Chapter 09 / 10

Markdown 工具链

从编辑器到文档站框架，从格式转换到知识库管理——覆盖完整的 Markdown 工作流

编辑器选择

选择合适的编辑器是高效写 Markdown 的第一步。不同的使用场景需要不同的工具。

VS Code — 开发者首选

Visual Studio Code 是开发者写 Markdown 的首选，内置了基本 Markdown 支持，通过插件可以大幅增强体验。

内置 Markdown 功能

推荐插件详解

Markdown All in One（最推荐）
最全功能插件：① 自动补全标题、链接、图片；② Alt+Shift+F 格式化（含表格对齐）；③ Ctrl+B/I 快捷键加粗/斜体；④ 自动生成目录（TOC）；⑤ 列表行 Tab/Shift+Tab 缩进/提升；⑥ 数学公式预览；⑦ 导出 HTML
markdownlint
实时检查 Markdown 格式规范，波浪线标注不规范写法，悬停查看规则说明。支持 .markdownlint.json 自定义规则配置。可以在 CI 中集成做格式检查。
Markdown Preview Enhanced
增强版预览：支持 Mermaid、PlantUML、数学公式、代码块执行（Jupyter 风格）、导出 PDF/HTML/PNG。比内置预览功能更强，但较重。
Paste Image
截图后直接 Ctrl+Alt+V 粘贴，自动将剪贴板中的图片保存为 PNG 文件并插入 ![](./images/xxx.png) 语法。写笔记时极其方便。
Foam（类 Obsidian 体验）
在 VS Code 中实现 Obsidian 的双向链接功能：[[文件名]] 链接、关系图谱可视化、命令快速创建新笔记。适合希望在 VS Code 中管理知识库的用户。

VS Code Markdown 常用快捷键

快捷键（Mac / Windows）功能
⌘⇧V / Ctrl+Shift+V打开 Markdown 预览
⌘K V / Ctrl+K V并排打开预览
⌘B / Ctrl+B加粗选中文字（需 Markdown All in One）
⌘I / Ctrl+I斜体选中文字
Alt+Shift+F格式化文档（表格对齐等）
Ctrl+Shift+[ / ]降低/提升标题级别
⌘/ / Ctrl+/注释（HTML 注释）

Typora — 所见即所得编辑器

Typora 采用"所见即所得"（WYSIWYG）模式：输入 Markdown 语法后立即渲染为最终效果，无需切换预览面板。

Typora 的核心特点

Typora vs VS Code 的选择

特征TyporaVS Code + 插件
写作体验更流畅（WYSIWYG）传统源码编辑
对程序员友好一般极好（熟悉的环境）
与代码文件的结合弱强（同一 IDE）
Git 集成无（需外部工具）内置 Git 面板
扩展性有限强（数千扩展）
价格约 89 元（一次性）免费

Obsidian — 知识库管理

Obsidian 是基于 Markdown 的本地知识管理工具，其核心特色是"双向链接"（Backlinks），可以构建笔记间的关系网络。

双向链接原理

在 Obsidian 中，用 [[文件名]] 创建链接：

# 笔记 A 中
学习 Python 时，我发现 [[数据结构]] 很重要。
[[算法基础]] 也需要系统学习。

# 自动效果
# 打开"数据结构"笔记时，可以看到"反向链接"
# 列出所有链接到它的笔记（包括笔记 A）
# 这就是"双向链接"：A 链接 B，B 也知道被 A 链接

Obsidian 特有语法

