Back to Details

markdown

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: markdown

Skill: Markdown

Apply Google Markdown style guide conventions to documentation.
为文档应用Google Markdown风格指南规范。

Overview

概述

This skill provides markdown formatting guidelines based on the Google Markdown Style Guide. It helps create readable, portable, and maintainable markdown documentation with consistent formatting across projects.
此Skill基于Google Markdown风格指南提供Markdown格式规范。它帮助创建可读性强、可移植且易于维护的Markdown文档，确保跨项目格式一致。

Core Principles

核心原则

Balance three goals:
  1. Source text is readable and portable - Plain text should be easy to read
  2. Corpus is maintainable - Consistent formatting across teams and time
  3. Syntax is simple - Easy to remember and apply
平衡三大目标：
  1. 源文本可读性与可移植性 - 纯文本应易于阅读
  2. 文档库可维护性 - 跨团队和时间保持格式一致
  3. 语法简洁性 - 易于记忆和应用

Essential Formatting Rules

关键格式规则

Document Structure

文档结构

Every markdown document should follow this layout:
markdown
undefined
每个Markdown文档应遵循以下布局：
markdown
undefined

Document Title

Document Title

Short introduction (1-3 sentences providing high-level overview).
[TOC]
Short introduction (1-3 sentences providing high-level overview).
[TOC]

Topic

Topic

Content.
Content.

See also

See also


**Key elements**:
- **H1 title** - First heading at level 1, matching or similar to filename
- **Introduction** - Brief overview for newcomers
- **[TOC]** - Table of contents after introduction (if supported by hosting)
- **H2+ headings** - All subsequent headings start from level 2
- **See also** - Miscellaneous links at bottom

**核心元素**:
- **H1标题** - 文档首个一级标题，与文件名匹配或类似
- **引言** - 为新手提供的简要概述
- **[TOC]** - 引言后添加目录（若托管平台支持）
- **H2及以上标题** - 所有后续标题从二级开始
- **相关链接** - 文档底部添加杂项链接

Headings

标题

Use ATX-style headings:
markdown
undefined
使用ATX风格标题:
markdown
undefined

Heading 1

Heading 1

Heading 2

Heading 2

Heading 3

Heading 3


**Best practices**:
- Add spacing: blank line before and after headings
- Space after `#`: `## Heading` not `##Heading`
- Use unique, descriptive names for each heading
- One H1 heading per document (the title)
- Follow sentence case capitalization for titles

**Example**:
```markdown

**最佳实践**:
- 添加间距：标题前后各留空行
- `#`后加空格：应为`## Heading`而非`##Heading`
- 为每个标题使用独特且描述性的名称
- 每个文档仅含一个H1标题（即文档标题）
- 标题采用句首大写格式

**示例**:
```markdown

Foo

Foo

Foo summary

Foo summary

Foo example

Foo example

Bar

Bar

Bar summary

Bar summary

Bar example

Bar example

undefined
undefined

Lists

列表

Nested list spacing - Use 4-space indent:
markdown
1.  First item (2 spaces after number).
    Wrapped text uses 4-space indent.
2.  Second item.

*   Bullet item (3 spaces after asterisk).
    Wrapped text uses 4-space indent.
    1.  Nested numbered item.
        8-space indent for wrapped text.
    2.  Another nested item.
*   Back to bullets.
Lazy numbering for long lists:
markdown
1.  First item.
1.  Second item.
    1.  Nested item.
    1.  Another nested item.
1.  Third item.
嵌套列表间距 - 使用4空格缩进:
markdown
1.  First item (2 spaces after number).
    Wrapped text uses 4-space indent.
2.  Second item.

*   Bullet item (3 spaces after asterisk).
    Wrapped text uses 4-space indent.
    1.  Nested numbered item.
        8-space indent for wrapped text.
    2.  Another nested item.
*   Back to bullets.
长列表使用简化编号:
markdown
1.  First item.
1.  Second item.
    1.  Nested item.
    1.  Another nested item.
1.  Third item.

Code

代码

Inline code - Use backticks for short code:
markdown
Run `script.sh` to start the process.
Check the `field_name` in the table.
Code blocks - Use fenced blocks with language:
markdown
```python
def foo(bar):
    return bar * 2
```
Best practices:
  • Always declare the language
  • Use fenced blocks, not indented blocks
  • Escape newlines in shell commands with 
    \
  • Nest code blocks in lists with proper indentation
行内代码 - 用反引号包裹短代码:
markdown
Run `script.sh` to start the process.
Check the `field_name` in the table.
代码块 - 使用带语言标识的围栏式代码块:
markdown
```python
def foo(bar):
    return bar * 2
