Skill: markdown

Apply Google Markdown style guide conventions to documentation.

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.

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

Essential Formatting Rules

Document Structure

Every markdown document should follow this layout:

# Document Title

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

[TOC]

## Topic

Content.

## See also

* https://link-to-more-info

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

Headings

Use ATX-style headings:

# 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:

## Foo
### Foo summary
### Foo example

## Bar
### Bar summary
### Bar example

Lists

Nested list spacing - Use 4-space indent:

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:

1.  First item.
1.  Second item.
    1.  Nested item.
    1.  Another nested item.
1.  Third item.

Code

Inline code - Use backticks for short code:

Run `script.sh` to start the process.
Check the `field_name` in the table.

Code blocks - Use fenced blocks with language:

```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

Links

Inline links:

See the [Markdown guide](markdown.md) for more info.

Reference links for long URLs or repeated links:

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

Line Length

Follow 80-character line limit for better tool integration and code review.

Exceptions:

• Links
• Tables
• Headings
• Code blocks

Example:

*   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:

Transport | Favored by | Advantages
--------- | ---------- | -----------
Swallow   | Coconuts   | Fast when unladen
Bicycle   | Miss Gulch | Weatherproof

Use reference links to keep table cells manageable.

Trailing Whitespace

Don't use trailing whitespace. Use backslash for line breaks:

This line needs a break,\
so it continues here.

Better: avoid <br /> entirely by using paragraph breaks (double newline).

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

Common Mistakes to Avoid

❌ Don't use setext-style headings:

Heading
-------

❌ Don't write vague link titles:

Click [here](url) for more info.

❌ Don't use indented code blocks:

    code without language specified

❌ Don't nest with inconsistent spacing:

* Item
 * Badly indented nested item

✅ Do use ATX-style headings with spacing:

## Heading

✅ Do write descriptive link titles:

See the [installation guide](url) for setup instructions.

✅ Do use fenced code blocks with language:

```python
print("Hello")
```

✅ Do use consistent 4-space nesting:

*   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

See Also

• Google Markdown Style Guide
• CommonMark Specification