通用文章模板

没有特殊结构要求时，从这张模板开始最安全。它提供一套完整的文章 frontmatter、常见的五段式正文结构和发布前检查，适合技术说明、经验总结、方法记录和一般性分享。

用途

写一篇普通的说明文章、经验总结、工具使用心得或知识整理。
希望文章正常进入首页、侧边栏、归档、分类、标签和站内搜索。
希望正文结构清楚，但不需要教程、复盘、题解或建站记录那样的专用章节。
作为其他模板的基础：先确保 frontmatter 正确，再按内容需要替换正文结构。

放在哪里

文章必须放在 docs/posts/ 下的一级分类目录中；也可以放在该分类下的二级目录中。不要在文章目录创建 index.md。

场景	目标文件	`categories`	`permalink`	公开地址
一级分类下	`docs/posts/技术笔记/10.example-article.md`	`[技术笔记]`	`/posts/技术笔记/example-article`	`https://www.baecon.cn/posts/技术笔记/example-article`
二级目录下	`docs/posts/技术笔记/项目记录/20.vitepress-deploy-guide.md`	`[技术笔记]`	`/posts/技术笔记/项目记录/vitepress-deploy-guide`	`https://www.baecon.cn/posts/技术笔记/项目记录/vitepress-deploy-guide`

公式：

text

文件：docs/posts/<一级分类>/[<子目录>/]<slug>.md
permalink：/posts/<一级分类>/[<子目录>/]<slug>
公开地址：https://www.baecon.cn/posts/<一级分类>/[<子目录>/]<slug>

文件名前的数字前缀用于默认排序，不会自动出现在显式 permalink 中。二级目录属于 URL 路径，不是第二个分类。

什么时候使用

你不确定该用哪个模板，而内容确实是一篇普通文章。
文章以解释、总结、对比、经验或观点为主。
文章结构可以自由组织，不需要强制给出环境版本、正确性证明或回滚步骤。
你想先得到一份安全、完整、可发布的 frontmatter，再专注写正文。

什么时候不要使用

内容是可复现的操作教程：使用技术教程模板。
内容是项目结束后的系统复盘：使用项目复盘模板。
内容是个人生活经历或感受：使用生活随笔模板。
内容是一道算法题：使用算法题解模板。
内容是域名、部署、CDN、评论或博客配置变更：使用建站记录模板。
你要创建分类目录入口：使用目录页模板，不要把目录页写成文章。
不要复制本说明页自身的 frontmatter。要复制的是下面代码块里的完整文章文件。

完整可复制文件

复制下面围栏中的全部内容，粘贴到 docs/posts/... 下新建的 .md 文件，再逐项替换占位值。

markdown

---
title: 通用文章标题
description: 说明这篇文章要解决的问题、适合哪些读者，以及读完后能获得什么结论；同时交代文章边界、验证方法和注意事项，并控制在 50 至 150 个中文字符之间。
permalink: /posts/技术笔记/example-article
categories:
  - 技术笔记
tags:
  - 示例标签
  - 写作模板
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

# 通用文章标题

先用一两句话说明读者为什么会打开这篇文章，以及文章大致会讲什么。这一段不是 frontmatter 字段，可以删除或改写。

## 背景

说明问题出现的场景、已有做法和困难。让没有上下文的读者也能理解：为什么现在值得讨论这个问题。

例如：

> 在把博客文章从手工列表改为自动目录后，新文章能自动进入侧边栏，但旧文章的链接开始出现不一致。

## 目标

写清这篇文章要达成什么，以及不打算覆盖什么。

- 目标一：让读者理解核心问题。
- 目标二：给出可执行的做法或判断标准。
- 边界：本文不讨论与本主题无关的部署细节。

## 正文

按逻辑拆分小节。每一节只解决一个问题；标题要具体，不要连续使用很多没有信息量的「其他」「补充」。

### 核心概念

解释必要的术语、前提和约束。第一次出现的缩写要展开说明。

### 具体做法

给出步骤、示例或对比。涉及代码时标注语言，涉及图片时写清 alt。

```text
这里可以放命令、配置、输出或简短代码示例。
```

![正文图片说明：展示配置完成后的页面效果](/images/posts/example-article/image-01.webp)

> 图片提示：必须替换成真实存在的图片，alt 不能为空。没有图片时删除整行，不要留下不存在的路径。

