wait4xandGLM-5.3
5bf0c327bf
用户要「在文章中加一篇关于文章书写的模板示例」，故交付一篇**可复制**的模板
文章而非干条文：正文每节都在真跑一种能力，读者看到的效果就是源码的效果。
- content/posts/writing-template.md（zh）与 posts-en 同名 en 版（locked:true
手写直译，不交给 TMT 重译）：标题层级纪律、彩色强调（一页三处限额）、
字族（楷/汇文明朝各一处 + 六族清单）、引用/列表/代码窗条/表格/图片放大/
链接卡片/details 折叠/分隔线
- pinned: true —— 这篇文章同时是置顶功能的活样本（归档首条实测）
- 后台 moments.text 由 text widget 改 markdown widget + 排版类提示：瞬间从此
与文章同级表达力（字体/颜色/多段），提示里写明外壳灰阶纪律
- docs/写作指南.md 新增三节：写作模板（cp 起步 + 三条纪律）、置顶文章
（语义边界：只改顺序不改 pubDate/URL/RSS）、瞬间怎么写（富文本 + 逐条评论
+ 只读计数 + text/image 至少一项）
验证: pnpm astro build 51 页 exit 0；content-lint 51 页 0 断链 0 缺图；
产物断言 c-blue/font-kai/font-huiwen/details/table 全部生效；
dist/archives 首条 = writing-template（置顶排序生效）
Spec: 2026-11-02_blog-5h-content-social (T7)
Co-authored-by: GLM-5.3
126 lines
5.4 KiB
Markdown
126 lines
5.4 KiB
Markdown
---
|
|
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 | `` | 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`:
|
|
|
|
<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.
|