本地 Markdown 工具链完全指南：从编辑器选型到 Ollama 本地部署

如果你的 Markdown 文件已经积累了好几百个，却还在用在线编辑器写，那你大概率遇到过这几个问题：图片外链失效、公式渲染慢、表格复制到 Word 直接乱掉、公司内部文档不方便传到云端。这次我们不追新工具，把本地写 MD 的选型和部署一次性理清楚。

从实际使用角度，一套合格的本地 Markdown 方案至少要满足五个条件：所见即所得、图片和附件走本地相对路径、支持数学公式、能批量处理文档、最好能接一个本地模型做写作辅助。下面不聊“哪个编辑器最好看”，而是直接按“怎么选、怎么装、怎么测、怎么排查”的顺序，把本地 Markdown 工具链讲明白。

文章会覆盖五部分：主流本地 Markdown 编辑器的核心能力对比、环境准备和安装步骤、公式/图片/表格/导出等功能的验证方法、批处理脚本示例，以及本地模型辅助写作的部署思路。

1. 核心能力速览

本地 Markdown 工具不只有一个编辑器，而是一条工具链。下表按“编辑器类、笔记类、博客渲染类、AI 辅助类”整理，方便快速对照。

需要说明：上表中的“适合人群”是通用判断，具体选择还要看你的操作系统、显存、写作文体和使用习惯。显存占用、安装时间等参数需要按实际环境测试，本文不会编造数字。

2. 适用场景与使用边界

这篇选型文章解决的是三类问题：

第一类是“编辑器选择困难”。本地 Markdown 编辑器非常多，有的偏向开发者，有的偏向笔记管理，有的只专注写作。如果你只是想把 Markdown 写顺手，任何一个主流工具都够用；如果你需要图片管理、公式渲染、批量导出，就需要组合使用。

第二类是“文档格式打通难”。很多人的痛点不是不会写 Markdown，而是写完后要发到公众号、CSDN、知乎，或者转成 Word 交给同事。本地 Markdown 方案可以配合 Pandoc、脚本模板，把这套流程固定下来，不用每次手动调格式。

第三类是“写作隐私和数据安全”。公司内部文档、客户方案、未发布的文章初稿，不太适合直接放到在线编辑器。本地工具把数据留在自己手里，同步与否自己控制，更稳妥。

不适合用本地 Markdown 的场景也要说清楚：

• 团队多人实时协同时，本地 Markdown 没有在线协作文档方便。
• 需要复杂排版（如多级页眉、专业公文格式）时，Word 更合适。
• 不愿意花时间维护工具链的用户，直接使用在线编辑器效率更高。
• 涉及他人肖像、人脸、声音、版权素材时，不能因为“本地部署”就放松授权审核，复制到任何平台前都需要确认来源和授权。

3. 本地 Markdown 环境准备与前置条件

Markdown 本质上就是纯文本，对硬件要求很低。但如果你要跑本地 AI 辅助模型、批量转换 PDF/Word、或者实时预览大型文档，还是需要检查一下环境。

3.1 操作系统与基础软件

3.2 GPU 与显存检查

如果你只写 Markdown，不跑本地模型，GPU 不是必需品。如果要接本地 AI 助手，建议先确认显卡型号和显存：8GB 显存可以尝试 7B 参数规模的量化模型，更大的模型需要更多显存，具体以实际测试为准。没有独立显卡的设备也可以跑 CPU 推理，但生成速度会慢很多。

3.3 目录规划

本地写 MD 最大的坑是文件乱。建议一开始就规划好目录：

code复制my-notes/
├── assets/          # 图片、附件、固定素材
├── drafts/          # 未完成文章
├── published/       # 已发布文章
├── templates/       # 模板文件
└── scripts/         # 批处理脚本

图片统一放到 assets/，正文里用相对路径引用，例如 ![](./assets/2025-01-01-example.png)。这样整个文件夹搬到哪里，图片都不会丢。

4. 安装部署与启动方式

下面按“VS Code 组合、桌面编辑器、Docker 启动笔记服务、静态博客渲染”四类给出通用安装步骤。具体命令中的路径、包名、版本号需要根据你的实际网络和平台调整。

4.1 VS Code 加 Markdown 插件

