markdown-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Writing

Markdown写作

Two things decide whether Markdown is good: where it renders (which syntax you may use) and how it reads (whether anyone finishes it). Handle them in that order.

一篇优质的Markdown内容取决于两点：渲染场景（你可以使用哪些语法）和可读性（是否有人会读完它）。请按此顺序处理这两点。

1. Check the render target first

1. 先确认渲染目标

Renders where	What you may use
GitHub only — issues, PRs, comments, discussions, wiki, repo file views	Everything, including alerts, `<details>` , task lists, footnotes, mermaid, theme-aware images
README that also ships to npm, PyPI, a docs site, or an editor preview	CommonMark + tables + `<details>` . Treat GitHub extras as degradable, not free
Terminal, `--help` output, plain-text logs	No Markdown. Write plain text

The degradation that matters in practice: a GitHub alert renders on npm as a plain blockquote with a literal
[!IMPORTANT]
line above the text. That is acceptable — use alerts in a published README anyway — but only if the sentence after it stands on its own without the label. An alert whose body reads "This one." is meaningless the moment the label stops rendering.

Full syntax and per-host support:

references/github-features.md

渲染场景	可使用的语法
仅GitHub平台——Issues、PR、评论、讨论、Wiki、仓库文件预览	所有语法，包括提示框、 `<details>` 、任务列表、脚注、Mermaid、适配主题的图片
同时发布到npm、PyPI、文档站点或编辑器预览的README	CommonMark + 表格 + `<details>` 。将GitHub扩展功能视为可降级兼容的内容，而非默认支持项
终端、 `--help` 输出、纯文本日志	不使用Markdown，撰写纯文本

实际场景中需要关注的降级问题：GitHub提示框在npm上会渲染为普通块引用，且顶部会显示一行字面量
[!IMPORTANT]
。这种情况是可接受的——即便如此仍可在发布的README中使用提示框，但前提是提示框后的内容无需依赖标签也能独立表意。如果提示框正文仅写“选这个”，一旦标签无法渲染，内容就毫无意义。

完整语法及各平台支持情况：

references/github-features.md

。

2. GitHub alerts

2. GitHub提示框

Five types, exact spelling, uppercase, nothing on the label line:

markdown

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Picking one:

NOTE — a true fact that a skimmer would otherwise miss. No stakes.
TIP — an optional shortcut. Deleting it costs nothing.
IMPORTANT — they will fail without this. Version floors, required config.
WARNING — doing it wrong has consequences. Deprecations, data loss, footguns.
CAUTION — the consequence of an action they are about to take.

Rules that keep them working:

Rare. Two or three per document. When everything is highlighted, nothing is.
Not a section. An alert is one to four lines. Longer means it is a section with a heading.
Not a wrapper for the obvious. If the plain sentence would have been read anyway, leave it plain.
Never stacked. Two alerts in a row read as noise.

Good uses: the version floor in an install section, a deprecated package banner, "this operation is destructive", the one constraint in an epic issue that every child issue depends on.

共有五种类型，拼写必须准确、大写，标签行不能包含其他内容：

markdown

> [!NOTE]
> 突出显示用户即便快速浏览也应注意的信息。

> [!TIP]
> 帮助用户更高效完成操作的可选信息。

> [!IMPORTANT]
> 用户成功完成操作必须知晓的关键信息。

> [!WARNING]
> 因存在潜在风险，需要用户立即关注的重要内容。

> [!CAUTION]
> 执行某操作可能产生的负面后果。

类型选择指南：

NOTE——快速浏览者可能错过的客观事实，无风险提示。
TIP——可选的快捷操作技巧，删除后不影响核心内容。
IMPORTANT——用户不知晓就会操作失败的信息，比如最低版本要求、必填配置。
WARNING——操作失误会引发后果的内容，比如废弃通知、数据丢失风险、易踩坑点。
CAUTION——用户即将执行的操作可能带来的负面结果。

确保提示框有效的规则：

少用：每份文档中最多2-3个。如果所有内容都被高亮，等于没有高亮。
不是章节：提示框内容控制在1-4行。内容过长说明应该拆分为带标题的章节。
不为显而易见的内容加框：如果普通语句就能被读者注意到，就保持原样。
不要连续使用：两个提示框连在一起会被视为噪音。