## 验证与注意事项

说明如何判断文章中的做法有效，以及哪些情况容易出错。

| 检查项 | 预期结果 |
|---|---|
| 页面能正常打开 | 没有 404 或构建报错 |
| 相关链接可点击 | 不跳转到错误页面 |
| 代码或步骤可复现 | 结果与文章描述一致 |

注意事项：

- 不要把密钥、Token、密码或私密链接写进正文。
- 不要复制其他文章中的日期和永久链接而不修改。
- 如果内容已经过时，应更新正文或明确标注适用版本。

## 总结

用几句话回收文章目标，给出最重要的结论、适用边界或下一步行动。不要把正文原样重复一遍。

复制后必须修改或确认

值	位置	应该怎么改	为什么必须确认
`title` 和正文 H1	frontmatter 与 `# 通用文章标题`	两处改成完全相同的真实标题	页面只能有一个 H1；标题不一致会影响目录、搜索和阅读体验。
`description`	frontmatter	换成真实摘要，建议 50–150 个中文字符	省略时 SEO 会回退到站点描述，首页卡片摘要也不可控。
`date`	frontmatter	通常不要手填；文件首次 Git commit 后启动/构建会自动写入	自动写入后不要为了「更新」而改它；更新信息用 `updated`。
`permalink`	frontmatter	改成全站唯一的 `/posts/一级分类/.../slug`	决定公开 URL；不要依赖自动生成，必须显式写稳定地址。
`categories`	frontmatter	改成文章所在的一级分类，只写一个	二级目录不是分类；显式填写比目录推断更稳定。
`tags`	frontmatter	换成 2–5 个与主题直接相关的标签	标签用于聚合和搜索；示例标签不能发布。
`coverImg`	frontmatter	通常删除以使用正文图片/随机背景；只在需要固定卡片或分享图时写真实路径	显式写后会固定，不再随机；路径必须存在。
`article`	frontmatter	保持 `true`	明确声明这是文章，确保首页和归档等能力正常。
`sidebar`	frontmatter	保持 `true`	正常文章需要左侧文章导航。
`pagefind-indexed`	frontmatter	保持 `true`	让文章进入站内搜索；它不是隐私开关。
`comment`	frontmatter	保持 `true`	普通文章显示评论区；不希望公开讨论时才改为 `false`。
正文图片	body	换成真实图片路径，保留有意义的 alt；没有图就删除图片行	图片路径约定为 `/images/posts/<slug>/<file>.webp`，alt 必填。

可选字段

这些字段没有写进基础模板，只在确有需要时添加。

字段	什么时候用	推荐值	注意
`top`	想让文章进入首页「精选文章」	`1`	它是真值筛选标记，不是排名；数字大小不负责排序。首页精选还有数量上限。
`sticky`	想让文章在按置顶排序的列表中靠前	`1` 或较小的数字	必须是数字，不能用 `true`；数字越小越靠前。
`titleTag`	想在标题旁显示「原创」「教程」「复盘」「题解」「记录」等短标识	2–4 个汉字	它只是视觉标签，不替代分类或 tags。
`sidebarSort`	文件名前缀不足以表达侧边栏顺序	`10`、`20`、`30`	数字越小越靠前；优先用文件名前缀，避免两套排序规则。
`inHomePost`	想从首页主文章列表隐藏一篇特殊文章	省略或 `true`；特殊时 `false`	会影响首页及分类/标签的 HomePost 列表，不会让文章变成私有页面。
`updated`	确实需要用一个新的修改日期覆盖 SEO 信息	`YYYY-MM-DD HH:mm:ss`	通常省略；它不能代替 `date`。
`author`	多人署名且站点级作者不适用	不写；如确需覆盖，用对象 `{ name, link }`	本站使用站点级作者，普通文章不要覆盖。

文章 frontmatter 字段总表

