Markdown Style

markdown-style

The Markdown authoring and review skill. Owns two layers of rules and the procedure for applying them:

1. Syntax canon — what valid Markdown looks like. Derived from the Markdown Guide basic-syntax reference. Full canon: references/syntax-canon.md. 2. Style overlay — opinionated rules a reviewer enforces on top of valid syntax. Derived from Google's Markdown style guide. Full overlay: references/style-overlay.md.

Load this skill when the question is "is this doc well-formed?" — not "does this doc belong here?" (that is doc-diagnostic). Style review never decides whether a doc should exist. It assumes the doc earned its place and asks whether the prose, structure, and Markdown are clean.

How to run a review

Run in two passes. Do not interleave them — the architect reads a syntax violation differently from a style violation, and conflating the two confuses the response.

Pass 1 — Syntax (must-fix)

Walk the file top to bottom. For each construct that violates the syntax canon (setext heading where ATX is expected, unfenced code block, missing blank line around a block element, ordered list using ) instead of ., etc.), emit one finding at a time:

Line N:
  Original: <verbatim line(s)>
  Layer:    syntax
  Rule:     <one-line rule from references/syntax-canon.md>
  Rewrite:  <corrected line(s)>
  Apply?    yes / no / adjust

Wait for the architect's reply before flagging the next finding. No bulk edits. Syntax findings always come before style findings.

Pass 2 — Style (should-fix)

Re-walk the file. For each violation of the style overlay (heading > H2 used as the document title, no [TOC] directive on a long doc, prose line > 80 characters outside an exception, uninformative link text like "here", reference link defined far from its use, generic repeated subheading like "Summary" under multiple parents, etc.), emit the same finding format with Layer: style.

The style pass is suggestion, not enforcement. The architect can decline any finding without justification — the rule is opinionated, not canonical. Reasonable disagreement is acceptable; flag it and move on.

Apply approved findings

After both passes are complete, apply only the approved rewrites in a single Edit pass. No audit markers in the file. No [reviewed] stamps. The diff is the audit trail.

The two layers — quick reference

Detailed rules live in references/. The summaries below cover the violations that account for most findings.

Syntax (must-fix) — quick reference

Full canon with examples and known-broken edge cases: references/syntax-canon.md.

Style (should-fix) — quick reference

Full overlay with rationales: references/style-overlay.md.

Routing — what this skill does not own

• "Should this doc exist?" -> doc-diagnostic (four-question diagnostic).
• "Is this ADR honest?" -> adr-critique (line-by-line audit against the "ADR is NOT" checklist — a content audit, not a form audit). Style and ADR critique can run on the same file; run ADR critique first because supersession may invalidate style work.
• "Where does this doc belong?" -> doc-diagnostic alternatives catalog.
• "Is the prose understandable?" -> out of scope. This skill enforces Markdown form, not prose clarity. Suggest a doc-diagnostic Audience check if the prose is unfit for its named audience.

What this skill does NOT cover

This skill is Markdown form only. It covers heading style, list indentation, code-fence language tags, link syntax, line length, and the rest of the Markdown-Guide / Google-style-overlay rule sets. It does not cover:

