中文博客写作示例：一篇覆盖常用格式的模板

这篇文章不是为了讲某个具体主题，而是像 LaTeX 模板里的“语法示例”一样，集中展示这个博客系统里常见的写作格式。你可以保留本文作为参考，也可以复制其中任意片段到自己的文章里。

Table of contents

Frontmatter：文章元信息

每篇博客开头的 --- 区域叫 frontmatter，用来描述文章标题、摘要、日期、标签等信息。当前项目的博客内容 schema 支持这些字段：

标题层级

正文从二级标题开始通常最稳妥，因为文章标题已经是一级标题。

三级标题

适合分组说明一个小主题。

四级标题

适合放在较长章节内部，但不要滥用。标题太碎时，读者会像在翻抽屉，很忙，但不一定更清楚。

段落与强调

普通段落直接书写即可。段落之间空一行，Markdown 会自动把它们渲染为独立段落。

你可以使用 加粗 表示重点，使用 斜体 表示术语、语气或轻微强调，也可以使用 inline code 标记变量名、命令、文件路径或字段名。

如果要写链接，格式是：Astro 官方文档。

列表

无序列表适合列举没有强顺序的内容：

• 文章想解决什么问题
• 读者需要提前知道什么
• 结论或建议是什么

有序列表适合表达步骤：

1. 先写清楚目标。
2. 再补充背景和限制。
3. 最后给出可执行的做法。

任务清单适合记录进度：

• 写 frontmatter
• 增加目录占位
• 展示常见 Markdown
• 写完后运行构建检查

引用

引用块适合摘录、提示或强调一句判断。

好的技术博客不只是“把事情说完”，还要让读者知道下一步该怎么做。

也可以写多段引用：

第一段引用。

第二段引用。中间保留一个空引用行即可。

图片与图注

普通 Markdown 图片写法如下：

如果需要图注，可以使用 HTML 的 <figure>：

表格

表格适合做对比、参数说明和清单：

代码块

代码块建议写语言名，这样可以启用语法高亮。

type PostMeta = {
  title: string;
  description: string;
  tags: string[];
};

export function formatTitle(meta: PostMeta) {
  return `${meta.title} | ${meta.tags.join(", ")}`;
}hello.ts

也可以写终端命令：

pnpm install
pnpm dev
pnpm buildterminal

当前主题支持代码块 meta 里的 file=...，会在代码块顶部显示文件名。

如果你需要突出某几行，可以使用项目里已有文章使用过的 Shiki 注释：

const title = "中文博客写作示例";
const draft = false; 

console.log({ title, draft });highlight-demo.js

折叠内容

原生 HTML 的 <details> 很适合放补充材料：

分隔线

用三个短横线可以插入分隔线：

分隔线适合在两个主题之间制造明确停顿，但不要每隔几段就放一次。

MDX 组件

这个项目在文章详情页里注册了 GalleryEmbed 组件，所以 .mdx 文章可以直接嵌入画廊：

如果你只想写纯 Markdown，不需要组件，可以把文件扩展名改成 .md。如果要写 JSX/组件，就使用 .mdx。

脚注

脚注适合放不影响主线阅读的补充信息。这里是一个带脚注的句子。¹

常见文章骨架

一篇实用型文章可以按这个结构组织：

1. 问题：读者为什么要关心这件事？
2. 背景：需要哪些上下文？
3. 方法：具体怎么做？
4. 示例：给出可以运行或可以照着改的代码。
5. 取舍：这个方案什么时候不适合？
6. 总结：用三五句话收束，不要重复全文。

结语

你可以把这篇文章当作博客写作的速查模板：先复制 frontmatter，改掉标题、摘要、日期和标签；正文则按需要挑选标题、表格、代码块、图片、引用或 MDX 组件。