feat(content): 写作模板示例文章与文档（5h T7 主体）
用户要「在文章中加一篇关于文章书写的模板示例」，故交付一篇**可复制**的模板
文章而非干条文：正文每节都在真跑一种能力，读者看到的效果就是源码的效果。
- 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
This commit is contained in:
wait4xandGLM-5.3 committed
1 parent
6538311387
commit
5bf0c327bf
4 files changed
+301
-1
No files matched your search
@@ -0,0 +1,125 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: "写作模板：这篇文章本身就是模板"
|
||||
pubDate: 2026-11-02
|
||||
category: tech
|
||||
tags: [写作, 模板]
|
||||
pinned: true
|
||||
description: 一篇文章演示全站可用的排版能力：标题层级、彩色强调、字族、引用、代码窗、表格、图、链接卡、折叠。复制它开始写新文。
|
||||
---
|
||||
|
||||
这篇不是教程，是**可复制的模板**。下面每一节都在真跑——你看到的效果，就是 Markdown 源码能产出的效果。写新文章时，把本文件复制一份、改个 slug、删掉不需要的段落即可。
|
||||
|
||||
它同时是**置顶功能**的活样本：`frontmatter` 里的 `pinned: true` 会让它排在首页、归档与书架的最前面，而日期、URL、订阅源里的时间都不变。
|
||||
|
||||
## 一、标题层级与段落
|
||||
|
||||
正文用 `##` 作一级节标题，`###` 作二级。**不要用 `#`**——文章标题由 frontmatter 的 `title` 渲染，正文再写 `#` 会出现两个一级标题，屏幕阅读器与搜索摘要都会困惑。
|
||||
|
||||
段落之间空一行即可。行内可以**加粗**、*斜体*、~~删除线~~、`行内代码`，也可以放[普通链接](https://astro.build)。
|
||||
|
||||
## 二、彩色强调：一页不超过三处
|
||||
|
||||
纪律来自设计基线：站点外壳是灰阶的，颜色只用来给正文某一个判断加重，一页最多三处。超过就变成花哨。
|
||||
|
||||
<span class="c-blue">第一处：一个关键结论用蓝色提出。</span> 后面照常叙述。
|
||||
|
||||
<span class="c-red">第二处：需要警示的坑用红色。</span> 比如「改完 Markdown 插件必须清 `node_modules/.astro`，否则改动静默不生效」。
|
||||
|
||||
<span class="c-green">第三处：确认可行的路径用绿色。</span> 三处之后，本节不再上色。
|
||||
|
||||
可用色相共 8 组（blue / teal / green / yellow / orange / red / pink / purple），每组有标准与 `-soft` 两档；另有 4 个灰阶层级类（`ink-muted` / `ink-warm` / `ink-cool` / `ink-faint`）用于降调，不算彩色额度。
|
||||
|
||||
## 三、字族：换字体只作用于被包裹的文字
|
||||
|
||||
正文默认是无衬线。想给某句话换气质，用类包起来就行：
|
||||
|
||||
<span class="font-kai">这一句是楷体。适合题记、书评里引的原句，或者需要慢一点读的段落。</span>
|
||||
|
||||
<span class="font-huiwen">这一句是汇文明朝体。长段落用它会明显降低阅读速度，所以只用在短句上。</span>
|
||||
|
||||
可用字族共 6 族（`font-kai` 楷、`font-song` 宋、`font-hei-sys` 黑、`font-fangsong` 仿宋、`font-huiwen` 汇文明朝、`font-kuaile` 快乐体），另有 `font-art-kuaile` 艺术字标题类。**注意体积**：整页换字族会让访问者下载一份中文字体，正文默认字体不要轻易改。
|
||||
|
||||
### 三级标题长这样
|
||||
|
||||
比二级小一档、加粗、上下留白更紧。用于把一节拆成几个小话题。
|
||||
|
||||
## 四、引用与列表
|
||||
|
||||
> 引用块用于摘录别人的话。署名可以换成斜体放在最后。
|
||||
>
|
||||
> —— 一句虚构的署名
|
||||
|
||||
无序列表：
|
||||
|
||||
- 第一项
|
||||
- 第二项，可以带 `行内代码`
|
||||
- 第三项，可以嵌套：
|
||||
- 子项一
|
||||
- 子项二
|
||||
|
||||
有序列表适合步骤：
|
||||
|
||||
1. 复制模板
|
||||
2. 改 frontmatter 的 slug 与标题
|
||||
3. 删掉不需要的段落
|
||||
|
||||
## 五、代码块
|
||||
|
||||
四行及以上的代码块会带上灰阶窗条（三个点），短代码块不加——避免小片段看着像截图。
|
||||
|
||||
```ts
|
||||
// 排序契约：置顶优先 → 时间倒序 → id 兜底
|
||||
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();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
行内提到变量时用 `posts` 这种形式即可。
|
||||
|
||||
## 六、表格
|
||||
|
||||
| 能力 | 写法 | 注意 |
|
||||
| --- | --- | --- |
|
||||
| 彩色强调 | `<span class="c-blue">` | 一页 ≤3 处 |
|
||||
| 换字族 | `<span class="font-kai">` | 整页换会拉字体体积 |
|
||||
| 图片 | `` | 体积纪律见写作指南 |
|
||||
| 视频 | frontmatter `video:` | 放 public/media，≤50MB |
|
||||
| 链接卡片 | 裸链接单独成段 | 构建期抓 OG，失败回落普通链接 |
|
||||
|
||||
## 七、图片
|
||||
|
||||
图片用相对路径引用，挂在 `content/posts/assets/<slug>/` 下，点击可放大（矢量图不糊）：
|
||||
|
||||
|
||||
|
||||
## 八、链接卡片
|
||||
|
||||
一个裸链接单独成段，构建期会抓取 OG 预览生成卡片；抓不到就退回普通链接，不会坏版：
|
||||
|
||||
https://astro.build
|
||||
|
||||
## 九、折叠长内容
|
||||
|
||||
长附录、完整日志、大段配置可以折叠，零 JS，原生 `details`：
|
||||
|
||||
<details>
|
||||
<summary>展开看一个被折叠的长例子</summary>
|
||||
|
||||
折叠区里可以放任何东西——段落、列表、代码块。
|
||||
|
||||
- 适合放「按需查看」的细节
|
||||
- 不适合放结论（读者可能永远不展开）
|
||||
|
||||
</details>
|
||||
|
||||
## 十、分隔线之后收尾
|
||||
|
||||
---
|
||||
|
||||
收尾三句就够：这篇讲了什么、读者该带走什么、下一步去哪。模板不是要你写满十节，而是**在你需要表达时，能力都在手边**。
|
||||
|
||||
下一篇开始，复制本文件，删到只剩你要说的。
|
||||
Reference in new issue
Block a user