字段	类型	省略时默认	推荐值	级别	完整说明
`title`	`string`	无可用默认；不要依赖自动推导	与正文唯一 H1 完全一致	必填	页面标题，也是首页卡片、侧边栏、搜索结果和浏览器标题的来源。复制模板后必须改成真实标题，并保证正文只有一个 H1。
`description`	`string`	SEO 会回退到站点描述；首页摘要质量不可控	50–150 个中文字符，说明问题、内容与读者收益	推荐	供 SEO 描述、首页卡片摘要和分享信息使用。应写成完整的一句话或两句话，不要堆关键词，也不要直接复制标题。
`desc`	`string`	未设置	省略	可选（旧字段）	旧目录页的兼容显示字段，主要给 catalogue 页面使用；它不是 SEO 主字段，也不参与首页摘要。新文章不要写；目录页如保留 `desc`，需与 `description` 同值。
`date`	`string`	文件首次 Git commit 的作者时间；已有值保留	通常省略，不手填；需要人工指定发布时间时才覆盖	自动维护；通常不手填	文章的创建/发布时间，用于展示、首页排序、归档和 SEO 的 `datePublished`。新文章不需要写；首次 commit 后启动/构建会写入并保持稳定。
`updated`	`string`	未显式设置；SEO 修改时间由构建或最后更新时间兜底	正常省略；确实需要覆盖时再用同一日期格式	可选	只用于覆盖 SEO 的 `dateModified`，不是文章发布时间，也不能代替 `date`。除非有明确的更新日期要展示给搜索引擎，否则不要填。
`permalink`	`string`	自动插件通常跳过已有 frontmatter，不能依赖自动生成	全站唯一：`/posts/<一级分类>/[<子目录>/]<slug>`	必填	决定文章的公开 URL。本项目要求显式填写，不能包含 `.md`，不能以 `docs/` 开头，也不能与其他页面重复。
`categories`	`string[]`	自动插件通常跳过；缺省时没有可靠分类	显式写一级分类，如 `[技术笔记]`	推荐	分类归档和分类卡片使用。只写一级分类；二级目录属于路径，不是第二个分类。一篇文章通常只写一个一级分类。
`tags`	`string[]`	`[]`	2–5 个具体标签，如 `[VitePress, 部署]`	推荐	标签用于聚合主题和搜索。标签应短而具体，避免把整句话、分类名或大量近义词都写成标签。
`coverImg`	`string` 或 `string[]`	首页卡片：正文图片随机 → `/home/bg*.webp` 随机；SEO 分享图回退站点默认	需要固定封面/分享图时才写真实路径；否则省略	可选（按需）	首页卡片优先使用；文章 Banner、OG 和分享图也会读取。显式写后不再随机；路径必须真实存在；不写时分享图不会自动取正文图。
`article`	`boolean`	在 `/posts/` 下省略时按 `true` 处理	`true`	推荐	明确声明这是文章，让首页、归档、分类和标签等文章能力正常工作。教程、复盘、随笔、题解和建站记录都应显式写 `true`。
`sidebar`	`boolean`	VitePress 默认为 `true`	`true`	推荐	控制文章页是否显示左侧文章导航。本站文章应保持 `true`；只有特殊全宽页面才考虑关闭。
`sidebarSort`	`number`	使用文件名数字前缀；没有前缀时按 `9999`	省略；确需覆盖时用 `10`、`20` 这类数字	可选	覆盖该文章在侧边栏中的排序，数字越小越靠前。优先用文件名前缀排序；同时使用两种方式会增加理解和维护成本。
`pagefind-indexed`	`boolean`	`true`	`true`	推荐	控制 Pagefind 是否索引此页。文章应保持 `true`；设为 `false` 只是不进入站内搜索，并不会把页面变成私有页面。
`comment`	`boolean`	未写 `false` 时按开启处理	`true`	推荐	控制文章评论区。普通文章保持 `true`；目录页、纯功能页或含敏感信息的页面应关闭或不要发布。
`top`	`boolean 或 number`	未设置，即不进入精选	省略；只有需要首页精选时写 `1`	可选	首页「精选文章」的真值筛选标记，不是排名：写 `1` 表示入选，数字大小本身不会排序。是否显示还受首页精选数量上限影响。
`sticky`	`number`	未设置，即不置顶	省略；确需置顶时用较小数字，如 `1`	可选	置顶排序字段，数字越小越靠前。它和 `top` 分工不同：`top` 负责进入精选卡片，`sticky` 负责置顶排序。不要用 `true` 代替数字。
`inHomePost`	`boolean`	`true`	省略或显式 `true`；只有特殊文章才写 `false`	可选	设为 `false` 时会从首页、分类页和标签页等 HomePost 列表隐藏；文章的 URL、侧边栏、归档、精选和搜索等不会自动变成私有。不要把它当作隐私开关。
`inCatalogue`	`boolean`	`true`	通常省略；不想让文章出现在目录页时写 `false`	高级	目录插件扫描开关；不影响侧栏、Pagefind、首页、归档或 RSS。
`titleTag`	`string`	无标签	省略；需要短标识时用 `原创`、`教程`、`复盘`、`题解`、`记录`	可选	标题旁的小标签，只用于视觉提示，不替代分类或标签。保持 2–4 个汉字最清晰，不要塞入长句。
`author`	`object`	使用站点级作者 `Baecon`	省略，不在单篇文章覆盖	可选（不建议）	若覆盖需用 `{ name: string, link?: string }` 对象；普通文章不要填写。

