技术写作与文档2018madoko.net
Madoko：快速编写专业文档的 Markdown 处理器
Madoko – a fast markdown processor for writing professional documents
导读
Madoko 是一个可直接在浏览器里运行的 Markdown 处理器，能把纯文本稿件编译成排版精良的网页、PDF 和 reveal.js 幻灯片。对写作者的价值在于它示范了一种分工：正文用 Markdown 流畅地写，视觉细节交给 CSS/PDF 模板精确控制。评论区也围绕"该用重型在线工具还是轻量编辑器+pandoc"展开了一场颇有启发的争论。
可以直接用的写作要点
- 01
把内容与排版分开：正文只写 Markdown 结构，样式交给模板/样式表统一控制，改版式时不必回头改文章。
- 02
写作工具越轻越好：选一个无干扰的纯文本编辑器，把编译、导出这类杂活交给 pandoc 之类的命令行工具。
- 03
同一份源文件可以同时产出文档、网页和幻灯片（如 reveal.js），一次写作多处复用，减少重复劳动。
- 04
不要迷信所见即所得：真正的排版效果往往在编译输出里才看得准，写作阶段专注文字本身更高效。
HN 评论精选
轻量编辑器+pandoc 足以替代重型在线工具，所见即所得被高估。
为什么现在什么都要跑在浏览器里？我喜欢精简、轻量、只专注一件事——编辑文字——的文本编辑器。Madoko 提供的东西（除了所见即所得，而那在真正产出内容时被高估了）用 pandoc 加自选编辑器都能做到。我最近用经典的 nvi，很适合无干扰环境，而且 OpenBSD 默认就装了。
messe查看英文原文
Why does everything have to run inside a web browser these days? I like my text editors/word processors to be lean, lightweight and focused on one thing: editing text. Everything Madoko offers here (aside from WYSIWYG—which is overrated when you're trying to produce content) can be accomplished with pandoc+your text editor of choice (I've been using classic nvi lately, seems to work well for a distraction free environment and as a bonus is in the base install of OpenBSD).
Markdown 的书写流畅 + CSS/PDF 的精确版式控制，是理想组合。
对我来说 Madoko 是彻底的胜利。Markdown 让文字写得顺畅，默认视觉效果又漂亮，再加上对 CSS 和 PDF 版式的超精确控制，使它成为非常强大的工具。可以用它做的东西的例子：monetary-reform.info、1984.surge.sh，以及一份 PDF（kortlink.dk/uumf）。
mathiasrw查看英文原文
Madoko is, to me, an absolute win. Markdown for smooth text writing and a beautiful default visual expression combined with ultra-precise control for CSS and pdf visuals makes it a very powerful tool. Examples of what can be made in Madoko: - http://monetary-reform.info - http://1984.surge.sh - http://kortlink.dk/uumf (PDF)
真正吸引人的是把 Markdown 直接变成幻灯片，且希望集成进常用编辑器。
对我来说最有意思的功能是用 reveal.js 做演示。我希望能有一个包把这些功能直接搬进 VSCode 或 Atom，因为我在那里已经能写 Markdown 并预览文档了。
siruncledrew查看英文原文
The presentation aspect with reveal.js is the most interesting feature to me. I would prefer if there was just a package to do all this in VSCode or Atom, since I could already write and preview markdown there for documents.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选