markdown-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Content Conventions

Markdown内容规范

Quick Reference

快速参考

Heading levels: H2-H3 for structure (H1 auto-generated from title)
Line length: 400 characters max for readability
Language: New Zealand English spelling and grammar
Code blocks: Use fenced blocks with language specification
Front matter: YAML metadata at file start

标题层级：使用H2-H3构建结构（H1由标题自动生成）
行长度：每行最多400个字符，提升可读性
语言：采用新西兰英语拼写和语法
代码块：使用带语言指定的围栏代码块
前置元数据：文件开头添加YAML元数据

Content Rules

内容规则

1. Headings

1. 标题

Use
```
##
```
for H2 and
```
###
```
for H3
Ensure hierarchical structure (don't skip levels)
Do not use H1 (
```
#
```
) - auto-generated from title
Recommend restructuring if content requires H4
Strongly recommend restructuring for H5+

markdown

undefined

使用
```
##
```
表示H2，
```
###
```
表示H3
确保层级结构清晰（不要跳过层级）
请勿使用H1（
```
#
```
）- 由标题自动生成
如果内容需要H4，建议重构内容
强烈建议对需要H5及以上的内容进行重构

markdown

undefined

Main Section (H2)

主章节（H2）

Content here...

此处为内容...

Subsection (H3)

子章节（H3）

Another Subsection (H3)

另一个子章节（H3）

2. Lists

2. 列表

Use
```
-
```
for bullet points
Use
```
1.
```
for numbered lists
Indent nested lists with two spaces
Ensure proper spacing between list items

markdown

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

1. First step
2. Second step
3. Third step

使用
```
-
```
作为无序列表项
使用
```
1.
```
作为有序列表项
嵌套列表使用两个空格缩进
确保列表项之间有适当间距

markdown

- 第一项
- 第二项
  - 嵌套项
  - 另一个嵌套项
- 第三项

1. 第一步
2. 第二步
3. 第三步

3. Code Blocks

3. 代码块

Use triple backticks for fenced code blocks
Always specify language after opening backticks
Ensures proper syntax highlighting

markdown

```python
def hello_world():
    print("Hello, World!")
```

```bash
npm install package-name
```

使用三个反引号创建围栏代码块
必须在开头反引号后指定语言
确保语法高亮正常显示

markdown

```python
def hello_world():
    print("Hello, World!")
```

```bash
npm install package-name
```

4. Links

4. 链接

Use descriptive link text (not "click here")
Ensure URLs are valid and accessible
Use relative paths for internal links

markdown

Good: See the [API documentation](./api-docs.md) for details.
Bad: Click [here](./api-docs.md) for docs.

Good: Read about [dependency injection patterns](https://example.com/di)
Bad: More info [here](https://example.com/di)

使用描述性链接文本（不要用“点击这里”）
确保URL有效且可访问
内部链接使用相对路径

markdown

推荐写法：查看[API文档](./api-docs.md)了解详情。
不推荐写法：点击[这里](./api-docs.md)查看文档。

推荐写法：阅读[依赖注入模式](https://example.com/di)相关内容
不推荐写法：更多信息[这里](https://example.com/di)

5. Images

5. 图片

Include descriptive alt text for accessibility
Use meaningful file names
Provide context in surrounding text

markdown

![Architecture diagram showing microservices communication](./diagrams/architecture.png)

![Database schema with relationships](./schema.png)

包含描述性替代文本以提升可访问性
使用有意义的文件名
在图片周围文本中提供上下文说明

markdown

![展示微服务通信的架构图](./diagrams/architecture.png)

![带关系的数据库架构图](./schema.png)

6. Tables

6. 表格

Use
```
|
```
for column separators
Include header row with alignment
Ensure columns are properly aligned

markdown

| Feature | Status | Priority |
| ------- | ------ | -------- |
| API     | Done   | High     |
| UI      | WIP    | Medium   |
| Tests   | Todo   | High     |

使用
```
|
```
作为列分隔符
包含带对齐方式的表头行
确保列对齐正确

markdown

| 功能 | 状态 | 优先级 |
| ------- | ------ | -------- |
| API     | 已完成 | 高       |
| UI      | 进行中 | 中       |
| 测试   | 待完成 | 高       |

7. Line Length

7. 行长度

Limit lines to 400 characters maximum
Break long lines at 80 characters for improved readability
Use soft line breaks for paragraphs
Avoid horizontal scrolling

每行最多400个字符
为提升可读性，建议在80字符处换行
段落使用软换行
避免横向滚动

8. Whitespace

8. 空白字符

Use blank lines to separate sections
One blank line between paragraphs
Two blank lines before major headings (optional)
Avoid excessive whitespace

使用空行分隔章节
段落之间保留一个空行
大标题前可保留两个空行（可选）
避免过多空白字符

Front Matter

前置元数据

Include YAML front matter at the start of documentation files:

yaml

---
title: Document Title
description: Brief description of content
author: Team Name
date: 2026-01-01
tags: [documentation, guide]
---

在文档文件开头添加YAML前置元数据：

yaml

---
title: Document Title
description: Brief description of content
author: Team Name
date: 2026-01-01
tags: [documentation, guide]
---

Language Standards

语言标准

Use New Zealand English for spelling and grammar
- Colour (not color)
- Organise (not organize)
- Analyse (not analyze)
- Centre (not center)
Maintain consistent terminology throughout documents
Use active voice where possible
Write clear, concise sentences

使用新西兰英语进行拼写和语法
- Colour（而非color）
- Organise（而非organize）
- Analyse（而非analyze）
- Centre（而非center）
文档中保持术语一致
尽可能使用主动语态
编写清晰、简洁的句子

Formatting Best Practices

格式化最佳实践

Emphasis

强调

markdown

Use _italics_ for emphasis.
Use **bold** for strong emphasis.
Use `code` for inline code or technical terms.

markdown

使用_斜体_表示强调。
使用**粗体**表示强强调。
使用`代码`表示行内代码或技术术语。

Blockquotes

块引用

markdown

> Important note or quote
> Can span multiple lines

markdown

> 重要提示或引用内容
> 可跨多行显示

Horizontal Rules

水平线

markdown

Use three or more hyphens, asterisks, or underscores:

---

Content after rule

markdown

使用三个或更多连字符、星号或下划线：

---

水平线后的内容

Task Lists (GitHub Flavored Markdown)

任务列表（GitHub风格Markdown）

markdown

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

markdown

- [x] 已完成任务
- [ ] 待完成任务
- [ ] 另一项待完成任务

Documentation Structure

文档结构

README Files

README文件

markdown

undefined

markdown

undefined

Project Name

项目名称

Brief description of the project.

项目简要描述。

Features

功能特性

Feature 1
Feature 2

功能1
功能2

Installation

安装步骤

```bash installation commands ```

bash

安装命令

Usage

使用方法

Basic usage examples.

基础使用示例。

Contributing

贡献指南

Guidelines for contributors.

贡献者须知。

License

许可证

License information.

undefined

许可证信息。

undefined

Technical Documentation

技术文档

markdown

undefined

markdown

undefined

Document Title

文档标题

Overview

概述

High-level summary.

高层级摘要。

Prerequisites

前置要求

Requirements before proceeding.

开始前需满足的条件。

Step-by-Step Guide

分步指南

Step 1: Initial Setup

步骤1：初始设置

Detailed instructions.

详细说明。

Step 2: Configuration

步骤2：配置

Configuration details.

配置详情。

Troubleshooting

故障排除

Common issues and solutions.

常见问题及解决方案。

References

参考资料

Links to related resources.

undefined

Validation

验证

Anti-Patterns to Avoid

需避免的反模式

❌ Don't do this:

markdown

undefined

❌ 请勿这样做：

markdown

undefined

Using H1 in content (H1 is for title only)

在内容中使用H1（H1仅用于标题）

Click here for more info.

Code without language: ``` code here ```

# No alt text


✅ **Do this instead:**

```markdown

点击这里了解更多信息。

未指定语言的代码：

代码内容

# 无替代文本


✅ **正确做法：**

```markdown

Using H2 for Main Sections

使用H2作为主章节

See the detailed API documentation for more information.

```python def example(): return "with language specified" ```

undefined

查看详细API文档了解更多信息。

python

def example():
return "已指定语言"

undefined