高级 VitePress 字段

以下字段属于 VitePress 或主题的页面布局能力，不是文章写作字段。初学者不要为了让页面看起来不同而逐篇修改；需要调整时应优先修改全站配置。

字段	类型	省略时默认	推荐值	级别	完整说明
`layout`	`string 或 false`	使用 VitePress 标准文章布局	省略	高级	切换页面布局。文章模板不需要设置；目录页才固定使用 `layout: page`。初学者不要为了外观而改它。
`outline`	`false`、数字、`[number, number]` 或 `"deep"`	由 VitePress 与主题的默认大纲配置决定	省略	高级	控制右侧标题大纲。普通文章沿用站点统一配置即可，除非全站规范明确要求，否则不要逐篇覆盖。
`aside`	`boolean` 或 `"left"`	默认跟随 VitePress 文章布局	省略	高级	控制右侧辅助栏。与全站布局相关，不应由每篇文章随意切换。
`lastUpdated`	`boolean`	跟随站点 `lastUpdated: true`	省略	高级	控制页面是否显示最后更新时间。本站已统一开启，不需要在每篇文章重复设置。
`editLink`	`boolean`	跟随站点主题配置	省略	高级	控制是否显示编辑链接。它属于站点能力，不是文章内容字段。
`pageClass`	`string`	空	省略	高级	给页面根元素追加 CSS 类，只在有配套样式时使用。随意填写不会产生视觉效果。
`layoutClass`	`string`	空	省略	高级	当前项目会把它作为布局组件 class 读取，但只有配套 CSS 才有意义；普通写作不需要填写。
`head`	`array`	`[]`	省略	高级	为单个页面追加 `<head>` 标签。站点已统一生成 SEO 和分享标签，重复配置容易冲突。
`titleTemplate`	`string 或 false`	使用站点标题模板	省略	高级	覆盖浏览器标题拼接方式。除非页面有特殊 SEO 要求，否则不要覆盖全站一致性。
`autoTitle`	`boolean`	doc 布局默认允许自动注入 H1	省略；正文已手写 H1	高级	设为 `false` 可禁止自动 H1 注入。
`articleUpdate`	`boolean 或 object`	跟随站点配置，默认启用	省略	高级	设为 `false` 隐藏文章页最近更新模块。
`articleBanner`	`boolean 或 object`	跟随站点配置；本站开启	省略	高级	设为 `false` 关闭单文章 Banner；通常仅无侧栏 doc 文章生效。
`coverBgColor`	`string`	跟随站点 defaultCoverBgColor，本站为空	省略	高级	单文章 Banner 背景色覆盖；无 Banner 时不可见。
`prev`	`boolean`	`true`（有上一页时）	省略	高级	设为 `false` 隐藏上一页链接。
`next`	`boolean`	`true`（有下一页时）	省略	高级	设为 `false` 隐藏下一页链接。

catalogue、path、pageTitle 是目录页专用字段，文章模板不要填写。若需要创建分类或子目录入口，请使用目录页模板。

章节	写什么	示例
`## 背景`	问题出现的场景、已有做法和困难	说明为什么旧流程不够用。
`## 目标`	文章要达成的结果、读者收益和边界	用 2–3 条列表写清覆盖范围。
`## 正文`	核心解释、步骤、示例、对比或实现	拆成若干具体的 H3 小节，而不是一段到底。
`## 验证与注意事项`	如何验证、常见错误、限制和安全提醒	用表格列出检查项和预期结果。
`## 总结`	回收目标，给出结论、边界和下一步	只写关键结论，不重复全文。