```
最佳实践:
  • 始终声明代码语言
  • 使用围栏式代码块，而非缩进式代码块
  • 用
    \
    转义Shell命令中的换行符
  • 在列表中嵌套代码块时使用正确的缩进

Links

链接

Inline links:
markdown
See the [Markdown guide](markdown.md) for more info.
Reference links for long URLs or repeated links:
markdown
See the [style guide] for details.

[style guide]: https://google.github.io/styleguide/docguide/style.html
Best practices:
  • Use informative link titles (not "here" or "link")
  • Use explicit paths, avoid 
    ../
    relative paths
  • Define reference links after first use, before next heading
  • Use reference links in tables to keep cells readable
行内链接:
markdown
See the [Markdown guide](markdown.md) for more info.
长URL或重复链接使用参考链接:
markdown
See the [style guide] for details.

[style guide]: https://google.github.io/styleguide/docguide/style.html
最佳实践:
  • 使用信息丰富的链接标题（避免使用「这里」或「链接」）
  • 使用明确路径，避免
    ../
    相对路径
  • 在首次使用后、下一个标题前定义参考链接
  • 在表格中使用参考链接以保持单元格可读性

Line Length

行长度

Follow 80-character line limit for better tool integration and code review.
Exceptions:
  • Links
  • Tables
  • Headings
  • Code blocks
Example:
markdown
*   See the
    [documentation](https://very-long-url.example.com/path/to/docs).
    for more details.
遵循80字符行限制，以更好地适配工具集成和代码审查。
例外情况:
  • 链接
  • 表格
  • 标题
  • 代码块
示例:
markdown
*   See the
    [documentation](https://very-long-url.example.com/path/to/docs).
    for more details.

Tables

表格

Use tables for tabular data that needs quick scanning. Avoid for data better presented as lists.
Good table use:
  • Uniform data distribution
  • Many parallel items with distinct attributes
  • Need for quick comparison
Example:
markdown
Transport | Favored by | Advantages
--------- | ---------- | -----------
Swallow   | Coconuts   | Fast when unladen
Bicycle   | Miss Gulch | Weatherproof
Use reference links to keep table cells manageable.
表格适用于需要快速浏览的表格型数据。若数据更适合用列表呈现，则避免使用表格。
表格适用场景:
  • 数据分布均匀
  • 多个并行条目具有不同属性
  • 需要快速比较
示例:
markdown
Transport | Favored by | Advantages
--------- | ---------- | -----------
Swallow   | Coconuts   | Fast when unladen
Bicycle   | Miss Gulch | Weatherproof
使用参考链接保持表格单元格简洁。

Trailing Whitespace

尾随空白

Don't use trailing whitespace. Use backslash for line breaks:
markdown
This line needs a break,\
so it continues here.
Better: avoid 
<br />
entirely by using paragraph breaks (double newline).
不要使用尾随空白。如需换行，使用反斜杠:
markdown
This line needs a break,\
so it continues here.
更佳方案：通过段落分隔（双换行）完全避免使用
<br />
。

Quick Reference

快速参考

Headings:
  • ATX-style: 
    # H1
    , 
    ## H2
    , 
    ### H3
  • Add blank lines before/after
  • One H1 per document
Lists:
  • 4-space indent for all nested content
  • Lazy numbering: 
    1.
    for all items in long lists
Code:
  • Inline: 
    `code`
  • Blocks: 
    ```language
    with language specified
Links:
  • Informative titles
  • Reference links for long/repeated URLs
Line length:
  • 80 characters (except links, tables, headings, code)
Whitespace:
  • No trailing whitespace
  • Use 
    \
    for line breaks if needed
标题:
  • ATX风格: 
    # H1
    , 
    ## H2
    , 
    ### H3
  • 前后各留空行
  • 每个文档仅一个H1
列表:
  • 所有嵌套内容使用4空格缩进
  • 长列表所有条目使用
    1.
    简化编号
代码:
  • 行内: 
    `code`
  • 代码块: 
    ```language
    并指定语言
链接:
  • 使用信息丰富的标题
  • 长/重复URL使用参考链接
行长度:
  • 80字符（链接、表格、标题、代码块除外）
空白:
  • 无尾随空白
  • 如需换行使用
    \

Common Mistakes to Avoid

常见错误规避

❌ Don't use setext-style headings:
markdown
Heading
-------
❌ Don't write vague link titles:
markdown
Click [here](url) for more info.
❌ Don't use indented code blocks:
markdown
    code without language specified
❌ Don't nest with inconsistent spacing:
markdown
* Item
 * Badly indented nested item
✅ Do use ATX-style headings with spacing:
markdown
undefined
❌ 不要使用Setext风格标题:
markdown
Heading
-------
❌ 不要使用模糊的链接标题:
markdown
Click [here](url) for more info.
❌ 不要使用缩进式代码块:
markdown
    code without language specified
❌ 不要使用不一致的嵌套间距:
markdown
* Item
 * Badly indented nested item
✅ 应使用带间距的ATX风格标题:
markdown
undefined

Heading

Heading


✅ Do write descriptive link titles:
```markdown
See the [installation guide](url) for setup instructions.
✅ Do use fenced code blocks with language:
markdown
```python
print("Hello")
```
✅ Do use consistent 4-space nesting:
markdown
*   Item
    *   Properly indented nested item

✅ 应使用描述性的链接标题:
```markdown
See the [installation guide](url) for setup instructions.
✅ 应使用带语言标识的围栏式代码块:
markdown
```python
print("Hello")
```
✅ 应使用一致的4空格嵌套:
markdown
*   Item
    *   Properly indented nested item

Additional Resources

额外资源

Reference Files

参考文件

For complete style guide details:
  • references/style-guide.md
     - Full Google Markdown Style Guide with all rules, examples, and edge cases
如需完整的风格指南细节:
  • references/style-guide.md
     - 完整的Google Markdown风格指南，包含所有规则、示例和边缘情况

See Also

相关链接