语法功能
[[笔记名]]内部链接（双向链接）
[[笔记名|显示文字]]带别名的内部链接
[[笔记名#章节]]链接到特定章节
![[笔记名]]嵌入其他笔记的全部内容
![[笔记名#章节]]嵌入其他笔记的特定章节
![[图片.png|200]]嵌入图片并指定宽度
#标签 / #父标签/子标签标签（支持层级）
> [!note] 标题Callout 告警块

推荐插件

核心增强插件

  • Dataview：将笔记作为数据库查询
  • Templater：强大的模板引擎
  • Calendar：日历视图 + 每日笔记
  • Tasks：任务管理和查询

可视化插件

  • Excalidraw：手绘风白板
  • Canvas：内置白板功能
  • Mind Map：思维导图视图
  • Charts View：图表可视化

Pandoc — 格式转换神器

Pandoc 是"文档转换界的瑞士军刀"，可以将 Markdown 转换为几乎任何文档格式（反之亦然）。

安装

# macOS
brew install pandoc

# Ubuntu/Debian
apt install pandoc

# Windows（推荐使用官方安装包或 winget）
winget install pandoc

基本转换命令

# Markdown → HTML
pandoc README.md -o README.html

# Markdown → HTML（带独立页面，含 CSS）
pandoc README.md --standalone -o README.html

# Markdown → PDF（需要安装 TeX 环境）
pandoc README.md -o README.pdf

# 使用 wkhtmltopdf 引擎导出 PDF（不需要 TeX）
pandoc README.md -o README.pdf --pdf-engine=wkhtmltopdf

# Markdown → Word 文档
pandoc README.md -o README.docx

# Markdown → EPUB（电子书）
pandoc book.md -o book.epub

# Markdown → 幻灯片（Reveal.js）
pandoc slides.md -t revealjs -s -o slides.html

YAML Front Matter 与 Pandoc

Pandoc 支持 YAML Front Matter，用于设置文档元数据：

---
title: "Pandoc 转换指南"
author: "张三"
date: "2026-03-26"
fontsize: 12pt
geometry: "margin=1in"
toc: true       # 是否生成目录
numbersections: true  # 是否给标题编号
---

# 正文从这里开始...
# 使用模板转换（自定义 PDF 样式）
pandoc report.md \
  --template=my-template.tex \
  --pdf-engine=xelatex \
  -V mainfont="PingFang SC" \
  -o report.pdf

# 批量转换整个目录
for f in docs/*.md; do
  pandoc "$f" -o "out/${f%.md}.html"
done
TIP（Pandoc + GitHub Actions 自动化）在 CI 中用 Pandoc 自动将 Markdown 文档转换为 PDF，随每次提交更新，团队始终有最新版本的 PDF 文档可以下载。这对需要打印版技术文档的团队非常实用。

MkDocs — Python 文档站

MkDocs 将一组 Markdown 文件构建成静态文档网站，主题 Material for MkDocs 是业内最受欢迎的文档主题之一。

快速上手

# 安装 MkDocs 和 Material 主题
pip install mkdocs mkdocs-material

# 创建新项目
mkdocs new my-docs
cd my-docs

# 启动本地预览服务器（热重载）
mkdocs serve
# 打开 http://localhost:8000

# 构建静态网站（输出到 site/ 目录）
mkdocs build

# 一键部署到 GitHub Pages
mkdocs gh-deploy

mkdocs.yml 完整配置示例

site_name: 我的项目文档
site_url: https://myuser.github.io/myproject
site_author: 张三
repo_url: https://github.com/myuser/myproject
repo_name: myuser/myproject
edit_uri: blob/main/docs/

theme:
  name: material
  language: zh
  palette:
    - scheme: default      # 浅色主题
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色
    - scheme: slate        # 深色主题
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色
  features:
    - navigation.tabs      # 顶部标签页导航
    - navigation.indexes   # 章节首页
    - search.highlight     # 搜索结果高亮
    - content.code.copy    # 代码块复制按钮

plugins:
  - search:
      lang: zh
  - minify:
      minify_html: true

markdown_extensions:
  - pymdownx.highlight:    # 增强代码高亮
      anchor_linenums: true
  - pymdownx.superfences  # 支持 Mermaid
  - admonition            # 告警块
  - pymdownx.tasklist     # 任务列表

nav:
  - 首页: index.md
  - 快速开始:
      - 安装: getting-started/install.md
      - 配置: getting-started/config.md
  - API 参考:
      - 概述: api/overview.md
      - 端点: api/endpoints.md
  - 开发指南: dev-guide.md

MkDocs Material 的 Admonition 语法

!!! note "可选标题"
    这是一个信息提示块。
    支持在 Markdown 文档中使用（不是 GitHub Alert 语法）。

!!! warning
    这是警告，没有自定义标题时显示默认标题。

??? tip "折叠的提示（默认折叠）"
    这个内容默认折叠，点击展开。

???+ info "展开的提示（默认展开）"
    这个内容默认展开，可以点击折叠。

Docusaurus — React 文档站

Facebook（Meta）开源的文档框架，基于 React，支持 MDX（Markdown + JSX），适合大型产品文档。

快速上手

# 使用 classic 模板创建项目（推荐）
npx create-docusaurus@latest my-docs classic --typescript

cd my-docs

# 启动开发服务器
npm start

# 构建生产版本
npm run build

# 预览构建结果
npm run serve

Docusaurus 的核心特色

内容功能

  • MDX：在 Markdown 中使用 React 组件
  • 版本管理：多版本文档并存
  • 博客：内置博客功能
  • i18n：多语言支持

性能与 SEO

  • 静态生成：构建时预渲染所有页面
  • Algolia 搜索集成
  • sitemap 自动生成
  • OpenGraph 元标签支持

MDX 的威力

# 在 .mdx 文件中使用 React 组件
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## 安装

<Tabs>
  <TabItem value="npm" label="npm" default>
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
</Tabs>

Lint 与格式检查工具

markdownlint

基于规则的 Markdown 格式检查工具，可以在 CI 中集成：

# 安装
npm install -g markdownlint-cli2

# 检查文件
markdownlint-cli2 "**/*.md" "#node_modules"

# 自动修复（部分规则支持）
markdownlint-cli2-fix "**/*.md"
# .markdownlint.json 配置示例
{
  "default": true,           // 启用所有规则
  "MD013": false,            // 不限制行长度
  "MD033": {                 // 限制 HTML 标签使用
    "allowed_elements": ["details", "summary", "br", "img", "div", "mark"]
  },
  "MD041": true,             // 第一行必须是 H1
  "MD022": true,             // 标题前后要有空行
  "MD024": {                 // 处理重复标题
    "siblings_only": true    // 只检查同级重复（允许不同章节有相同子标题）
  },
  "MD046": {                 // 代码块风格
    "style": "fenced"        // 强制使用围栏代码块
  }
}

Prettier 格式化

# 安装
npm install -D prettier

# 格式化所有 Markdown
npx prettier --write "**/*.md"

# .prettierrc 配置
{
  "proseWrap": "always",     // 自动折行
  "printWidth": 100          // 行宽限制
}

markdown-link-check 链接检查

# 安装
npm install -g markdown-link-check

# 检查单个文件
markdown-link-check README.md

# 检查目录下所有文件
find . -name "*.md" -not -path "*/node_modules/*" | xargs -L1 markdown-link-check

# .markdown-link-check.json 配置（忽略某些链接）
{
  "ignorePatterns": [
    { "pattern": "^https://localhost" },
    { "pattern": "^file://" }
  ],
  "retryOn429": true,
  "retryCount": 3
}

在 GitHub Actions 中集成所有检查

name: Markdown Quality
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装依赖
        run: npm ci

      - name: markdownlint 格式检查
        run: npx markdownlint-cli2 "**/*.md" "#node_modules"

      - name: 链接有效性检查
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          config-file: '.markdown-link-check.json'

Markdown 解析器对比

了解主流 Markdown 解析器，有助于理解为什么同一文档在不同平台渲染不同：

解析器语言规范使用场景
markedJavaScriptGFM前端/Node.js，GitHub Pages
markdown-itJavaScriptCommonMark + 插件VS Code 内置，VitePress
goldmarkGoCommonMarkHugo（静态博客）
Python-MarkdownPython原始 MarkdownMkDocs
mistunePythonCommonMarkPython 项目
kramdownRubyCommonMark+扩展Jekyll（GitHub Pages）
pandocHaskellPandoc Markdown文档转换
pulldown-cmarkRustCommonMarkzola、Rust 文档工具

小结

本章要点