Markdown Style Guide

This article is the blog’s long-term style guide. It isn’t a Markdown tutorial from scratch; instead, it shows how common writing patterns look after passing through the content pipeline, typographic rules, syntax highlighting, Mermaid rendering, and footnote processing.

Every time the theme is adjusted, this page should make visual regressions easy to spot.

Paragraphs and Reading Rhythm

Syntax

A paragraph is a block of text, separated from other paragraphs by a blank line.

The second paragraph starts after a blank line, and should maintain the same column width, line height, and paragraph spacing.

Effect

A paragraph is a block of text, separated from other paragraphs by a blank line. Long-form typography should maintain a comfortable reading width, sufficient line height, and stable paragraph spacing. The article column should remain readable on phone, tablet, and desktop screens.

The second paragraph starts after a blank line. It should feel connected to the previous paragraph without being too close. Many small spacing issues tend to surface here.

Headings

Syntax

## Chapter heading

### Subsection heading

#### Detail heading

Effect

Subsection heading

Subsection headings introduce a focused topic. They should be easy to discover by scanning, but should not overpower the body text.

Detail heading

Detail headings are suitable for short notes, examples, and local structure within a larger section.

Inline Formatting

Inline formatting works well for emphasis and technical details: bold text, emphasized text, inline code, deleted text, and an ordinary link. Mixed-language typesetting should also feel natural: English text can sit alongside 中文 and 日本語 on the same line without breaking the reading rhythm.

Some inline HTML is also useful in technical writing: H₂O, x², i18n, ⌘ + K, and highlighted text.

Blockquotes

Syntax

> Good typography makes structure visible without making the page feel busy.
>
> Quotes can also contain **emphasis**, links, and multiple paragraphs.

Effect

Good typography makes structure visible without making the page feel busy.

Quotes can also contain emphasis, links, and multiple paragraphs. A well-styled quote should be clearly distinct from body text while still belonging to the article’s visual system.

The paragraph after the quote should cleanly return to the normal body-text rhythm.

Lists

Unordered lists are well suited to feature summaries:

• Typography should maintain stable spacing.
• Links should be clearly visible and easy to access.
• Longer list items should wrap naturally without pushing content out of the article column.

Ordered lists are well suited to workflows:

1. Write a draft.
2. Preview the article.
3. Check both narrow and wide screens.
4. Publish after confirming the formatting is correct.

Nested lists should remain scannable:

• Content checks
  • Headings
  • Paragraphs
  • Links
• Media checks
  • Images
  • Mermaid diagrams
  • Code blocks

Task lists are useful for compatibility checks:

• Paragraphs
• Lists
• Tables
• Footnotes
• Print styles

Tables

Tables should be compact, readable, and safe on narrow screens.

Code Blocks

Use fenced code blocks with language identifiers so syntax highlighting can select the correct grammar.

type BlogPost = {
  title: string;
  description: string;
  tags: string[];
};

function summarizePost(post: BlogPost) {
  return `${post.title} — ${post.description}`;
}

Command-line code should also be displayed clearly:

pnpm install
pnpm dev
pnpm build

To display Markdown source that itself contains a fenced code block, use a longer fence on the outside:

```ts
console.log("Nested fence example");
```

Images

Images should follow the article width, preserve their original aspect ratio, and provide meaningful alternative text.

Diagrams

Mermaid diagrams should be rendered as SVG, while retaining the source diagram text in the Markdown. Diagrams can be scaled inline, dragged when overflowing, and opened via an expand button.

flowchart TD
A[Write Markdown] --> B[Build Content]
B --> C[Render Article]
C --> D[Read in Browser]
D --> E[Detect Regression]

Horizontal Rule

A horizontal rule can separate related but distinct content sections.

The spacing after a horizontal rule should feel intentional, not abrupt.

Footnotes

Footnotes are great for small asides that you don’t want to break the flow of the body text. This sentence contains a short footnote to check the rendering flow.¹

Another sentence can also use a second footnote, putting more detailed notes at the bottom of the article.²

Summary

A good example article should cover a wide enough range of topics and features, yet still be readable. If future style changes affect headings, lists, blockquotes, code blocks, tables, or footnotes, this page should make those problems obvious.