将Markdown转换为Word文档-支持代码块与GIF动图

一、为什么需要将Markdown转换为Word？二、解决方案概述三、完整操作指南1、环境准备：创建Docker容器2、安装必要依赖3、设置横向页面布局4、执行转换命令
四、转换效果说明五、常见问题处理六、总结

本文介绍如何将Markdown文档转换为Word格式，并保留代码高亮、GIF动图等特殊元素。

一、为什么需要将Markdown转换为Word？

Markdown作为一种轻量级标记语言，深受开发者和技术写作者喜爱。然而，在实际分享和协作过程中，我们常常面临以下需求：

跨平台分享需求：微信等社交平台对Word文档的支持比Markdown更好非技术读者需求：许多读者更习惯阅读Word格式的文档格式保留需求：需要保留代码块、图片、GIF等特殊元素的原始格式打印和排版需求：Word提供更精细的打印控制和排版选项

二、解决方案概述

我们使用Pandoc作为核心转换工具，它是一个强大的文档格式转换器。为了处理Mermaid图表等高级元素，我们额外使用pandoc-mermaid-selenium-filter插件，通过Chrome浏览器渲染这些特殊元素。

三、完整操作指南

1、环境准备：创建Docker容器

我们使用Docker容器确保环境一致性，避免影响本地系统。


# 创建一个Ubuntu 22.04容器，并将当前目录挂载到容器的/home目录
docker run -it --privileged --net=host 
    -v $PWD:/home -w /home --name pandoc ubuntu:22.04 /bin/bash

参数解释：

--privileged：给予容器特殊权限（用于浏览器渲染）-v $PWD:/home：将当前目录挂载到容器的/home目录-w /home：设置工作目录为/home--name pandoc：为容器命名为”pandoc”

2、安装必要依赖

在容器内执行以下命令安装所需软件：


# 更新软件包列表并安装基础工具
apt update
apt install python3.10 python3-pip -y
apt install pandoc -y
apt install unzip -y
apt install wget -y

# 安装Chrome浏览器依赖库
apt install libnss3-dev -y
apt install libatk1.0-dev -y
apt install libatk-bridge2.0-dev -y
apt install libcups2 -y
apt install libxkbcommon-dev -y
apt install libxcomposite1 -y
apt install libxdamage1 -y
apt install libxrandr2 -y
apt install libgbm1 -y
apt install libpango1.0-dev -y
apt install libasound2 -y

# 安装pandoc过滤器用于处理Mermaid图表
pip3 install pandoc-mermaid-selenium-filter

# 下载并安装Chrome浏览器（用于渲染图表）
wget -O /tmp/chrome-linux64.zip 
    https://storage.googleapis.com/chrome-for-testing-public/114.0.5735.90/linux64/chrome-linux64.zip
unzip -d /usr/local/ /tmp/chrome-linux64.zip
export PATH=/usr/local/chrome-linux64/:$PATH

3、设置横向页面布局

默认的Word文档是纵向布局，但对于代码块和图表，横向布局通常更合适。创建页面布局配置文件：


cat > custom-page.xml << 'EOF'
<w:sectPr>
    <w:pgSz w:w="16838" w:h="11906" w:orient="landscape"/>
    <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="708" w:footer="708" w:gutter="0"/>
</w:sectPr>
EOF

参数说明：

w:orient="landscape"：设置页面为横向布局w:w和w:h：定义页面尺寸（单位：twip，1/1440英寸）w:pgMar：设置页面边距

4、执行转换命令

现在可以使用以下命令将Markdown转换为Word文档：


pandoc input.md 
    --filter pandoc-mermaid-selenium-filter 
    --highlight-style breezeDark 
    --include-in-header=custom-page.xml 
    -o output.docx

参数详解：

input.md：输入的Markdown文件--filter pandoc-mermaid-selenium-filter：使用过滤器处理Mermaid图表--highlight-style breezeDark：设置代码高亮样式为暗色主题--include-in-header=custom-page.xml：包含自定义页面布局-o output.docx：指定输出文件名