---
title: "Writing template: this post is the template"
pubDate: 2026-11-02
category: tech
tags: [writing, template]
pinned: true
locked: true
description: 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](https://astro.build).

## 2. Colour emphasis: three per page at most

The rule comes from the design baseline: the shell is greyscale, so colour exists to weight one judgement in the body — three per page, maximum. More than that and it turns loud.

<span class="c-blue">First use: state one key conclusion in blue.</span> Then carry on normally.

<span class="c-red">Second use: warn about a trap in red.</span> For example, “after changing a Markdown plugin you must clear `node_modules/.astro`, or the change silently does nothing”.

<span class="c-green">Third use: confirm a working path in green.</span> After three, this section stays uncoloured.

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:

<span class="font-kai">This sentence is in Kai. Good for epigraphs, quoted lines in a review, or paragraphs that should be read slowly.</span>

<span class="font-huiwen">This sentence is in Huiwen Ming. Over a long paragraph it noticeably slows reading, so use it for short lines only.</span>

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.

```ts
// 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">` | three per page at most |
| Typeface | `<span class="font-kai">` | a whole page adds font weight |
| Image | `![alt](./assets/<slug>/x.jpg)` | 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:

![Sample image: a greyscale coast](../posts/assets/media-sample/sample-photo.jpg)

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

<details>
<summary>Open the folded example</summary>

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

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

</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.