合适的使用场景：安装章节中的最低版本要求、废弃包提示、“此操作具有破坏性”、所有子Issue都依赖的主Issue约束条件。

3. Write for someone with no time

3. 为没时间的读者撰写内容

Assume the reader is skimming, on a phone, or has ADHD. All three want the same thing: the point, early, in short pieces.

Lead with the point. The first sentence of a section answers "what is this / what do I do". Background comes after, or not at all.
Show, then explain. Put the code block or the command first and the paragraph about it second. A working example answers more questions than three paragraphs.
One idea per paragraph. Two to four sentences. A wall of text is skipped whole, so the point inside it is lost.
Short sections. If a section runs past a screen, it is two sections — or it is a table pretending to be prose.
Talk to the reader. Second person, active voice, present tense. "Pass a seed to reproduce the roll", not "A seed may be passed in order for the roll to be reproduced". You are explaining something to a person, not filing a report.
Concrete beats abstract. Real values, real output, real filenames. Put the result in a trailing comment:
```
result.total; // 14
```
.
Numbers beat adjectives. Not "blazingly fast" —
```
0.49 µs per roll
```
. Not "tiny" —
```
11.9 kB brotli
```
.

Delete on sight: "Note that", "It is important to note", "simply", "just", "basically", "in order to", "As you can see", "Let's dive in", "In this section we will", "feel free to", "powerful", "seamless", "robust".

Match the register to the document. A README talks to the reader. A changelog is a list. An architecture doc can be denser. A PR body is a factual summary of changes — no personality, no explanation of why the reader should care. Do not make everything chatty; make everything clear.

假设读者正在快速浏览、使用手机阅读，或患有注意力缺陷障碍。这三类读者的需求一致：尽早看到核心要点，内容简短。

开门见山：章节的第一句话就要回答“这是什么/我该做什么”。背景信息放在后面，或者干脆省略。
先展示，再解释：先放代码块或命令，再用段落说明。一个可运行的示例比三段文字能回答更多问题。
一段一个核心观点：每段2-4句话。大段文字会被直接跳过，其中的要点也会丢失。
章节简短：如果一个章节超过一屏长度，就拆成两个章节——或者它其实是伪装成 prose 的表格。
与读者对话：使用第二人称、主动语态、现在时态。比如写“传入随机种子以重现结果”，而非“可传入随机种子，从而实现结果重现”。你是在给人讲解内容，不是提交报告。
具体优于抽象：使用真实值、真实输出、真实文件名。把结果放在末尾注释里：
```
result.total; // 14
```
。
数字优于形容词：不说“快到飞起”，而是写
```
0.49 µs per roll
```
；不说“体积小巧”，而是写
```
11.9 kB brotli
```
。

看到就删除的冗余表达：“请注意”、“需要注意的是”、“简单地”、“只是”、“基本上”、“为了”、“如你所见”、“让我们深入探讨”、“在本节中我们将”、“随时可以”、“强大的”、“无缝的”、“健壮的”。

根据文档类型调整语气：README要像和读者对话；变更日志是列表形式；架构文档可以更严谨；PR正文是对变更的事实性总结——无需个性表达，也不用解释读者为什么要关心。不要让所有内容都变得口语化，但要确保所有内容都清晰易懂。

4. Simple first, technical after

4. 先简单说明，再补充技术细节

Never mix the plain explanation and the exhaustive detail in one block. Split them:

Two or three sentences in plain words: what it is, why you would use it.
A minimal example.
Then the table, the edge cases, the full option list, the
```
<details>
```
block.

A reader who only needs step 1 can leave after step 1. A reader who needs the table can find it without reading step 1 twice. Interleaving them costs both readers.

This is also the rule for reference material: prose explains, tables enumerate. Anything with a repeated shape — options, flags, error codes, exit codes, fields, comparisons — is a table, not a bulleted list of sentences.

永远不要把通俗解释和详尽细节混在同一个区块里。拆分它们：

用2-3句通俗语言说明：这是什么、为什么要用它。
给出最简示例。
再展示表格、边缘情况、完整选项列表、
```
<details>
```
区块。

