pandoc 是唯一靠谱的通用 Markdown 转 HTML 方案，需显式指定 -f gfm、--standalone 等参数，注意编码、路径、CSS 选择器匹配及 GFM 兼容性问题。
用 pandoc 直接转，别碰在线工具和 GUI 软件
绝大多数人卡在第一步：选错工具。在线转换器丢格式、改编码、不支持自定义 CSS；GUI 软件（比如 Markdown Preview Enhanced 的“导出 HTML”按钮）常静默失败，且不暴露错误原因。pandoc 是唯一靠谱的通用方案，它把 .md 当作源语言，html 是目标格式，中间不加任何抽象层。
实操建议：
- 装好
pandoc后，终端里直接跑：pandoc input.md -o output.html - 默认输出是纯 HTML5，无样式，但结构干净——这是好事，方便你后续加 CSS 或嵌入网页
- 如果原文有中文，加
--standalone和-c style.css之前，先确认文件编码是 UTF-8（否则浏览器打开显示乱码，错误信息可能是UnicodeDecodeError） - 别用
markdown-it或markedCLI 工具替代pandoc：它们不支持 TOC、数学公式、引用导出等常见需求
加目录、语法高亮、数学公式，全靠 pandoc 参数控制
pandoc 不是“一键生成”，但每个功能都对应一个明确参数，而不是靠配置文件或插件开关。漏掉某个参数，对应功能就彻底不生效，不会报错也不会提示。
常见组合示例：
立即学习“前端免费学习笔记（深入）”；
- 生成带层级目录的 HTML：
pandoc --toc --toc-depth=3 input.md -o output.html - 启用代码块语法高亮（默认用 highlight.js）：
pandoc --highlight-style=pygments input.md -o output.html；若要更小体积，改用--highlight-style=espresso - 渲染 LaTeX 数学公式：
pandoc --mathjax input.md -o output.html（会自动引入 MathJax CDN）；本地部署可换为--mathml或--webtex - 注意：
--standalone必须加上才能让 CSS、JS、标题、meta 标签完整写入 HTML 文件；没它，输出只是 HTML 片段，浏览器打不开
CSS 样式不生效？大概率是路径或作用域问题
很多人加了 -c style.css 却发现字体没变、列表还是默认样式。不是 pandoc 没读 CSS，而是 CSS 选择器没匹配上生成的 HTML 结构。
真实原因和应对：
-
pandoc生成的标题是<h1>～<h6>，但默认 class 是header，不是title或section-title；查生成的 HTML 源码，按实际 class 写 CSS - CSS 文件路径必须相对于当前执行命令的目录，不是相对于
.md文件位置；比如pandoc docs/a.md -c css/main.css，就要确保你在docs/..目录下运行 - 如果用了
--self-contained，CSS 会被内联进<style>，此时外部 CSS 文件完全无效——这个参数只适合发给他人单 HTML 文件，不适合开发调试 - 避免用
!important强行覆盖；先用浏览器开发者工具看 computed styles，确认是否真被加载、是否被更高优先级规则压制
GitHub README.md 不能直接转？得先清理扩展语法
GitHub 的 Markdown 渲染器（github-markup）支持很多 pandoc 不认的语法，比如 ~~strikethrough~~、[comment]: # (hidden)、任务列表 - [x] done。这些在 pandoc 默认模式下会原样输出为文本，甚至破坏 HTML 结构。
安全做法：
- 用
pandoc -f gfm -t html显式指定输入格式为 GitHub Flavored Markdown（GFM），它能识别任务列表、表格对齐、删除线等 - 但 GFM 表格列宽控制、自定义属性（如
{: #myid}）仍不支持；需要手动删或替换 - 如果 README 里有
且图片路径是相对 GitHub 仓库的（如./img/logo.png），转成 HTML 后路径不会自动转为绝对 URL，浏览器打不开——得用--resource-path或脚本批量替换src属性 - 别依赖
pandoc自动检测格式：它常把 GFM 当成普通 Markdown，导致解析错位；永远显式写-f gfm
真正麻烦的不是命令怎么敲，而是每次改完 CSS 或加个新功能，都要重新检查生成的 HTML 源码里有没有多出空格、有没有漏掉 class、data- 属性有没有被 pandoc 过滤掉——这些细节不会报错，只会让页面看起来“不太对”。
