Writing template: this post is the template

This is not a tutorial — it is a template you can copy. Every section below actually runs: what you see is what Markdown produces. To start a new post, copy this file, change the slug, and delete what you do not need.

It is also the live sample for pinning: pinned: true in the frontmatter lifts a post to the front of the home page, the archive and the bookshelf, while its date, URL and RSS timestamps stay untouched.

1. Heading levels and paragraphs

Use ## for a section and ### for a subsection. Never use # — the post title comes from the frontmatter title, and a second level-one heading confuses both screen readers and search snippets.

Leave a blank line between paragraphs. Inline you can use bold, italic, strikethrough, inline code, and ordinary links.

2. Colour emphasis: as much as you need

Colour is no longer capped (the old “three per page” limit was lifted on 2026-11-02). The one rule that remains is the shell: navigation, footer, buttons and background stay greyscale — the shell is temperament, the body is expression.

First use: state one key conclusion in blue. Then carry on normally.

Second use: warn about a trap in red. For example, “after changing a Markdown plugin you must clear node_modules/.astro, or the change silently does nothing”.

Confirm a working path in green. If a whole paragraph deserves emphasis, mark the whole paragraph.

There are eight hues (blue / teal / green / yellow / orange / red / pink / purple), each with a standard and a -soft variant, plus four greyscale classes (ink-muted / ink-warm / ink-cool / ink-faint) for lowering tone — those do not count against the colour budget.

3. Typefaces: change only what you wrap

Body text is sans-serif by default. To give one sentence a different temperament, wrap it:

This sentence is in Kai. Good for epigraphs, quoted lines in a review, or paragraphs that should be read slowly.

This sentence is in Huiwen Ming. Over a long paragraph it noticeably slows reading, so use it for short lines only.

Six families are available (font-kai, font-song, font-hei-sys, font-fangsong, font-huiwen, font-kuaile), plus an artistic heading class font-art-kuaile. Mind the weight: switching a whole page to a family makes every visitor download a CJK font, so avoid changing the body default casually.

A level-three heading looks like this

One step smaller than level two, bold, with tighter spacing. Use it to split a section into topics.

4. Quotes and lists

Block quotes are for quoting someone. An attribution can follow as italics.

— an invented attribution

Unordered list:

• First item
• Second item, with inline code
• Third item, nested:
  • Child one
  • Child two

Ordered lists suit steps:

1. Copy the template
2. Change the slug and title in the frontmatter
3. Delete the sections you do not need

5. Code blocks

Blocks of four lines or more get a greyscale window bar (three dots); shorter fragments do not, so small snippets do not look like screenshots.

// Sort contract: pinned first → newest first → id as a tie-breaker
export function sortPosts<T extends Post>(posts: T[]): T[] {
  return [...posts].sort((a, b) => {
    const pin = Number(b.data.pinned === true) - Number(a.data.pinned === true);
    return pin !== 0 ? pin : b.data.pubDate.getTime() - a.data.pubDate.getTime();
  });
}

Refer to variables inline like posts.

6. Tables

7. Images

Reference images by relative path, stored under content/posts/assets/<slug>/; they expand on click and vectors stay sharp:

8. Link cards

A bare URL on its own line becomes an OG preview card at build time; if the fetch fails it degrades to a plain link, never breaking the layout:

Astro

Astro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between.

astro.build

9. Folding long content

Long appendices, full logs and big configs can fold away with zero JavaScript, using native details:

10. Closing after the rule

Three sentences are enough to close: what this covered, what the reader should take away, and where to go next. The template is not a demand to write ten sections — it is a promise that the capabilities are at hand when you need to express something.

Next time, copy this file and delete until only your point remains.