VS Code 是最稳妥的 Markdown 开发环境。不需要额外配置就能打开 .md 文件，并内置预览。建议安装以下插件：

• Markdown All in One：快捷键、目录生成、自动格式化。
• markdownlint：检查 Markdown 语法规范。
• Paste Image：粘贴截图时自动保存到指定目录。
• Markdown Preview Enhanced：增强预览，支持公式、导出 PDF。

安装命令：

bash复制# 在 VS Code 扩展面板中搜索插件名并点击安装
# 或者使用命令行安装，需要替换扩展ID
code --install-extension yzh.markdown-all-in-one
code --install-extension DavidAnson.vscode-markdownlint
code --install-extension mushan.vscode-paste-image
code --install-extension shd101wyy.markdown-preview-enhanced

启动方式：打开包含 Markdown 文件的文件夹，按 Ctrl+Shift+V 打开预览面板。右上角可以切换“侧边预览”和“全屏预览”。

4.2 桌面编辑器安装

Mark Text 的安装比较简单，各系统通用思路：

bash复制# Windows 下用 winget（部分工具可能不在源中）
winget install marktext

# macOS 下用 Homebrew
brew install --cask marktext

# Linux 下用 AppImage 或对应发行版的包

Typora 目前是商业收费软件，安装包从官网下载。是否购买根据个人需求决定，免费试用期和价格以官网为准。

Obsidian 和 Joplin 同样提供各平台安装包。其中 Joplin 可以提供命令行界面和桌面客户端，官方文档里有关键字“local”的相关说明，使用前建议先读一遍。

4.3 Docker 启动思源笔记

如果你喜欢笔记服务化、希望数据留在本机，可以尝试用 Docker 跑思源笔记。以下只是通用模板，具体镜像名和版本需要以思源笔记官方发布页为准：

bash复制# 先确认 Docker 已安装并启动
docker run -d \
  --name siyuan \
  -p 6806:6806 \
  -v /your/workspace:/home/siyuan/workspace \
  b3log/siyuan \
  --workspace=/home/siyuan/workspace

启动后浏览器访问 http://127.0.0.1:6806。端口号如果被占用，可以改成其他宿主机端口。

4.4 静态博客渲染

如果你追求“本地写 MD → 生成 HTML → 上线”的工作流，Hugo 是不错的选择。Hugo 是单个二进制文件，下载解压即可启动：

bash复制# 新建站点
hugo new site quick-site

# 进入目录，创建第一篇草稿
cd quick-site
hugo new posts/first-post.md

# 本地预览
hugo server -D --bind 127.0.0.1 --port 1313

浏览器访问 http://127.0.0.1:1313，就能看到实时渲染效果。-D 表示显示草稿，正式构建时去掉即可。

5. 功能测试与效果验证

装好工具之后，不要直接开始写长文，先花十分钟做一轮功能验证。下面按公式、图片、表格、导出四个维度给出测试方法。

5.1 数学公式测试

很多人的痛点不是写公式，而是写完公式在编辑器里渲染正常、一贴到平台就乱。先建一个测试文件，分别验证行内公式和块级公式。

markdown复制行内公式示例：$E = mc^2$。

块级公式示例：

$$
\int_{-\infty}^{+\infty} e^{-x^2} dx = \sqrt{\pi}
$$

大括号多行公式示例：

$$
f(x) =
\begin{cases}
x^2, & x \ge 0 \\
-x^2, & x < 0
\end{cases}
$$

判断标准：

• 预览中公式是否居中渲染。
• 公式中的 \begin{cases} 是否正常换行。
• 导出的 PDF/HTML 中公式是否完整。

如果块级公式不渲染，常见原因是编辑器没有启用 MathJax/KaTeX 支持，需要在设置里打开对应的公式渲染开关。

5.2 图片路径测试

图片路径是 Markdown 新手最容易踩的坑。测试步骤如下：

1. 在 assets 目录放一张测试图片。
2. 正文中写 ![](./assets/test.png)。
3. 分别测试：本地预览、导出 HTML、整个文件夹移动到另一个目录后是否仍能显示。

判断标准：换机器后图片依然正常显示。如果导出 HTML 后图片丢失，检查 HTML 文件与 assets 目录的相对位置是否一致。

VS Code 的 Paste Image 插件需要配置粘贴目录：