• Prose-level enforcement — terminology consistency, inclusive-language substitutions, banned phrases, voice / tense / mood rules. The next layer up for that work is [Vale](https://vale.sh) (the prose-linter framework that runs configurable style packs over Markdown, AsciiDoc, reST, HTML, and more). Vale composes well with this skill: doc-master fixes the Markdown form; Vale enforces the prose terminology. doc-master does not bundle Vale or its rule packs.
• AsciiDoc / reStructuredText / org-mode / MDX — this skill is Markdown only. Other lightweight markup languages have their own canonical rules; reach for the matching tool (e.g., asciidoctor --safe-mode).
• Spelling and grammar — out of scope. Use a spell checker (codespell, hunspell, LanguageTool) in addition to this skill, not instead.

Hard limits

• The skill flags findings — it does not bulk-rewrite. One finding at a time, per-line approval, mirrors adr-critique.
• Syntax findings ("must-fix") take precedence over style findings ("should-fix"). Never re-order.
• The skill does not invent new rules. Every finding must cite a rule from references/syntax-canon.md or references/style-overlay.md. If the user disputes a style finding, default to the user — the overlay is opinionated.
• The skill respects project-local conventions when they conflict with the canon (e.g., a project that has standardized on _underscore_ emphasis). Note the conflict; defer to the project.

Examples

<example> <user_query>Lint this README — I think the formatting is messy.</user_query> <response> Loading the markdown-style skill. Two-pass review: syntax findings first (must-fix), then style findings (should-fix), one finding at a time with per-line approval.

Send the file path (or paste the content) and I will start the syntax pass. </response> </example>

<example> <user_query>Is === under a heading line valid Markdown?</user_query> <response> Yes — that is setext-style H1. It is valid Markdown. But the style overlay (and most modern style guides, including Google's) prefer ATX style (# Heading) because setext underlines are "annoying to maintain," do not scale past H2, and obscure the heading level when scanning the file.

Recommendation: replace === with a single #. I can do that as a syntax-equivalent rewrite (no semantic change) if you point me at the file. </response> </example>

<example> <user_query>What's the heading style for our docs?</user_query> <response> The skill's default is ATX (#, ##, ..., ######), one H1 used as the document title, subsequent headings start at H2, sentence-style capitalization, blank lines before and after. That mirrors Google's Markdown style guide.

If your project already has a different convention (e.g., all headings start at H1, or you use setext for top-level titles), tell me and I will defer to the project. The skill is opinionated but yields to project-local rules — note the conflict, move on. </response> </example>

Attribution

The two layers in this skill are derived from publicly available style references:

• Syntax canon — distilled from the Markdown Guide basic-syntax reference (https://www.markdownguide.org/basic-syntax/), licensed CC BY-SA 4.0. See NOTICES.md at the plugin root.
• Style overlay — distilled from Google's developer documentation Markdown style guide (https://google.github.io/styleguide/docguide/style.html), part of google/styleguide (Apache License 2.0). See NOTICES.md.

The skill distills load-bearing rules from each source; it does not reproduce either document verbatim. When the user needs the original text, link out — do not paste long excerpts into this skill.

Markdown style overlay

The "what is good" layer. Distilled from Google's developer documentation Markdown style guide (https://google.github.io/styleguide/docguide/style.html, Apache 2.0). For the "what is valid" layer, see syntax-canon.md.

Findings in this file are should-fix, not must-fix. The architect can decline any finding without justification — these rules are opinionated. Where the project has a local convention that conflicts with a rule here, defer to the project.

The skill cites style findings by short name (e.g., style/headings/atx-only) so the architect can locate them here.

Authoring philosophy

style/philosophy/minimum-viable

"Minimum viable documentation" — a small, fresh, accurate set of docs beats a sprawling stale one. Delete cruft frequently. This dovetails with doc-diagnostic's anti-padding rule.

style/philosophy/better-than-best

Reviewers should LGTM quickly when the change is reasonable, suggest concrete alternatives instead of blocking, and only block when the change makes the docs worse. Authors should not bikeshed.

Headings

style/headings/atx-only

Use ATX style (#, ##, ...). Do not use setext (=== / --- underlines). Setext is "annoying to maintain" and cannot express H3 or below.

style/headings/single-h1

Exactly one H1 per document, used as the title. Subsequent headings start at H2. The H1 should match (or nearly match) the filename — both are read as the document's identifier.

style/headings/unique-names

Avoid bare repeated subheadings like "Summary" or "Example" under multiple parents. Prefix with the parent topic — "Foo summary", "Bar summary" — so the auto-generated anchor is intuitive.

style/headings/sentence-case-and-product-names

Follow the project's title-case convention (the original Google guide refers out to a broader prose style guide for this). Always preserve product / tool / binary name capitalization — write Markdown, not markdown; GitHub, not github.

style/headings/blank-lines-around

Always put a blank line before and after the heading. This is technically a syntax rule too, but the style overlay enforces it strictly — some processors recover, but the source must be portable.

Document skeleton

style/skeleton/recommended

The recommended document skeleton:

# Document Title

<optional one-line author or owner indication>

<1–3 sentence introduction, written for a newcomer who knows the system exists but not this doc.>

[TOC]

## Topic

…

## Another topic

…

## See also

- [Related doc](/path/to/related.md)

The skeleton is not mandatory, but every deviation should have a reason.

style/skeleton/title-matches-filename

The H1 title should match (or nearly match) the filename. request-routing.md -> # Request routing, not # How the Routing System Works.

style/skeleton/intro-1-to-3-sentences

The intro is 1–3 sentences and answers "what is this doc, who is it for, what will I get from it." Longer intros become unread preamble.

style/skeleton/see-also-section

A final ## See also section is the canonical location for links the reader might want next. Reference-style links inside See also keep it scannable.

Table of contents

style/toc/use-when-long

Use the [TOC] directive for any document that does not fit on one laptop screen. Short docs do not need a TOC — it adds noise.

style/toc/placement

Place [TOC] between the introduction and the first ## H2. Position matters for screen readers and keyboard navigation, since [TOC] injects the table of contents at that point in the DOM.

Line length

style/line-length/80

Wrap prose lines at 80 characters. Rationale: Code Search does not soft-wrap, and 80 mirrors the surrounding code conventions.

style/line-length/exceptions

The 80-character rule does not apply to:

• Links (one URL per line is fine even if it overflows).
• Table rows (cell content cannot wrap; the line will be as long as the widest cell).
• Headings (a heading is one logical line).
• Code blocks (preserve the original code).

The prose around a long link still wraps — only the line with the link is allowed to overflow.

Whitespace and line breaks

style/whitespace/no-trailing

No trailing whitespace on any line. This overrides the syntax-valid two-trailing-spaces-for-<br> trick because trailing whitespace is invisible, removed by IDE cleanup, and rejected by presubmit checks. Use a paragraph break (blank line) instead.

style/line-breaks/sparingly

Use a trailing \ for hard breaks sparingly. Prefer paragraph breaks for separation; prefer block-level constructs (lists, blockquotes) for structure.

Lists

style/lists/lazy-numbering-long

For long or nested ordered lists, use lazy numbering — repeat 1. on every item. Rationale: editing is easier (no renumbering after an insert), and rendered output is identical.

style/lists/full-numbering-short

For short, stable, top-level ordered lists, fully numbered (1., 2., 3.) is fine and more readable in the raw source.

style/lists/indent-4

Nested items and wrapped item text use 4-space indentation. Two spaces after the item number / three spaces after a bullet, so all content aligns at column 4. Wrapped text inside a nested item needs 8-space indent.

style/lists/single-space-only-for-trivial

Single-space (* Foo) is acceptable only when the list is short, flat, and every item is single-line. For anything else, prefer the 2-spaces-after-number form so continuations align cleanly.

style/lists/prefer-list-to-table

Prefer a list to a table when the data is one-dimensional. Tables are for two-dimensional data with parallel attributes.

Code

style/code/fenced-only

Always use fenced code blocks ( ` ). Do not use 4-space-indented blocks. Rationale: indented blocks cannot specify a language, have ambiguous boundaries, and are harder to find in Code Search.

style/code/declare-language

Always declare a language on the fence:

````markdown

…

````

Use text (or none) when there is genuinely no language.

style/code/inline-backticks-for-escapes

Use inline backticks for short code, field names, file types ( README.md ), and to escape strings that should not be auto-linked or parsed — fake paths, example URLs containing $VAR, placeholder identifiers.

style/code/escape-shell-newlines

In shell snippets that wrap, escape the newline with \ so users can copy-paste the whole command:

docker run --rm \
  --name example \
  -p 8080:8080 \
  example:latest

style/code/inside-lists

Fenced code blocks inside lists must indent to align with the list item's text — 4 spaces from the bullet, 4 more spaces for any extra nesting level.

Links

style/links/repo-absolute

For links within the same repo, prefer explicit absolute paths: […](/path/to/page.md). Do not use the full https://… URL for in-repo links — it breaks when the repo moves.

style/links/avoid-relative-traversal

../ relative paths are fragile. Same-directory relative (./neighbor.md) is fine; anything that traverses up is not.

style/links/informative-text

The link text must be informative. Never use "here", "link", "this", or the raw URL as the label. Write the sentence naturally, then wrap the most meaningful phrase.

• Bad: For more information, click here.
• Good: See the request-routing reference for the full middleware order.

style/links/reference-style-when

Use reference-style links when:

• The inline URL would hurt the readability of the surrounding sentence.
• The same destination is referenced multiple times — reference-style eliminates duplication.
• The link sits inside a table cell, because cells cannot wrap a long URL.

Do not use reference-style when the URL is short and inline would read just as cleanly.

style/links/reference-placement

Reference link definitions go just before the next heading, at the end of the section where the link is first used. Treat them like footnotes scoped to a section.

Exception: a link used across multiple sections goes at the end of the document, so moving a section does not leave a dangling reference.

Images

style/images/sparingly

Use images sparingly. Prose tends to age better than screenshots.

style/images/when-justified

Use an image when showing is genuinely easier than describing — UI navigation, architectural diagrams, chart output. Otherwise prefer prose.

style/images/alt-text-required

Always include alt text. The alt text is the only content available to a non-sighted reader.

Tables

style/tables/scannable-two-dimensional

Use tables only for scannable, tabular data with two-dimensional structure and many parallel items with distinct attributes.

style/tables/avoid-when

Avoid tables that exhibit:

• Poor distribution — many empty cells, or one column that does not vary.
• Unbalanced row-to-column ratio — too tall and narrow, or too wide and short.
• Rambling prose in cells — Markdown cannot wrap cell text across lines.

style/tables/short-cells

Tables may exceed the 80-character line-length rule. Keep cells short. Use reference-style links inside cells to keep widths reasonable.

HTML

style/html/avoid

Strongly prefer Markdown to HTML. The one acknowledged exception is large tables that need features Markdown tables cannot express (colspan, rowspan, nested block content). Note that some renderers (the original guide cites Gitiles) do not render HTML at all.

Capitalization

style/capitalization/preserve-names

Preserve product / tool / binary capitalization in headings and prose alike: Markdown, GitHub, Kubernetes, npm (yes, lowercase), iOS, kubectl.

Items the style overlay does not specify

The source guide is deliberately silent on:

• Emphasis convention — **bold** vs __bold__, *italic* vs _italic_. The syntax canon already covers compatibility; the style overlay does not pick a winner. Follow project convention.
• File naming — only that the H1 should match or nearly match the filename. No imposed kebab-case vs snake_case rule.
• Hard document length thresholds — only the qualitative "above the fold on a laptop" criterion for whether [TOC] is justified.

When the architect asks "what should I do about X" and X is on this list, the skill responds: "the style guide is silent — follow the project's existing convention, or pick one and apply it consistently."

Markdown syntax canon

The "what is valid" layer. Distilled from the Markdown Guide basic-syntax reference (https://www.markdownguide.org/basic-syntax/, CC BY-SA 4.0). For the "what is good" layer, see style-overlay.md.

A finding in this file is a must-fix — the construct is either invalid or so inconsistently rendered across processors that it counts as a bug. The skill cites the rule by its short name (e.g., syntax/headings/atx-space-after) so the architect can locate it here.

Headings

syntax/headings/atx

ATX style uses 1–6 # characters at the start of a line.

# H1
## H2
### H3
###### H6

The number of # characters equals the heading level.

syntax/headings/atx-space-after

A space must follow the #. #Heading is not a heading on most processors. # Heading is.

syntax/headings/blank-lines-around

Put a blank line before and after every heading. Some processors recover from missing blank lines; others render the heading inline. Always include them.

syntax/headings/setext

Setext style underlines text:

Heading level 1
===============

Heading level 2
---------------

=== becomes H1; --- becomes H2. Setext only supports levels 1–2 — it cannot express H3 and below. Valid, but the style overlay prefers ATX.

Paragraphs

syntax/paragraphs/blank-line-separator

Paragraphs are separated by a blank line. Two consecutive non-blank lines are part of the same paragraph.

syntax/paragraphs/no-indent

Do not indent paragraphs with tabs or spaces. Indentation has block-level meaning (code, list continuation) and triggers "unexpected formatting problems."

Line breaks

syntax/line-breaks/two-trailing-spaces

End a line with two or more trailing spaces, then return, to produce a <br>. This is the original Markdown syntax and is widely supported but is "controversial" because trailing whitespace is invisible.

syntax/line-breaks/br-tag

The <br> HTML tag is universally supported and more visible than trailing whitespace.

syntax/line-breaks/backslash

A trailing \ at line end works in CommonMark but is not universally supported. Prefer paragraph breaks where possible.

Emphasis

syntax/emphasis/bold

**bold** or __bold__ becomes <strong>bold</strong>.

syntax/emphasis/italic

*italic* or _italic_ becomes <em>italic</em>.

syntax/emphasis/bold-italic

***both*** (or ***both***, **_both_**, *__both__*) becomes bold and italic.

syntax/emphasis/mid-word-asterisks

For emphasis in the middle of a word (e.g., Love**is**bold), use asterisks only. Underscores are not handled consistently mid-word across processors.

Blockquotes

syntax/blockquote/prefix

Prefix the line with >:

> A blockquote.

syntax/blockquote/multi-paragraph

For multi-paragraph quotes, put > on the blank line between paragraphs:

> First paragraph.
>
> Second paragraph.

syntax/blockquote/nesting

Nest with >>:

> Outer.
>
>> Inner.

syntax/blockquote/contents

Blockquotes can contain headings, lists, and emphasis. Put blank lines before and after the blockquote.

Lists

syntax/lists/ordered-period

Ordered list items use a number followed by a period:

1. First
2. Second
3. Third

1) is not portable. Use ..

syntax/lists/ordered-start-at-1

The first item must be 1. The remaining items can repeat 1. (lazy numbering) or count up (2., 3., ...). The starting number determines the rendered start.

syntax/lists/unordered-marker

Use -, *, or +. Pick one per list. Mixing markers within a single list is invalid.

syntax/lists/nested-indent-4

To attach a paragraph, blockquote, image, or nested list to an item, indent the continuation 4 spaces (one tab):

- Item
  - This nested item is two spaces; some processors accept it but it is not portable.
- Item
    - This nested item is 4 spaces; portable.

syntax/lists/nested-code-indent-8

To attach a code block to a list item, indent the code 8 spaces (two tabs).

syntax/lists/escape-leading-number

To start an unordered item with <number>., escape the period: - 1968\. A great year! Otherwise some processors treat the line as an ordered-list item.

Code

syntax/code/inline-backticks

Inline code uses single backticks: ` nano `.

syntax/code/inline-double-backticks

If the inline code contains a backtick, wrap it in double backticks: `` use code here ``.

syntax/code/indented-block

A code block can be indicated by indenting every line at least 4 spaces (one tab). This is the original Markdown syntax — valid, but the style overlay strongly prefers fenced blocks.

syntax/code/fenced-block

Fenced blocks use three backticks (or three tildes) on their own line, optionally followed by a language tag:

````markdown

def foo():
    pass

````

Fenced blocks are an extended-syntax feature — supported by every modern processor and the style overlay's recommended default.

Horizontal rules

syntax/horizontal-rule

Three or more ---, ***, or ___ alone on a line:

---

Put blank lines before and after. Otherwise --- directly after a non-blank line is parsed as a setext H2 underline.

Links

syntax/links/inline

[link text](https://example.com).

syntax/links/inline-title

[link text](https://example.com "tooltip title"). The title shows on hover.

syntax/links/autolinks

<https://example.com> or <user@example.com>. The angle brackets are required for autolinks.

syntax/links/emphasis-and-code

Links can be emphasized: **[EFF](https://eff.org)**. They can wrap inline code: ` [code](#anchor) `.

syntax/links/reference-style

Define the link target elsewhere in the document:

This is a [hobbit-hole][1].

[1]: https://en.wikipedia.org/wiki/Hobbit "Hobbit hole"

The reference label is case-insensitive. The definition can use any of [label]: url, [label]: url "title", [label]: <url> "title".

syntax/links/url-encoding

URLs with spaces or parentheses break inline link syntax. URL-encode: space -> %20, ( -> %28, ) -> %29. If that is impractical, fall back to a raw <a href="…"> HTML tag.

Images

syntax/images/inline

![alt text](path/to/image.jpg) — alt text is required. Optional title: ![alt](path "title").

syntax/images/linked

Wrap the image markdown in a link to make the image itself clickable:

[![alt](image.jpg "title")](https://example.com)

Escaping

syntax/escape

Prefix the following with \ to render them literally rather than as Markdown:

\  `  *  _  {  }  [  ]  <  >  (  )  #  +  -  .  !  |

Example: \*not italic\* renders as *not italic*.

Inline HTML

syntax/html/inline-allowed

You can embed HTML in Markdown: <em>word</em>, <sub>subscript</sub>, etc. Useful when Markdown cannot express the construct (e.g., colspan in a table).

syntax/html/block-level-blank-lines

Block-level HTML (<div>, <table>, <pre>, <p>) must be separated from surrounding Markdown by blank lines.

syntax/html/block-level-no-indent

Block-level HTML tags must not be indented. Indented HTML is parsed as a code block.

syntax/html/markdown-inside-block-html

Markdown syntax does not work inside block-level HTML. The contents of a <div> are rendered as HTML, not Markdown.

Known compatibility footguns

The Markdown Guide lists these as "processors don't agree":

• Underscores mid-word for emphasis — use asterisks.
• Mixed list delimiters within one list — pick one and stick with it.
• Missing space after # in a heading — always include the space.
• ) as an ordered-list delimiter — use ..
• Missing blank lines around block elements — always include them.

The skill flags violations of these as syntax findings even when the processor in use happens to handle them, because the source is then non-portable.