blog/content/posts/writing-template.md

title, pubDate, category, tags, pinned, description

title	pubDate	category	tags	pinned	description
写作模板：这篇文章本身就是模板	2026-11-02	tech	写作 模板	true	一篇文章演示全站可用的排版能力：标题层级、彩色强调、字族、引用、代码窗、表格、图、链接卡、折叠。复制它开始写新文。

这篇不是教程，是可复制的模板。下面每一节都在真跑——你看到的效果，就是 Markdown 源码能产出的效果。写新文章时，把本文件复制一份、改个 slug、删掉不需要的段落即可。

它同时是置顶功能的活样本：frontmatter 里的 pinned: true 会让它排在首页、归档与书架的最前面，而日期、URL、订阅源里的时间都不变。

一、标题层级与段落

正文用 ## 作一级节标题，### 作二级。不要用 #——文章标题由 frontmatter 的 title 渲染，正文再写 # 会出现两个一级标题，屏幕阅读器与搜索摘要都会困惑。

段落之间空一行即可。行内可以加粗、斜体、删除线、行内代码，也可以放普通链接。

二、彩色强调：一页不超过三处

纪律来自设计基线：站点外壳是灰阶的，颜色只用来给正文某一个判断加重，一页最多三处。超过就变成花哨。

第一处：一个关键结论用蓝色提出。 后面照常叙述。

第二处：需要警示的坑用红色。 比如「改完 Markdown 插件必须清 node_modules/.astro，否则改动静默不生效」。

第三处：确认可行的路径用绿色。 三处之后，本节不再上色。

可用色相共 8 组（blue / teal / green / yellow / orange / red / pink / purple），每组有标准与 -soft 两档；另有 4 个灰阶层级类（ink-muted / ink-warm / ink-cool / ink-faint）用于降调，不算彩色额度。

三、字族：换字体只作用于被包裹的文字

正文默认是无衬线。想给某句话换气质，用类包起来就行：

这一句是楷体。适合题记、书评里引的原句，或者需要慢一点读的段落。

这一句是汇文明朝体。长段落用它会明显降低阅读速度，所以只用在短句上。

可用字族共 6 族（font-kai 楷、font-song 宋、font-hei-sys 黑、font-fangsong 仿宋、font-huiwen 汇文明朝、font-kuaile 快乐体），另有 font-art-kuaile 艺术字标题类。注意体积：整页换字族会让访问者下载一份中文字体，正文默认字体不要轻易改。

三级标题长这样

比二级小一档、加粗、上下留白更紧。用于把一节拆成几个小话题。

四、引用与列表

引用块用于摘录别人的话。署名可以换成斜体放在最后。

—— 一句虚构的署名

无序列表：

• 第一项
• 第二项，可以带 行内代码
• 第三项，可以嵌套：
  • 子项一
  • 子项二

有序列表适合步骤：

1. 复制模板
2. 改 frontmatter 的 slug 与标题
3. 删掉不需要的段落

五、代码块

四行及以上的代码块会带上灰阶窗条（三个点），短代码块不加——避免小片段看着像截图。

// 排序契约：置顶优先 → 时间倒序 → 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：

展开看一个被折叠的长例子

折叠区里可以放任何东西——段落、列表、代码块。

• 适合放「按需查看」的细节
• 不适合放结论（读者可能永远不展开）

十、分隔线之后收尾

---

收尾三句就够：这篇讲了什么、读者该带走什么、下一步去哪。模板不是要你写满十节，而是在你需要表达时，能力都在手边。

下一篇开始，复制本文件，删到只剩你要说的。