md-syntax

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Authoring Guidelines

Markdown 编写指南

Follow these rules when creating or editing markdown files.

创建或编辑 Markdown 文件时，请遵循以下规则。

Rules

规则

Always specify language on code blocks - Use
```
bash
```
,
```
yaml
```
,
```
json
```
,
```
text
```
,
```
hcl
```
,
```
go
```
, etc. Never use bare
```
```
```
No AI slop - Never use emojis, glyphs or emdashes
Use headings, not bold for section titles - Use proper heading levels (
```
##
```
,
```
###
```
, etc.) not
```
**Bold**
```
on its own line
One H1 per file - Only one
```
# Title
```
at the top
First line should be H1 - Start files with
```
# Title
```
Write to the formatter contract - A PostToolUse hook reformats markdown after every write. See
```
/md-lint
```
for what it rewrites and which lint rules it cannot fix
Blank lines between styles - Put single blank line between different markdown types

始终为代码块指定语言 - 使用
```
bash
```
、
```
yaml
```
、
```
json
```
、
```
text
```
、
```
hcl
```
、
```
go
```
等。禁止使用未指定语言的
```
```
```
不要使用 AI 粗制滥造的内容 - 不使用 emoji、装饰性字形符号或 em dash
章节标题使用标题，而不是加粗 - 使用正确的标题层级（
```
##
```
、
```
###
```
等），不要单独使用
```
**加粗**
```
每个文件只能有一个 H1 - 仅在顶部使用一个
```
# 标题
```
第一行应为 H1 - 以
```
# 标题
```
开始文件
遵循格式化器约定 - PostToolUse hook 会在每次写入后重新格式化 Markdown。有关其重写内容以及无法修复的 lint 规则，请参阅
```
/md-lint
```
不同样式之间保留空行 - 在不同 Markdown 类型之间添加一个空行

Examples

示例

Blank lines between styles

不同样式之间保留空行

Put a single blank line between markdown types/styles. Do not put multiple blank lines between markdown styles.

CORRECT

text

undefined

在不同 Markdown 类型或样式之间添加一个空行。不要在 Markdown 样式之间添加多个空行。

正确

text

undefined

Heading

paragraph

list item one
list item two

block quote


INCORRECT

```text

paragraph

list item one
list item two

block quote


错误

```text

Heading

paragraph

list item one
list item two

block quote

undefined

paragraph

list item one
list item two

block quote

undefined

Headings not bold

标题不要加粗

CORRECT

text

undefined

正确

text

undefined

Heading

paragraph


INCORRECT

```text
**heading incorrect bold**

paragraph

paragraph


错误

```text
**heading incorrect bold**

paragraph

Code Blocks

代码块

Always specify language.

CORRECT with language

text

```bash
#!/bin/bash
```

INCORRECT without language

text

```
#!/bin/bash
```

始终指定语言。

正确，指定语言

text

```bash
#!/bin/bash
```

错误，未指定语言

text

```
#!/bin/bash
```

Trailing New Line

末尾换行

End the file with a single newline after the last line of content. A fenced example can't show this, because the fence hides the final byte. Check it with

tail -c 1 file.md | xxd

, which must print

0a

在最后一行内容后添加一个换行符并结束文件。围栏代码块示例无法体现这一点，因为围栏会隐藏最后一个字节。可以使用

tail -c 1 file.md | xxd

检查，输出必须为

0a

。