json复制{
  "pasteImage.path": "${currentFileDir}/assets",
  "pasteImage.basePath": "${currentFileDir}",
  "pasteImage.namePrefix": "${currentFileNameWithoutExt}-"
}

配置后截图直接粘贴，图片就会自动保存到当前文件同级的 assets 目录，并自动插入相对路径。

5.3 表格与列表测试

Markdown 表格在编辑器和平台之间的兼容性差异很大。测试文件可以先写一个包含合并单元格意图的复杂示例：

markdown复制| 功能 | 编辑器 A | 编辑器 B |
| --- | --- | --- |
| 公式 | 支持 | 不支持 |
| 图片相对路径 | 支持 | 支持 |
| 导出 Word | 通过插件 | 原生支持 |

判断标准：

• 预览中列对齐是否正常。
• 复制到目标平台后表格是否保留。
• 表格内如果包含 | 或特殊字符，是否需要用转义写法。

如果表格粘贴到 Word 后乱掉，优先走“Markdown → Pandoc → Word”的转换流程，而不是直接复制。

5.4 导出 PDF/Word 验证

导出是“写完怎么交付”的关键。推荐用 Pandoc 做转换，不依赖编辑器的导出功能：

bash复制# Markdown 转 Word
pandoc input.md -o output.docx --toc

# Markdown 转 PDF（需要 LaTeX 或 weasyprint 环境）
pandoc input.md -o output.pdf -V mainfont="Noto Sans CJK SC"

依赖安装：

bash复制# macOS
brew install pandoc

# Ubuntu / Debian
sudo apt update && sudo apt install pandoc

# Windows
winget install --id JohnMacFarlane.Pandoc

中文 PDF 的问题比较常见：直接导出可能出现中文乱码或空白。上面的命令指定了中文字体 Noto Sans CJK SC，如果你的系统里没有这个字体，需要换成已安装的中文字体名，或者用 weasyprint 作为 PDF 引擎。

5.5 长文稳定性测试

本地写 MD 最大的好处是稳。写长文时建议先创建一篇 3000 字以上的测试文档，包含标题层级、代码块、引用、多个图片，然后连续操作：频繁切换预览、快速滚动、长时间不保存后关闭软件再重开。

判断标准：

• 预览切换是否明显卡顿。
• 重新打开后内容是否完整。
• 图片资源是否有损坏。

如果遇到卡顿，优先把文档拆成多个文件，用“索引文档 + 子文档”的方式管理，而不是在一个文件里堆积上万字。

6. 批量任务与自动化工作流

本地 Markdown 的核心优势之一，就是可以用脚本批量处理。下面给三个高频场景：批量转 Word、批量检查图片引用、批量替换链接。

6.1 目录下批量转换 Markdown 为 Word

假设你的文章都在 published/ 目录，需要一个脚本扫描所有 .md 文件并输出到 docx/ 目录。下面是一个 Python 脚本示例：

python复制import subprocess
from pathlib import Path

source_dir = Path("published")
output_dir = Path("docx")
output_dir.mkdir(exist_ok=True)

for md_file in source_dir.rglob("*.md"):
    output_file = output_dir / f"{md_file.stem}.docx"
    subprocess.run(
        ["pandoc", str(md_file), "-o", str(output_file), "--toc"],
        check=True,
    )
    print(f"converted: {md_file.name}")

运行时安装依赖：

bash复制python -m pip install --upgrade pandoc

注意：pandoc 是独立程序，Python 包只负责调用，需要先安装 Pandoc 本体。

6.2 检查 Markdown 中的图片引用是否失效

写久了容易出“图片路径拼错、文件被移动”的问题。写一个简单的检查脚本：

python复制import re
from pathlib import Path

def check_images(md_file):
    content = md_file.read_text(encoding="utf-8")
    pattern = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
    for match in pattern.finditer(content):
        ref = match.group(1)
        if ref.startswith("http"):
            continue
        img_path = (md_file.parent / ref).resolve()
        if not img_path.exists():
            print(f"[缺失] {md_file.name}: {ref}")

for md_file in Path(".").rglob("*.md"):
    check_images(md_file)

运行方式：

bash复制python check_md_images.py

