Markdown 与文档工程：写作规范、静态生成与 LaTeX 排版

段落：空行分隔，句末双空格换行
强调：*斜体*、**粗体**、~~删除线~~、'内联代码'
链接：[文字](url) 或 ![图片](url)
列表：- 无序、1. 有序，缩进 2/4 空格子项
引用：> 内容，可嵌套

# Markdown 初衷：可读>可写，不穷举所有格式
# 各工具按需求添加扩展 → 不同语法在不同站点表现不同
# 工程建议：选一个支持 CommonMark + GFM 的平台，别混用花里胡哨的方言

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A   | B   | C   |

# 部分解析器支持左中右对齐（:位置）

- [ ] 待办
- [x] 已完成
# 点击复选框是渲染层特性，纯文本层面只是一个语法糖

正文[^注释]

[^注释]: 注释内容

# 在代码块中声明 mermaid
# 渲染为流程图/时序图/甘特图等
#  GitHub/GitLab/VS Code 插件原生支持
# Hugo 需整合 mermaid.js 或 shortcode

# 只用一次（页面标题）
## 二级以上递进不跳级
## 目录锚点由渲染器自动生成，注意特殊字符兼容性
# 中文标点删除后可能粘连（如「排序：冒泡→slug-sorttmaopao」）

建议在 Triple backtick 后指定语言：```python
获得语法高亮（最终由渲染器/样式表决定）
# 代码块中的 ## 可能被误判为标题——加 v 前缀「v2.0」即可

相对路径：推荐使用从仓库根目录的路径（跨环境友好）
alt 文本：不仅 accessibility，也是图片 SEO
外部链接：警惕 404 → 定期检查或上 CI 检验
# Markdown 中的不可见字符（Zero-width space）会导致链接失效

历史回溯：谁改了什么、为什么改
分支合并：Feature 文档随代码分支走
冲突处理：两人改同一节 → Git 解决
同行评审：与代码 PR 一样的审阅流程

- 标题层级是否正确
- 代码块是否有语言标记
- 图片 alt 文本是否写
- 链接是否有效
- 专有名词大小写一致（API 是否全大写、包名是否保持原名）
- 无术语堆砌（读者是谁？）
- 无冗余（废话删除线保留 vs 直接删除）
- 更新日期/版本号

# Markdown 本身无"评论"语法，用 HTML 注释 <!-- ... -->
# 建议用 Hugo 或 VitePress 的 Callout 语法做标注

Markdown 写内容 → 工具渲染 HTML → 托管（Vercel/Netlify/GitHub Pages）
内容移动成本低：Hugo → VitePress 只需适配短代码/目录结构
# 所以选好"写"和"托管"，工具换起来没那么痛苦

# 目录结构：docs/ + sidebars.js + docusaurus.config.js
# 版本化：mkdir docs/ver-2，docusaurus 自动切版本
# I18N：i18n/zh/docusaurus-plugin-content-docs/
# 搜索：本地 Search（需 index）或 Algolia DocSearch
# 自定义：React 组件写 Custom Pages
# Deploy：Build 后产物是静态 HTML，可丢 CDN

# 目录结构：docs/ + .vitepress/config.js + 自动 sidebar
# 主题：默认主题简洁，设置 frontmatter layout 即可自定义
# 搜索：本地 minisearch 或 Algolia
# 短代码：Vue 组件做自定义 Block
# 性能：Vite 驱动，dev 启动毫秒级

# mkdocs.yml 配置中心，插件只需 pip install
# 主题：Material（最强移动端与暗色模式）
# 搜索：内置 lunr.js（自动生成索引）
# 适合：纯文档、技术团队内部、不想碰前端构建
# 痛点：没有前端 hot reload（需 --watch）

# Go 编写 → 构建速度秒级（10k+ 页）
# 主题系统成熟（2、300 主题可选）
# 短代码（Shortcodes）做嵌入：`{{< figure >}}`、`{{< ref >}}`
# taxonomy：自动标签/分类页面
# 适合：博客+文档混合站、大量页面、对构建速度有要求
# 痛点：模板语言（Go template）学习曲线

行内：$E=mc^2$
行间（居中）：$$E=mc^2$$
多行对齐：\begin{align} ... \end{align}

\alpha, \beta, \gamma, \sum, \prod, \int, \frac, \sqrt,
\hat{x}, \bar{x}, \vec{x}, \mathbb{R}, \mathcal{N}

\begin{theorem}[费马小定理]
...
\end{theorem}
\begin{proof}
...
\end{proof}
# 需 \usepackage{amsthm}

amsmath    数学公式（核心）
amsthm     定理环境（定义/引理/证明）
geometry   页面尺寸
hyperref   超链接
listings   代码高亮
# 工程：pandoc 可 Markdown→LaTeX→PDF，用模板控制样式

# Markdown → PDF
pandoc input.md -o output.pdf --pdf-engine=xelatex -V CJKmainfont="SimSun"
# Markdown → PPT
pandoc input.md -o output.pptx
# Markdown → EPUB
pandoc input.md -o output.epub --metadata title="My Book"
# 模板：--template 用 .tex/.html 自定义

# 写一次 Markdown → 多格式发布
# 缺点：各格式样式不同，复杂排版需各别模板
# 折中：内容用 Markdown，排版用专业工具（InDesign/PowerPoint）