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:

Source text is readable and portable - Plain text should be easy to read
Corpus is maintainable - Consistent formatting across teams and time
Syntax is simple - Easy to remember and apply

平衡三大目标：

源文本可读性与可移植性 - 纯文本应易于阅读
文档库可维护性 - 跨团队和时间保持格式一致
语法简洁性 - 易于记忆和应用

Essential Formatting Rules

关键格式规则

Document Structure

文档结构

Every markdown document should follow this layout:

markdown

undefined

每个Markdown文档应遵循以下布局：

markdown

undefined

Document Title

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

[TOC]

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

[TOC]

Topic

Content.

Heading 1

Heading 2

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 summary

Foo example

Bar

Bar summary

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命令中的换行符
在列表中嵌套代码块时使用正确的缩进

链接

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


✅ 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风格指南，包含所有规则、示例和边缘情况

markdown

Original

Translation

Skill: markdown

Skill: Markdown

Overview

概述

Core Principles

核心原则

Essential Formatting Rules

关键格式规则

Document Structure

文档结构

Document Title

Document Title

Topic

Topic

See also

See also

Headings

标题

Heading 1

Heading 1

Heading 2

Heading 2

Heading 3

Heading 3

Foo

Foo

Foo summary

Foo summary

Foo example

Foo example

Bar

Bar

Bar summary

Bar summary

Bar example

Bar example

Lists

列表

Code

代码

Links

链接

Line Length

行长度

Tables

表格

Trailing Whitespace

尾随空白

Quick Reference

快速参考

Common Mistakes to Avoid

常见错误规避

Heading

Heading

Additional Resources

额外资源

Reference Files

参考文件

See Also

相关链接