这个脚本会找出所有引用了本地图片但文件不存在的情况。如果你的图片路径有特殊字符或空格，正则部分需要按实际调整。

6.3 批量替换已发布文章中的旧链接

已经发布的文章经常需要批量更新链接。用 Python 做全局替换时，注意只替换 Markdown 链接部分，不要误改正文：

python复制from pathlib import Path
import re

old_url = "https://old.example.com"
new_url = "https://new.example.com"

def replace_links(md_file):
    content = md_file.read_text(encoding="utf-8")
    # 只匹配 Markdown 链接语法中的 URL 部分
    new_content = re.sub(
        rf"\(({re.escape(old_url)}[^)]*)\)",
        lambda m: m.group(0).replace(old_url, new_url),
        content,
    )
    if new_content != content:
        md_file.write_text(new_content, encoding="utf-8")
        print(f"已更新: {md_file}")

for md_file in Path("published").rglob("*.md"):
    replace_links(md_file)

批量操作强烈建议先跑一遍 git diff 或备份目录，避免不可逆的全局替换。

7. 本地 AI 助手与 Markdown 写作

热词里频繁出现“本地部署大语言模型”“ollama 本地部署”“本地部署 deepseek”，说明很多人已经不只是写 Markdown，而是希望配合本地模型做润色、摘要和续写。我给出一个相对稳妥的本地部署思路：Ollama + 本地模型 + 编辑器调用。

7.1 安装 Ollama

Ollama 是一款把大模型封装成本地服务的工具，官方提供命令行安装脚本。由于不同网络环境差异较大，安装时如果下载失败，优先查看官网文档的镜像或手动安装方案，而不是修改系统代理设置。macOS 和 Windows 均有桌面端安装包，Linux 用官方脚本：

bash复制# macOS / Windows 下载对应安装包
# Linux 官方脚本，注意确认来源
curl -fsSL https://ollama.ai/install.sh | sh

安装后启动服务并确认状态：

bash复制ollama --version
ollama serve

默认监听地址是 127.0.0.1:11434。启动成功后再拉取模型，例如中文能力表现相对成熟的量化模型：

bash复制ollama run qwen2.5:7b

模型参数大小、量化格式直接影响显存占用。7B 量化模型在 8GB 显存设备上可以尝试运行，具体速度以本机测试为准；设备显存不够时会退到 CPU 推理，速度会明显变慢。

7.2 调用本地模型接口

启动后，Ollama 会提供一个本地 HTTP 接口。可以用 curl 测试：

bash复制curl -X POST http://127.0.0.1:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "prompt": "帮我润色下面这段 Markdown 文案，保持技术风格：\n本地部署大语言模型时，显存占用是核心指标。",
    "stream": false
  }'

返回结果中通常包含 response 字段，就是模型生成的文本。Python 调用也是一样的思路：

python复制import requests

def chat(prompt, model="qwen2.5:7b"):
    url = "http://127.0.0.1:11434/api/generate"
    payload = {
        "model": model,
        "prompt": prompt,
        "stream": False,
    }
    response = requests.post(url, json=payload, timeout=180)
    return response.json().get("response", "")

print(chat("把这段文字改成适合 CSDN 发布的口吻：理解本地 Markdown 编辑器。"))

7.3 接进编辑器

VS Code 有一类基于 OpenAI 兼容接口的插件，可以把 Ollama 配置成“本地后端”。配置思路是：把模型服务地址填成 http://127.0.0.1:11434，模型名填成你本地拉取的模型名，然后选中文字让 AI 润色或续写。

这类接法有两个注意点：

• 本地模型的生成速度取决于显卡、显存、模型大小和上下文长度，不要用云端模型的体验来预期。
• 每次请求传输的内容都在本机内部完成，不需要担心文本上云，但仍需注意他人隐私内容不要随意输入到公开工具中。

7.4 本地 AI 的显存与硬件观察

这里只说观察方法，不给固定数字。启动模型后可以通过 nvidia-smi 实时查看显存占用：

bash复制# 每 2 秒刷新一次
nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv -l 2

重点观察：

• 模型加载后显存占用是否稳定。
• 生成长文本时显存是否持续增长。
• 多开对话时是否出现显存溢出。

如果显存占用过高，可以换更小规模的模型，或者限制上下文长度。设备只有 CPU 时也可以运行，但长文本生成会比较慢。

