Back to Details

markdown-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markdown Documentation

Markdown 文档

Overview

概述

Master markdown syntax and best practices for creating well-formatted, readable documentation using standard Markdown and GitHub Flavored Markdown (GFM).
精通Markdown语法及最佳实践，使用标准Markdown和GitHub Flavored Markdown（GFM）创建格式规范、可读性强的文档。

When to Use

适用场景

  • README files
  • Documentation pages
  • GitHub/GitLab wikis
  • Blog posts
  • Technical writing
  • Project documentation
  • Comment formatting
  • README文件
  • 文档页面
  • GitHub/GitLab 维基
  • 博客文章
  • 技术写作
  • 项目文档
  • 注释格式化

Markdown Syntax Reference

Markdown语法参考

Headers

标题

markdown
undefined
markdown
undefined

H1 Header

H1 Header

H2 Header

H2 Header

H3 Header

H3 Header

H4 Header

H4 Header

H5 Header
H5 Header
H6 Header
H6 Header

Alternative H1

Alternative H2

undefined

Alternative H1

Alternative H2

undefined

Text Formatting

文本格式化

markdown
**Bold text**
__Also bold__

*Italic text*
_Also italic_

***Bold and italic***
___Also bold and italic___

~~Strikethrough~~

`Inline code`

> Blockquote
> Multiple lines
> in blockquote

---
Horizontal rule (also ___ or ***)
markdown
**Bold text**
__Also bold__

*Italic text*
_Also italic_

***Bold and italic***
___Also bold and italic___

~~Strikethrough~~

`Inline code`

> Blockquote
> Multiple lines
> in blockquote

---
Horizontal rule (also ___ or ***)

Lists

列表

markdown
Unordered list:
- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

Using asterisks:
* Item 1
* Item 2

Using plus:
+ Item 1
+ Item 2

Ordered list:
1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

Task list (GitHub Flavored Markdown):
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
markdown
Unordered list:
- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

Using asterisks:
* Item 1
* Item 2

Using plus:
+ Item 1
+ Item 2

Ordered list:
1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

Task list (GitHub Flavored Markdown):
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links and Images

链接与图片

