技术写作与文档2020dave.autonoma.ca
一位技术写作者的「Markdown 排版」系列博客
“Typesetting Markdown” blog post series by a technical writer
导读
这是一位技术作者撰写的系列文章，介绍如何用 pandoc、ConTeXt、脚本和 R 搭建一套 Markdown 排版生态，从自动生成 PDF 到变量替换、图表嵌入和样式隔离。对写作者来说，它不只是工具教程，也展示了如何把复杂写作流程拆成系列、解释设计取舍，并回应读者对示例与复杂度的质疑。
可以直接用的写作要点
- 01
把复杂写作/发布流程拆成系列文章，每部分只解决一个明确问题，读者更容易跟进。
- 02
技术写作要尽量提供可运行示例、源码目录和最终成品，让读者能验证方法是否适合自己。
- 03
介绍新工具链时，要主动对比读者熟悉的方案（如 LaTeX、Pandoc 或 Sphinx），说明“为什么值得换”。
- 04
把重复出现的变量、样式和生成步骤外部化，可以让内容源文件更干净、更易复用。
HN 评论精选
作者按模块说明整套 Markdown 排版生态：脚本、样式、变量、R 集成和主题复用。
作者自述：这个系列讲用 pandoc 和 ConTeXt 排版 Markdown 的生态。第 1—3 部分讲可复用的 bash 脚本，在源文档变化时自动生成 PDF，并介绍 ConTeXt、pandoc 和脚本；第 4 部分讲如何独立于 Markdown 源设置颜色等呈现；第 5 部分讲插值变量，把变量放在 YAML 等外部文件中再在 Markdown 里引用；第 6 部分加入 R 并嵌入图表；第 7 部分用 R 生成电动车投资回报文档，并演示 plain TeX；第 8 部分将讲主题隔离和小说排版。
thangalin查看英文原文
Author here. Typesetting Markdown is a multi-part series that describes an ecosystem for typesetting Markdown documents using pandoc and ConTeXt. Here's a brief walk-through: Parts 1, 2, & 3 are about the ecosystem: writing reusable and user-friendly bash scripts that autogenerate PDF files when content in the source documents change. They introduce the reader to ConTeXt, pandoc, and scripting. Part 4 enhances the ecosystem a bit more before describing one way to apply colours and other presentation in the output document, independently from the Markdown source. Part 5 demonstrates what I feel is missing from almost all editors, Markdown or otherwise: interpolated variables. I've posted an architecture diagram at https://i.imgur.com/8IMpAkN.png for the curious. This part describes how to externalize variables (e.g., in YAML) and reference them within Markdown documents. Part 6 adds R into the mix, including how to generate then embed graphical output into R Markdown documents. Part 7 uses R to generate a high-level return-on-investment document outlining how long it will take to pay off an electric vehicle versus maintaining a gas guzzler. This part also describes how to have plain TeX (not LaTeX) typeset in the final document. Part 8 (soon!) revisits themes to demonstrate how different styles can be isolated and applied to novels. It will show ways of setting up directory structures, how to use ConTeXt "modes", and, by the end, will show a way to typeset famous (public domain) novels by applying a couple different styles.
对工具链复杂度的质疑，要求作者说明相对 LaTeX 的核心优势。
评论者质疑：R、pandoc、YAML、Markdown，再加不少自定义构建脚本，最后似乎 LaTeX 反而更简单。能否总结一下“为什么不直接用 LaTeX”？
j2kun查看英文原文
R + pandoc + yaml + markdown + quite a few custom build scripts... it seems like LaTeX is simpler in the end. Could you summarize "why not just use LaTeX?"
赞赏设计思路，但要求提供完整示例，并质疑复杂脚本是否真的改善 Markdown→PDF 流程。
评论者称赞文章详细，也感谢作者分享流程和背后的思考，并特别提到工具清单和书籍设计资源很有用。但他问：是否有示例源码，比如一个包含 Markdown 与文本文件、bash 脚本和最终 PDF 的文件夹？他说自己看过 Leanpub、RMarkdown 书籍和《Crafting Interpreters》的自定义构建脚本，有一些痛点，想先通过实例判断这套流程是否解决这些问题，再读技术细节。没有示例时，他只能略读，因为步骤显得复杂，也不容易看出相比现有 Pandoc 流程的改进。他还提到自己正用 Python Sphinx 配合 Makefile 和 pandoc，并质疑第 1 部分里用 Bash 写参数解析等步骤是否与“纯文本到 PDF”本身正交。
danso查看英文原文
This is an impressive and detailed writeup, so thank you for sharing not only your process but the thinking and reasoning behind it. I especially appreciate the list of tools [0] and book design resources [1]. I hope my comments/observations don't seem overly harsh: First, a question: is there a link to example source code, e.g. a folder of Markdown+.text files, the bash scripts, and the resulting PDF? Speaking as someone who has put a decent amount of time in looking at plain-text-publishing systems (such as Leanpub's Markdown system, Hadley Wickham's RMarkdown books [2] and u/munificent's custom build script for "Crafting Interpreters" [3]), I have an idea of my current pain points, and I want to see via-example of whether your process deals with them, before I get into your technical details. Without such an example (and if I'm being honest, even with great examples), I can't bring myself to do more than skim your material, because the steps seem so complicated, and I can't easily discern how they improve how I currently use Pandoc to do the Markdown->PDF process. For example, I'm currently trying to use Python's Sphinx [4] – which, besides being great at creating an online reference site, can also output s compiled file that I can pass into pandoc with a pre-defined Makefile. So all the steps (again, just based on my skimming) you detail in your "Part 1: Build Script", which include writing the argument parser in Bash, seem orthogonal to the plaintext-to-PDF process? [0] https://dave.autonoma.ca/blog/2019/05/29/typesetting-markdown-part-2/ [1] https://dave.autonoma.ca/blog/2020/04/11/interior-book-design/ [2] https://github.com/hadley/r4ds [3] https://news.ycombinator.com/item?id=22788738 [4] https://pedrokroger.net/using-sphinx-write-technical-books/
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选