本地 Markdown 写作完整指南：从工具选型到工作流搭建

写 Markdown 这件事，看起来简单，但真到落地时往往卡在一堆细节上：用什么编辑器、图片怎么存放、预览效果和线上不一致、HTML 老文档怎么转成 md、离线环境里还能不能顺畅写作。本文围绕“本地写 MD”这条主线，整理一套从工具选型、环境配置到 HTML 转 Markdown、本地预览、图片管理、常见排错的完整方案。不管你是刚开始接触 md 文件格式，还是已经在维护技术文档库，跟着这篇文章把本地写作流程搭起来，后面写文章、记笔记、做项目文档都会顺手很多。

1. 为什么要在本地写 Markdown

1.1 Markdown 文件格式的本质

Markdown 是一种轻量级标记语言，用纯文本来表达文章结构。你不需要像 Word 那样去点工具栏按钮，而是直接用 #、-、[文本](链接) 这类符号完成标题、列表、链接和代码块的排版。所有内容都保存在后缀为 .md 的普通文本文件中，没有私有格式，也没有隐藏的 XML 结构。

下面是一份典型 Markdown 文件的原始内容：

markdown复制# 项目标题

## 背景

这是一个示例段落，包含**加粗**和[链接](https://example.com)。

- 任务一
- 任务二

~~~bash
echo "hello md"
~~~

从技术角度解释，Markdown 做的事情是把“内容表达”和“排版结构”分离：你写的是纯文本，但通过约定好的标记语法，任何支持 Markdown 的渲染器都能把它转换成 HTML、PDF 或带样式的网页。正因为文件本身是纯文本，它不会被绑定在某一家软件的数据格式里。十年以后软件可能换了好几代，但你的 md 文件用记事本打开还能看到全部正文，这一点非常关键。

1.2 本地工具相对于在线编辑器的优势

在线编辑器很香，打开浏览器就能写，实时保存，团队协同也方便。但很多场景下，本地工具才是更可靠的方案：

• 离线可用。地铁、飞机、内网环境，只要本地文件还在，就能继续写。
• 数据掌握在自己手里。文档不会因为平台调整、账号异常或者网络问题而丢失。
• 和 Git 天然搭配。每次修改都能形成提交记录，错了可以回滚，多人维护时也方便审阅。
• 自动化能力强。批量替换图片路径、批量转换 HTML、统一排版风格，这些都可以用本地脚本完成。
• 样式完全可控。预览用的 CSS 可以按自己的博客或文档站风格定制。
• 可以和本地大模型配合。如果你在 Ollama、LM Studio 这类工具里跑着本地模型，就能在写作时让模型润色段落，而不需要把文档内容上传到第三方服务。

在线工具也有自己的优势，例如团队实时协同和跨设备自动同步。所以这篇文章并不是完全否定在线方案，而是想强调：当你开始在意离线可用、内容隐私和长线维护时，本地 md 工具是绕不开的方向。

1.3 哪些场景必须用本地 MD 工具

结合日常开发工作，下面几类场景几乎是“必须用本地 MD 工具”的：

• 内网开发环境。公司内网隔离，访问在线编辑器不稳定甚至根本不可用。
• 静态博客写作。Hexo、Hugo、VitePress 这类站点生成器的输入就是本地 Markdown 文件，写完再构建发布。
• 项目文档维护。README、接口说明、架构设计文档直接放在 Git 仓库里，用 md 文件承载最合适。
• 私有知识库积累。个人技术笔记、面试题整理、研究记录，这些内容往往不适合上传到在线服务。
• 频繁插入本地截图。技术文章经常需要截图，本地编辑器可以把图片直接粘贴到项目目录，路径可控，不需要先上传图床。

这些场景的共同点是什么？文件必须是普通文件，内容必须可控，编辑过程要支持离线完成。这也是后面所有工具选择和配置方案的设计前提。

2. 挑选本地 MD 工具的原则与主流工具对比

2.1 核心选择标准

很多人选 Markdown 编辑器只看“长得好看不好看”，但真正长期使用时会发现，考虑维度要更多一些：

• 编辑体验。快捷键是否顺手，代码块插入是否方便，表格编辑是否友好，中文输入法有没有奇怪的兼容问题。
• 预览体验。是否支持分屏实时预览，滚动是否同步，能否自定义主题，能否直接导出 PDF 或 HTML。
• 扩展能力。插件生态是否成熟，能不能运行自定义脚本，能否配置 lint 规则来保持文档规范。
• 资源管理。粘贴图片后图片文件保存在哪里，插入的路径是相对路径还是绝对路径，多篇文章时图片怎么归类。
• 跨平台能力。如果你经常在 Windows 和 macOS 之间切换，配置文件和插件是否容易同步。

没有一款工具能在所有维度拿到满分。写技术博客的人更看重预览和扩展能力；做知识库管理的人更看重双链和检索；偶尔写一点 md 的人只需要轻量编辑。先明确自己的核心场景，再选工具。

2.2 主流工具横向对比

这张表的价值是帮你确认方向。如果你主要写技术文档和博客，强烈建议尝试 VS Code 加 Markdown Preview Enhanced；如果你在积累大量个人笔记、希望建立知识网络，Obsidian 更适合；如果你喜欢打开就是一张白纸、完全不想看到源码标记，Typora 或 MarkText 会更顺手。

2.3 工具选型不是终点，工作流才是

很多朋友不停地在编辑器之间切换，问题其实不在编辑器，而在没有一套固定工作流。真正能提升效率的是一套完整链路：新建 md 文件、本地截图自动命名、分屏预览、Git 提交、构建发布。编辑器只是这套流程的载体。

后面我会以 VS Code 作为主线，搭配 Pandoc 做 HTML 转 Markdown，配合本地脚本处理图片路径，再补充静态站点预览方案。这套组合适合大多数写技术文档的开发者，并且可以灵活替换其中任意一环。

3. 环境准备与版本说明

3.1 操作系统与基础软件

本文示例以 Windows 10/11 和 macOS 主流版本为例，Linux 上的思路完全一样。涉及软件版本时，建议安装官网提供的最新稳定版，或者跟随团队既有项目固定版本。不要盲目追求最新版本，稳定性和兼容性在文档工作中更重要。

需要准备的基础软件有：

• 一个文本编辑器。推荐 VS Code，已经习惯了 Sublime Text 或其他工具也没关系，思路通用。
• Git。用于本地文件版本管理，后文几乎所有“写坏了还能回滚”的操作都依赖它。
• Pandoc。通用文档转换器，主要用来把 HTML、Word 等格式转成 Markdown，或反向导出。
• 可选：Node.js 运行环境。只有当你要跑 VitePress、Hexo 这类静态站点生成器时才需要。

Git 在 Windows 上安装后会提供 Git Bash，后文部分 bash 脚本可以直接在 Git Bash 里运行。Node.js 如果暂时用不到，可以等需要搭建文档站时再安装，不用一开始就把环境搞得很重。

3.2 安装 VS Code 与推荐插件

VS Code 安装完成后，打开扩展面板，重点搜索安装以下几个插件：

• Markdown Preview Enhanced。本地 Markdown 预览增强插件，支持分屏、滚动同步、自定义样式、Pandoc 导出。
• Markdown All in One。提供常用快捷键、目录生成、列表处理等能力。
• markdownlint。检查 md 文件里的语法问题和排版问题，适合维护规范性文档。
• Paste Image。粘贴截图时自动把图片保存到项目目录，并生成相对路径插入到 md 中。

其中前两个插件也可以用命令行安装：

bash复制code --install-extension yzh.markdown-preview-enhanced
code --install-extension davidanson.vscode-markdownlint

其他插件在扩展商店里按名称搜索安装即可。插件安装完成后，建议重启一次 VS Code，避免扩展加载不完整。不同插件在不同版本下界面措辞可能有差异，但核心功能基本一致。

3.3 安装 Pandoc

Pandoc 是一个开源文档转换器，能在 Markdown、HTML、Word、PDF 等多种格式之间互相转换。安装方式取决于操作系统：

• macOS：推荐使用 Homebrew，执行 brew install pandoc。
• Windows：可以使用 winget 或 Chocolatey 搜索安装，也可以直接去官网下载安装包。
• Linux：可以通过 apt install pandoc 或 dnf install pandoc 安装，具体包名跟随发行版。

不同系统的包管理器包名可能有差异，建议安装前查一下对应官方文档。安装完成后，在终端执行 pandoc --version，能正常输出版本信息就说明环境就绪。如果团队项目里有固定的 Pandoc 版本要求，建议优先使用与 CI 环境一致的版本，避免同一份 HTML 在不同机器上转换出不同结果。

4. 从 HTML 到 MD：批量转换实操

4.1 单个 HTML 文件转 Markdown

如果你手头有一批旧网页文档需要整理到 Markdown 体系里，Pandoc 是最省力的工具。单文件转换命令：

bash复制pandoc input.html -t gfm -o output.md

参数含义：

• input.html：输入文件路径。
• -t gfm：指定输出格式为 GitHub Flavored Markdown。GFM 是 GitHub 风格 Markdown，支持表格、任务列表等扩展，非常适合技术文档。
• -o output.md：输出文件路径。

转换完成后打开 output.md，标题、段落、列表基本都会保留。如果原 HTML 里有大量内联样式和 div 标签，Pandoc 会尝试降级为普通文本，但免不了有一些残留，需要后续清理。

4.2 批量转换目录中的 HTML 文件

文档数量一多，单个命令就不够用了。批量转换的思路是写一个循环脚本，遍历目录下所有 HTML 文件，逐个调用 Pandoc。先看 bash 版本：

bash复制for f in *.html; do
  pandoc "$f" -t gfm -o "${f%.html}.md"
  echo "converted: $f"
done

脚本注意事项：

• *.html 会把当前目录下所有 HTML 文件作为循环变量 $f 依次处理。
• "$f" 加双引号是防止文件名包含空格时被拆成多个参数。
• ${f%.html}.md 是 Shell 参数展开，去掉 .html 后缀后拼接 .md。例如 index.html 会变成 index.md。

Windows 下使用 PowerShell 的写法：

powershell复制Get-ChildItem -Filter *.html | ForEach-Object {
    pandoc $_.FullName -t gfm -o ($_.BaseName + ".md")
    Write-Host "converted: $($_.Name)"
}

这段命令会遍历当前目录下所有 HTML 文件，通过 BaseName 获取不含扩展名的文件名，再拼接 .md 输出。批量转换前建议先备份原始 HTML 目录，确认转换结果满意后再清理。转换结果可能有样式残留、空行过多或表格错位，属于正常现象。

4.3 转换后的批量清理脚本

Pandoc 不是万能的，HTML 中常见的 div、span 以及内联样式会被原样带进 Markdown，虽然不影响阅读但会影响整洁度。这里可以写一个小型 Python 脚本做二次清理。新建 clean_md.py 文件：

python复制import re
from pathlib import Path

def clean_md(file_path: Path) -> None:
    text = file_path.read_text(encoding='utf-8')
    # 去掉残留的 div 标签
    text = re.sub(r'<div[^>]*>', '', text)
    text = re.sub(r'</div>', '', text)
    text = re.sub(r'<span[^>]*>', '', text)
    text = re.sub(r'</span>', '', text)
    # 将连续三个以上空行压缩为两个空行
    text = re.sub(r'\n{3,}', '\n\n', text)
    file_path.write_text(text, encoding='utf-8')

if __name__ == '__main__':
    for md_file in Path('.').glob('*.md'):
        clean_md(md_file)
        print(f'cleaned: {md_file.name}')

执行方式：

bash复制python clean_md.py

脚本的逻辑很简单：通过正则去掉常见 HTML 标签，再把多个空行合并成两个空行。清理后打开文件人工检查一遍，重点看标题层级、列表缩进和代码块围栏是否完整。正则表达式能处理的只是简单残留场景，碰到复杂 HTML 还是需要手动调整。

5. 本地预览与浏览器环境：配置一套可复用的预览方案

5.1 为什么需要单独的预览配置

很多编辑器打开 md 文件后默认只显示源码，新手写完后想看效果还要切到其他工具，非常打断思路。分屏预览才是写作效率的关键：左边写源码，右边看渲染结果，标题层级、图片、代码块一眼就能发现问题。所以“本地写 MD”不只是找一个能打字的编辑器，还要把预览、图片、导出这些环节串起来。

5.2 VS Code 工作区配置

在项目根目录创建 .vscode/settings.json，写入以下配置：

json复制{
  "markdown-preview-enhanced.previewTheme": "github-light.css",
  "markdown-preview-enhanced.codeBlockTheme": "solarized-light.css",
  "markdown-preview-enhanced.enableScriptExecution": false,
  "pasteImage.path": "${projectRoot}/assets/img",
  "pasteImage.namePrefix": "",
  "pasteImage.insertPattern": "![${imageFileName}](${imageFilePath})"
}

逐项说明：

• previewTheme：预览主题，这里选择 GitHub 风格，比较接近线上博客的阅读体验。
• codeBlockTheme：代码块主题，和预览主题独立设置。
• enableScriptExecution：是否允许预览页面执行脚本。建议保持关闭，避免本地文档被恶意脚本影响。
• pasteImage.path：粘贴截图时图片的保存目录，${projectRoot} 代表当前项目根目录。
• pasteImage.namePrefix：图片文件名前缀，留空则按时间戳自动命名。
• pasteImage.insertPattern：插入图片到 md 文件中的格式模板，${imageFileName} 和 ${imageFilePath} 是 Paste Image 插件提供的变量。

配置完成后，在 md 文件里按 Ctrl+Shift+P（macOS 是 Cmd+Shift+P）调出命令面板，输入 Markdown Preview Enhanced: Open Preview，即可打开分屏预览。左侧编辑，右侧实时刷新，体验很接近在线编辑器。

5.3 浏览器直接打开本地 MD 文件

有时候你不想启动大型编辑器，只想快速在浏览器里看一眼 md 文件。可以给 Chrome 或 Edge 安装 Markdown Viewer 一类的扩展，并在扩展详情里开启“允许访问文件 URL”，然后把 .md 文件拖拽到浏览器窗口就能完成渲染。

不同的浏览器扩展配置差异比较大，建议以扩展自身说明为准。如果你不希望依赖浏览器扩展，更稳定的方式是项目里跑一个静态站点服务。以 VitePress 为例，安装依赖后执行本地开发命令，浏览器访问 localhost 地址就能看到渲染好的文档页面。这种方式适合真正在维护文档站的人，主题和组件都能自定义。

5.4 mac 上 Sublime Text 预览 MD 的补充

习惯使用 Sublime Text 的话，可以通过 Package Control 安装 Markdown Preview 插件。安装后打开一个 md 文件，在命令面板执行 Markdown Preview: Preview in Browser，或者使用 Save to HTML 输出静态文件。

整体体验比不上 VS Code 的 Markdown Preview Enhanced，但优点是启动快、够轻。需要留意两个坑点：一是预览前记得先保存文件，否则浏览器看到的是旧内容；二是默认样式比较简单，想要更好看的排版，需要手动指定一个 CSS 文件。如果你的写作场景只要求“快速看效果”，Sublime Text 的插件方案也够用。

6. 本地 MD 工作流实战：从写作到发布

6.1 典型文档项目结构

用一个实际技术博客文档项目举例，目录结构可以这样组织：

text复制blog/
├── docs/
│   └── posts/
│       └── 2025-04-local-markdown-workflow.md
├── assets/
│   └── img/
│       └── 2025-04-local-markdown-workflow/
│           └── demo.png
├── scripts/
│   └── fix_images.py
├── .vscode/
│   └── settings.json
└── README.md

设计思路很简单：

• docs/posts 放文章正文。
• assets/img 统一放图片，图片按文章名再建一层目录，避免不同文章之间的同名图片互相覆盖。
• scripts 放自动化脚本，例如图片路径修复、批处理转换。
• .vscode 保存工作区配置，团队克隆仓库后能获得一致的编辑器设置。

这样拆分的好处是文章和图片分开管理，提交 Git 时不会被大量二进制图片拖慢，以后迁移到其他静态站点生成器时只需要调整资源路径规则。

6.2 图片路径标准化脚本

本地写 md 最头疼的问题之一，是粘贴截图之后图片路径可能变成 C:\Users\你的用户名\assets\img\xxx.png 或者 /Users/你的用户名/assets/img/xxx.png。这种绝对路径一旦仓库被其他人克隆，图片全部失效。

可以写一个 Python 脚本来统一修正。新建 scripts/fix_images.py：

python复制import re
from pathlib import Path

def fix_image_paths(md_file: Path, image_dir: str = 'assets/img') -> None:
    text = md_file.read_text(encoding='utf-8')
    pattern = r'!\[([^\]]*)\]\(([^)]+)\)'

    def repl(match):
        alt_text = match.group(1)
        src_path = match.group(2)
        # 判断是否包含本地盘符或 Unix 根路径
        if ':/' in src_path or ':\\' in src_path or src_path.startswith('/'):
            filename = Path(src_path).name
            return f'![{alt_text}]({image_dir}/{filename})'
        return match.group(0)

    md_file.write_text(re.sub(pattern, repl, text), encoding='utf-8')

if __name__ == '__main__':
    for md_file in Path('docs').rglob('*.md'):
        fix_image_paths(md_file)
        print(f'fixed: {md_file}')

使用时先确认图片已经统一放在 assets/img 目录下，再执行 python scripts/fix_images.py。脚本会扫描 docs 目录下的所有 md 文件，只替换包含盘符或根路径的图片引用，替换成 assets/img/文件名 这样的相对路径。

这个脚本的核心价值不是正则写得完美，而是把“路径规范化”从手工操作变成可重复执行的命令。以后每次移动仓库或克隆新机器，跑一遍脚本就能修复大部分图片路径问题。

6.3 接入本地 AI 辅助写作（可选）

如果你已经在本地跑 Ollama、LM Studio 这类开源大模型服务，可以把 Markdown 写作流程和本地模型结合起来。常见用法有三种：

• 选中 md 文件里的某个段落，发送给本地模型润色或扩写。
• 让本地模型按固定模板生成文档初稿，再人工修改。
• 批量检查多个 md 文件的标题层级、段落结构和行文风格，发现不统一的地方。

这类工具通常会在本地开启一个 HTTP API，VS Code 也有很多插件支持连接本地模型。配置方式需要看具体插件的文档，这里不展开部署细节，因为本地大模型部署是另一个完整主题。需要记住的是：本地模型方案的价值在于内容不出本机，所以不要在这种方案里再硬套第三方云服务，否则就失去了本地写作的隐私优势。

7. 常见问题与排查思路

7.1 高频问题速查表

7.2 图片不显示怎么排查

本地预览里图片裂开，不要先怀疑编辑器，绝大多数情况是路径问题。按顺序排查四步：

1. 打开 md 源码看图片路径。如果出现 C:\Users 或 /Users 这样的绝对路径，基本可以确定问题所在。
2. 确认图片文件真实存在于路径对应的位置。注意文件名大小写、中文名和空格，Windows 下中文文件名通常没问题，但部署到 Linux 环境时大小写和编码都会成为隐患。
3. 把绝对路径改成相对路径，例如 assets/img/demo.png，前提是 md 文件和 assets 目录的相对位置正确。
4. 刷新预览页面。如果还是不行，重启一次 VS Code 窗口，因为插件可能缓存了目录信息。

如果改完路径还是显示不出来，可以打开预览页面的开发者工具，看图片请求的具体报错。一般能看到 404 或者路径拼接错误，定位起来比盲目猜测快得多。

7.3 预览脚本执行被浏览器拦截

Markdown Preview Enhanced 默认会阻止一部分本地脚本执行。如果你打开预览时看不到样式，或者页面弹出安全警告，先打开开发者工具查看控制台报错。一个通用排查办法是临时换成内置主题，把 previewTheme 从自定义主题改成默认主题，确认是不是 CSS 文件路径写错。如果项目中放了自己的 CSS，检查一下路径大小写、文件夹层级有没有拼错。

enableScriptExecution 这个配置项也要注意。如果某个文档引用了需要脚本的复杂组件，预览无效果时可以临时打开它调试，但要记住排查完之后改回 false，不要让所有文档都默认执行脚本。

7.4 Pandoc 转换预期与实际情况不一致

HTML 转 Markdown 本质是有损转换。HTML 里的复杂布局、表格嵌套、内联样式，转换后只能落成 Markdown 能表达的内容。遇到表格错位、样式丢失、嵌套列表被拍平的情况，先检查原始 HTML 是否足够干净，而不是责怪 Pandoc。

不要追求 100% 还原。Markdown 的目标是可读、可维护、可版本管理，不是像素级还原页面。转换后人工 review 是正常流程。如果转换需求很频繁，建议建立一套自己的 HTML 模板规范，从源头减少 <div> 和 style 的使用，转换出来的 md 质量会明显提升。

8. 最佳实践与工程建议

8.1 文件与目录规范

本地 Markdown 项目长期维护，最怕的是每个人风格不一样、目录混乱。建议一开始就固定以下规则：

• 文件名统一使用小写英文、数字和连字符，例如 local-md-workflow.md，避免空格和中文在跨平台时出问题。
• 图片目录统一为 assets/img，复杂文章再按文章名分一层子目录。
• 一篇文章只出现一个一级标题，其余标题从二级开始，避免站内目录结构混乱。
• 代码块必须标注语言类型，Markdown 解析器才能正确高亮。
• 相对链接优先于绝对链接，方便整个仓库整体迁移。

这些规范不用很长，几十行 Markdown 就能写完。重点是能够执行、能够检查，而不是停留在口头上。

8.2 Git 版本管理与备份

本地 md 写作最值得养成的习惯，是用 Git 做版本管理。简单流程是：

bash复制git add docs/ assets/
git commit -m "docs: 完成本地 Markdown 工作流文章初稿"

提交信息建议带 docs: 前缀，方便以后筛选历史记录。每次写完一个小节就提交一次，不需要等整篇文章完成再一次性提交。这样做的好处是，就算某一段改乱了，也能精准回到上一个可用版本。

归档类文档可以定期推送到远程私有仓库，或者打包备份到公司规定的存储位置。这里要特别注意：推送前必须确认目标仓库的可见范围和权限，不要把内部文档误推到公开仓库。涉及敏感文档时，更推荐使用离线备份或私有 Git 服务，遵守最小权限原则。

8.3 安全与隐私边界

本地 Markdown 的一个重要优势，是敏感内容不需要上传到第三方平台。在线编辑器虽然方便，但你无法完全控制服务端如何处理文档内容。本地编辑器至少在断网时能继续工作，内容不会自动扩散到外部。

日常使用中建议做好几点：

• 优先选择开源、离线可用的编辑器。
• 关闭编辑器“自动同步到云端”这类默认行为。
• 不要在文档里粘贴长期有效的私密令牌、生产数据库连接串。
• 文档确实需要写敏感信息时，使用环境变量或占位符，正式发布前再替换。

这些习惯看起来琐碎，但能避免很多风险。文档管理不是只关心格式和工具，更要关心内容在什么范围内流转、谁能看到、谁能修改。

8.4 让文档长期可维护

Markdown 的优势是轻量和快速，但如果没有约束，很快也会变成一堆风格混乱的文件。建议维护一份团队内部或者个人使用的写作规范，固定这些内容：标题层级写法、图片命名规则、代码块语言标注要求、词语风格、文章开头模板。

配合 markdownlint 的自动检查，可以在提交之前发现大部分格式问题。规范不用写得像论文，能落地、团队成员愿意遵守才是关键。等工具和工作流固定下来，写 md 就不再是“找工具”的问题，而是“持续产出内容”的问题。

如果你刚好也在找本地写 MD 的顺手工具，建议从安装 VS Code 和 Markdown Preview Enhanced 开始，配好 settings.json，然后写一篇一百行左右的短文，把新建文件、插入截图、分屏预览、Git 提交的完整链路跑通。工具只有自己用过一遍，才知道哪里顺手、哪里有坑。希望这套方案能帮你把本地写作流程稳定下来。