blog/content/posts-en/writing-template.md

title, pubDate, category, tags, pinned, locked, description

title	pubDate	category	tags	pinned	locked	description
Writing template: this post is the template	2026-11-02	tech	writing template	true	true	One post that exercises every typographic capability on the site — heading levels, colour emphasis, typefaces, quotes, code windows, tables, images, link cards, folding. Copy it to start a new post.

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

Capability	Syntax	Note
Colour emphasis	<span class="c-blue">	no limit (shell stays greyscale)
Typeface	<span class="font-kai">	a whole page adds font weight
Image		see the writing guide for size rules
Video	frontmatter video:	lives in public/media, ≤50MB
Link card	a bare URL on its own line	OG fetched at build time, falls back to a plain link

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:

https://astro.build

9. Folding long content

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

Open the folded example

A folded region can hold anything — paragraphs, lists, code blocks.

• Best for “read on demand” detail
• Not for conclusions (readers may never open it)

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.