只需要第一步内容的读者看完就可以离开；需要表格的读者无需重复阅读第一步内容。混在一起会浪费两类读者的时间。

这也是参考资料的规则：** prose 用于解释，表格用于枚举**。任何具有重复结构的内容——选项、标志、错误码、退出码、字段、对比项——都应该用表格呈现，而不是写成带句子的项目符号列表。

5. Structure defaults

5. 结构默认规则

One
```
#
```
per document, or none when a centered HTML title block already names it. Everything else is
```
##
```
/
```
###
```
. Do not go past
```
###
```
.
Sentence case headings. "Error handling", not "Error Handling".
Headings are navigation. They should read as a list of answers to "how do I…" — a skimmer reads only these.
Always tag code fences with a language (
```
bash
```
,
```
typescript
```
,
```
json
```
,
```
markdown
```
). Untagged fences lose highlighting everywhere.
<details>
for the material only some readers need — long output, benchmark protocol, a migration table. It keeps the page short without deleting the information.
Link text says where it goes.
```
[MIGRATION.md](MIGRATION.md)
```
, never "click here" or a bare URL dropped mid-sentence.
Relative links for in-repo files so they survive forks and tags.
Table of contents only past ~6 sections, and only in a README. GitHub already renders an outline button for every Markdown file.
Match the file's existing wrap width. If the file hard-wraps at 80, wrap at 80. If it does not, do not introduce it.

每份文档最多一个
```
#
```
标题，如果已有居中的HTML标题块命名文档，则不用
```
#
```
。其他标题用
```
##
```
/
```
###
```
，不要使用
```
####
```
及以下层级。
标题采用句首大写格式：比如“错误处理”，而非“错误处理（全大写）”。
标题是导航工具：标题应该像是“我该如何……”的答案列表——快速浏览者只会看这些标题。
代码块必须标记语言（
```
bash
```
、
```
typescript
```
、
```
json
```
、
```
markdown
```
）。未标记的代码块在任何地方都不会有语法高亮。
用
<details>
存放仅部分读者需要的内容——比如长输出、基准测试流程、迁移表格。这样既能保持页面简洁，又不会删除必要信息。
链接文本要明确指向：比如
```
[MIGRATION.md](MIGRATION.md)
```
，永远不要用“点击这里”或在句子中间直接放裸URL。
仓库内文件使用相对链接，这样在分支和标签切换时仍能正常访问。
仅当章节数超过6个时才添加目录，且仅在README中添加。GitHub已经为每个Markdown文件提供了大纲按钮。
匹配文件已有的换行宽度：如果文件固定在80字符处换行，就保持80字符；如果没有，就不要引入换行规则。

6. Don't

6. 不要做的事

Emoji headings, unless the repo already does it consistently.
More than four or five badges. Version, CI, license, runtime — stop there.
An "Introduction" or "Overview" heading holding one sentence.
Restating the docs site in the README. Link to it.
A "Features" list of adjectives. Each bullet gets a bolded claim and a fact that backs it.
Bold or italics for emphasis inside every other sentence. Emphasis works only when it is rare.
Trailing "hope this helps" / "let me know if you need anything" in a PR or issue body.

给标题加表情，除非仓库已有统一的表情使用规范。
使用超过4-5个徽章。版本、CI、许可证、运行环境——到此为止。
用“简介”或“概述”标题只放一句话。
在README中重复文档站点的内容，直接链接到文档站点即可。
写满形容词的“功能特性”列表。每个项目符号都要有加粗的核心主张和支撑事实。
每隔一句话就用粗体或斜体强调。只有少用的时候，强调才有效。
在PR或Issue正文末尾加“希望这能帮到你”/“如果需要帮助请告诉我”之类的话。

README template

README模板

references/readme-template.md

holds a general-purpose skeleton with every optional block marked. Take the sections that apply and delete the rest — a short README that covers install, usage, and one real example beats a long one with empty headings.

references/readme-template.md

包含一个通用框架，所有可选区块都已标记。保留适用的章节，删除其余部分——一个涵盖安装、用法和真实示例的简短README，远胜于满是空标题的冗长文档。