markdown
[Link text](https://example.com)
[Link with title](https://example.com "Link title")

Reference-style link:
[Link text][reference]
[reference]: https://example.com

Automatic link:
<https://example.com>
<email@example.com>

![Alt text](image.png)
![Alt text](image.png "Image title")

Reference-style image:
![Alt text][image-ref]
[image-ref]: image.png
markdown
[Link text](https://example.com)
[Link with title](https://example.com "Link title")

Reference-style link:
[Link text][reference]
[reference]: https://example.com

Automatic link:
<https://example.com>
<email@example.com>

![Alt text](image.png)
![Alt text](image.png "Image title")

Reference-style image:
![Alt text][image-ref]
[image-ref]: image.png

Code Blocks

代码块

markdown
Inline code: `const x = 5;`

Code block with language:
```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

```python
def hello(name):
    print(f"Hello, {name}!")
```

```bash
npm install
npm start
```

Indented code block (4 spaces):
    const x = 5;
    console.log(x);
markdown
Inline code: `const x = 5;`

Code block with language:
```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

```python
def hello(name):
    print(f"Hello, {name}!")
```

```bash
npm install
npm start
```

Indented code block (4 spaces):
    const x = 5;
    console.log(x);

Tables

表格

markdown
Simple table:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Aligned columns:
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
| Text | Text   | Text  |

Minimal table:
Column 1 | Column 2
---------|----------
Data     | Data
Data     | Data
markdown
Simple table:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Aligned columns:
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
| Text | Text   | Text  |

Minimal table:
Column 1 | Column 2
---------|----------
Data     | Data
Data     | Data

Extended Syntax (GitHub Flavored Markdown)

扩展语法（GitHub Flavored Markdown）

markdown
Footnotes:
Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

Definition list:
Term
: Definition

Emoji:
:smile: :rocket: :heart:
:+1: :-1: :eyes:

Automatic URL linking:
https://github.com

Task lists in issues:
- [x] #739
- [ ] https://github.com/octo-org/repo/issues/1
- [ ] Add tests

Mentioning users and teams:
@username
@org/team-name

Referencing issues and PRs:
#123
GH-123
username/repo#123
markdown
Footnotes:
Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

Definition list:
Term
: Definition

Emoji:
:smile: :rocket: :heart:
:+1: :-1: :eyes:

Automatic URL linking:
https://github.com

Task lists in issues:
- [x] #739
- [ ] https://github.com/octo-org/repo/issues/1
- [ ] Add tests

Mentioning users and teams:
@username
@org/team-name

Referencing issues and PRs:
#123
GH-123
username/repo#123

README Template

README 模板

markdown
undefined
markdown
undefined

Project Name

Project Name

Brief description of what this project does and who it's for.
Build Status License Version
Brief description of what this project does and who it's for.
Build Status License Version

Table of Contents

Table of Contents

Features

Features

  • Feature 1
  • Feature 2
  • Feature 3
  • Feature 1
  • Feature 2
  • Feature 3

Demo

Demo

Demo GIF
Try it live: https://demo.example.com
Demo GIF
Try it live: https://demo.example.com

Installation

Installation

Prerequisites

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Node.js 18+
  • npm or yarn

Install via npm

Install via npm

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

Install via yarn

Install via yarn

bash
yarn add package-name
bash
yarn add package-name

From source

From source

bash
git clone https://github.com/user/repo.git
cd repo
npm install
npm run build
bash
git clone https://github.com/user/repo.git
cd repo
npm install
npm run build

Usage

Usage

Basic usage example:
javascript
import { Package } from 'package-name';

const instance = new Package({
  option1: 'value1',
  option2: 'value2'
});

instance.doSomething();
Basic usage example:
javascript
import { Package } from 'package-name';

const instance = new Package({
  option1: 'value1',
  option2: 'value2'
});

instance.doSomething();

Advanced Usage

Advanced Usage

More complex example:
javascript
const result = await instance.advancedMethod({
  param1: 'value',
  param2: 123
});

console.log(result);
More complex example:
javascript
const result = await instance.advancedMethod({
  param1: 'value',
  param2: 123
});

console.log(result);

API Reference

API Reference

Class.method(param1, param2)

Class.method(param1, param2)

Description of what this method does.
Parameters:
  • param1
    (string): Description of param1
  • param2
    (number): Description of param2
Returns: Description of return value
Example:
javascript
const result = instance.method('value', 42);
Description of what this method does.
Parameters:
  • param1
    (string): Description of param1
  • param2
    (number): Description of param2
Returns: Description of return value
Example:
javascript
const result = instance.method('value', 42);

Configuration

Configuration

Create a 
.configrc
file:
json
{
  "setting1": "value1",
  "setting2": true,
  "setting3": {
    "nested": "value"
  }
}
Create a 
.configrc
file:
json
{
  "setting1": "value1",
  "setting2": true,
  "setting3": {
    "nested": "value"
  }
}

Contributing

Contributing

Contributions are welcome! Please follow these steps:
  1. Fork the repository
  2. Create a feature branch (
    git checkout -b feature/AmazingFeature
    )
  3. Commit your changes (
    git commit -m 'Add some AmazingFeature'
    )
  4. Push to the branch (
    git push origin feature/AmazingFeature
    )
  5. Open a Pull Request
Please read CONTRIBUTING.md for details on our code of conduct and development process.
Contributions are welcome! Please follow these steps:
  1. Fork the repository
  2. Create a feature branch (
    git checkout -b feature/AmazingFeature
    )
  3. Commit your changes (
    git commit -m 'Add some AmazingFeature'
    )
  4. Push to the branch (
    git push origin feature/AmazingFeature
    )
  5. Open a Pull Request
Please read CONTRIBUTING.md for details on our code of conduct and development process.

Testing

Testing

bash
undefined
bash
undefined

Run all tests

Run all tests

npm test
npm test

Run with coverage

Run with coverage

npm run test:coverage
npm run test:coverage

Run in watch mode

Run in watch mode

npm run test:watch
undefined
npm run test:watch
undefined

Deployment

Deployment

bash
undefined
bash
undefined

Build for production

Build for production

npm run build
npm run build

Deploy

Deploy

npm run deploy
undefined
npm run deploy
undefined

Built With

Built With

Versioning

Versioning

We use SemVer for versioning. For available versions, see the tags on this repository.
We use SemVer for versioning. For available versions, see the tags on this repository.

Authors

Authors

See also the list of contributors who participated in this project.
See also the list of contributors who participated in this project.

License

License

This project is licensed under the MIT License - see the LICENSE file for details.
This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Acknowledgments

  • Hat tip to anyone whose code was used
  • Inspiration
  • References
  • Hat tip to anyone whose code was used
  • Inspiration
  • References

Support

Support

Roadmap

Roadmap

  • Feature 1
  • Feature 2
  • Feature 3
  • Feature 4
See the open issues for a full list of proposed features.
  • Feature 1
  • Feature 2
  • Feature 3
  • Feature 4
See the open issues for a full list of proposed features.

FAQ

FAQ

Question 1?

Question 1?

Answer to question 1.
Answer to question 1.

Question 2?

Question 2?

Answer to question 2.
Answer to question 2.

Changelog

Changelog

See CHANGELOG.md for a list of changes.
undefined
See CHANGELOG.md for a list of changes.
undefined

Documentation Best Practices

文档写作最佳实践

File Structure

文件结构

docs/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── guides/
│   ├── getting-started.md
│   ├── installation.md
│   └── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── examples/
    ├── basic-usage.md
    └── advanced-usage.md
docs/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── guides/
│   ├── getting-started.md
│   ├── installation.md
│   └── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── examples/
    ├── basic-usage.md
    └── advanced-usage.md

Linking Between Documents

文档间链接

markdown
Link to another doc:
[Installation Guide](guides/installation.md)

Link to section in current doc:
[See Configuration](#configuration)

Link to section in another doc:
[API Authentication](api/authentication.md#oauth2)

Link to external resource:
[GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/)
markdown
Link to another doc:
[Installation Guide](guides/installation.md)

Link to section in current doc:
[See Configuration](#configuration)

Link to section in another doc:
[API Authentication](api/authentication.md#oauth2)

Link to external resource:
[GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/)

Using Anchors

使用锚点

markdown
Create custom anchors:

<a name="custom-anchor"></a>
markdown
Create custom anchors:

<a name="custom-anchor"></a>

Section Title

Section Title

Link to it: Jump to section
undefined
Link to it: Jump to section
undefined

Collapsible Sections

可折叠区块

markdown
<details>
<summary>Click to expand</summary>

Hidden content goes here.

- Can include lists
- Code blocks
- Images

```javascript
const code = 'works too';
</details> ```
markdown
<details>
<summary>Click to expand</summary>

Hidden content goes here.

- Can include lists
- Code blocks
- Images

```javascript
const code = 'works too';
</details> ```

Syntax Highlighting

语法高亮

markdown
Common languages:
```javascript
```typescript
```python
```bash
```java
```go
```rust
```sql
```json
```yaml
```html
```css
```dockerfile
```graphql
```markdown
markdown
Common languages:
```javascript
```typescript
```python
```bash
```java
```go
```rust
```sql
```json
```yaml
```html
```css
```dockerfile
```graphql
```markdown

Badges

徽章

markdown
![Build Status](https://img.shields.io/github/workflow/status/user/repo/CI)
![Coverage](https://img.shields.io/codecov/c/github/user/repo)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/github/license/user/repo)
![Downloads](https://img.shields.io/npm/dm/package-name)
![Stars](https://img.shields.io/github/stars/user/repo?style=social)
markdown
![Build Status](https://img.shields.io/github/workflow/status/user/repo/CI)
![Coverage](https://img.shields.io/codecov/c/github/user/repo)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/github/license/user/repo)
![Downloads](https://img.shields.io/npm/dm/package-name)
![Stars](https://img.shields.io/github/stars/user/repo?style=social)

Alerts and Callouts

提示与注意事项

markdown
> **Note**
> This is a note

> **Warning**
> This is a warning

> **Important**
> This is important information

GitHub-style alerts (GFM):
> [!NOTE]
> Useful information

> [!TIP]
> Helpful advice

> [!IMPORTANT]
> Key information

> [!WARNING]
> Critical content

> [!CAUTION]
> Negative potential consequences
markdown
> **Note**
> This is a note

> **Warning**
> This is a warning

> **Important**
> This is important information

GitHub-style alerts (GFM):
> [!NOTE]
> Useful information

> [!TIP]
> Helpful advice

> [!IMPORTANT]
> Key information

> [!WARNING]
> Critical content

> [!CAUTION]
> Negative potential consequences

Mermaid Diagrams

Mermaid 图表

markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]
    C --> E[End]
    D --> E
```

```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B->>A: Hello Alice!
```
markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]
    C --> E[End]
    D --> E
```

```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B->>A: Hello Alice!
```

Markdown Tools

Markdown 工具

Linters

代码检查工具

bash
undefined
bash
undefined

markdownlint

markdownlint

npm install -g markdownlint-cli markdownlint '**/*.md'
npm install -g markdownlint-cli markdownlint '**/*.md'

Configuration: .markdownlint.json

Configuration: .markdownlint.json

{ "default": true, "MD013": false, "MD033": false }
undefined
{ "default": true, "MD013": false, "MD033": false }
undefined

Formatters

格式化工具

bash
undefined
bash
undefined

prettier

prettier

npm install -g prettier prettier --write '**/*.md'
npm install -g prettier prettier --write '**/*.md'

Configuration: .prettierrc

Configuration: .prettierrc

{ "proseWrap": "always", "printWidth": 80 }
undefined
{ "proseWrap": "always", "printWidth": 80 }
undefined

Preview

预览工具

bash
undefined
bash
undefined

grip - GitHub README preview

grip - GitHub README preview

pip install grip grip README.md
pip install grip grip README.md

Open http://localhost:6419

Open http://localhost:6419

undefined
undefined

Best Practices

最佳实践

✅ DO

✅ 建议

  • Use descriptive link text
  • Include table of contents for long documents
  • Add alt text to images
  • Use code blocks with language specification
  • Keep lines under 80-100 characters
  • Use relative links for internal docs
  • Add badges for build status, coverage, etc.
  • Include examples and screenshots
  • Use semantic line breaks
  • Test all links regularly
  • 使用描述性链接文本
  • 长文档添加目录
  • 为图片添加替代文本
  • 为代码块指定语言
  • 每行长度控制在80-100字符以内
  • 内部文档使用相对链接
  • 添加构建状态、覆盖率等徽章
  • 包含示例和截图
  • 使用语义化换行
  • 定期测试所有链接

❌ DON'T

❌ 不建议

  • Use "click here" as link text
  • Forget alt text on images
  • Mix HTML and Markdown unnecessarily
  • Use absolute paths for local files
  • Create walls of text without breaks
  • Skip language specification in code blocks
  • Use images for text content (accessibility)
  • 使用“点击这里”作为链接文本
  • 不为图片添加替代文本
  • 不必要地混合HTML和Markdown
  • 本地文件使用绝对路径
  • 无换行的大段文本
  • 代码块不指定语言
  • 使用图片代替文本内容（无障碍考虑）

Resources

参考资源