8. 资源占用与性能观察

本地 Markdown 的“资源占用”分成三块：编辑器本身、批处理任务、本地模型。

编辑器本身很轻量，VS Code 空闲时主要占用内存，Markdown 渲染基本不消耗 GPU。大型仓库、超长文档和大量插件会拉高内存占用，建议定期清理不再使用的扩展。

Pandoc 批量转换是短时 CPU 任务。转换大量文档时，占用会短暂升高，但完成后释放。如果转换过程中内存跟着涨，通常是大文档或复杂表格导致的，可以把单次转换拆分。

本地模型是唯一真正需要显存的部分。推荐的观察方法：

• 记录“空闲显存”和“加载模型后显存”的差值，这就是模型占用。
• 生成长文本时观察温度，笔记本用户要注意散热。
• 不要把显存全部占满，预留一点给系统界面和编辑器渲染。

降低占用有三个简单手段：选择更小模型、使用量化版本、控制并发请求数量。本地模型服务一般不需要并发，串行调用足够。

9. 常见问题与排查方法

这些问题的共同规律是：先确认“本地编辑器是否正常”，再确认“导出/发布链路是否正常”，不要一上来就重装软件。

10. 最佳实践与使用建议

本地 Markdown 工具链一旦稳定，就不要频繁更换。下面这些实践来自日常写作经验，可以直接复用。

第一，目录结构要提前定好。建议在项目根目录放一个 README.md 说明文档，里面写清楚“图片放哪里、草稿放哪里、发布后放哪里”。这样即使换机器、换编辑器，也能快速恢复习惯。

第二，正文使用相对路径引用图片，不写绝对路径。绝对路径在移动文件夹或同步到别的设备时会直接断裂。

第三，重要文档纳入版本管理。本地 Markdown 配合 Git 是最佳搭档，每次修改都有记录，批量替换也不会出事故：

bash复制git init
git add .
git commit -m "初始化 Markdown 笔记库"

第四，发布前做一次“渲染检查”。CSDN、微信公众号、知乎的 Markdown 方言并不完全一致。先在本地把公式、表格、代码块渲染一遍，再复制到目标平台，减少发布后调整格式的时间。

第五，使用模板文件。把常用的 front matter、目录结构、标签体系固定在一个模板里：

yaml复制---
title: ""
date: 2025-01-01
tags: []
categories: []
summary: ""
---

第六，关于 AI 辅助，要清楚边界。本地模型可以润色、缩写、续写，但涉及他人未公开内容、公司机密、客户方案时，仍然要谨慎。本地部署不等于可以忽略来源授权；涉及图片、人脸、声音、版权材料时，要确认自己有合法使用权利。

第七，控制单文件长度。一个 Markdown 文件超过 5000 行之后，编辑器的语法高亮和预览都可能变慢。建议单文件控制在单个章节的粒度，用目录或索引文件串联。

11. 总结与下一步

回到开头的问题：“本地写 MD 的神仙工具”到底存不存在？从我的使用经验看，不存在一个能覆盖所有场景的单一工具，但存在一套稳定组合：VS Code 负责编辑和写代码片段，桌面编辑器负责日常快速记录，Pandoc 负责格式转换，Ollama 加本地模型负责最后的润色与生成。这套组合的优势是数据完全可控、管道可编程、并且能随着你的需求扩展。

最先应该验证的功能是图片相对路径和公式渲染。这两项只要稳定，日常写作就不会断；如果这两项有问题，再好看的界面也没用。

最容易踩的坑是“编辑器能预览，但发布后公式/图片失效”。这不是编辑器的问题，而是你没有把“本地路径”和“远端发布”两套环境区分开。本地写 Markdown 时用相对路径，发布前换成图床链接或平台自有上传，这样最稳。

下一步可以按这个顺序推进：搭建目录结构 → 选一个主编辑器 → 用测试文档跑通公式和图片 → 配好 Pandoc 转换 → 写两个批处理脚本 → 再考虑接本地模型。整套流程跑通之后，本地写 Markdown 的效率会比在线编辑器高很多，而且不用担心内容被平台绑死。建议先把这套工具链搭起来，再按你本身的写作习惯慢慢微调。