如何手动添加一篇新文章

站点是怎么工作的

SSG 静态生成：构建时为每个 URL 生成一份完整 HTML（含正文、TOC、SEO 元数据）。搜索引擎能完整索引；浏览器直出，不用等 JS。

.
├── index.html                   ★ 构建产物 · 首页
├── <cat>/                       ★ 构建产物 · 每个分类
│   ├── index.html              （分类列表页）
│   └── <id>/index.html         （文章页 · 含 SEO meta + TOC）
├── styles/                      主题变量 / 组件样式
├── scripts/
│   └── app.js                   主题切换 / TOC 跟随 / 列表搜索 增强
├── vendor/
│   └── marked.min.js            浏览器端 Markdown 解析（备用）
├── content/                     ★ 你主要在这里写东西
│   ├── _categories.json         分类元信息
│   ├── manifest.json            自动生成 · 别手改
│   ├── search-index.json        自动生成 · 全文搜索索引
│   ├── python-basic/*.md
│   ├── python-advanced/*.md
│   ├── ops-corp/*.md
│   └── ...
├── tools/
│   ├── build-manifest.js        扫 content/ 生成 manifest + search-index
│   └── build-static.js          ★ 生成所有静态 HTML + sitemap + robots + rss
├── templates/
│   ├── article.template.md      加文章时抄这个
│   └── category.template.txt    加分类时抄这个
├── site.config.json             站点配置（域名 / 名称 / 描述）
├── package.json
├── sitemap.xml                  自动生成
├── robots.txt                   自动生成
└── rss.xml                      自动生成

1. 加一篇新文章（最常用）

三步：

复制 templates/article.template.md 到 content/<分类id>/<新文章id>.md
编辑：改 frontmatter（title / date / excerpt），写正文（Markdown）
跑 npm run build，浏览器刷新

新文章 URL 自动是 /<分类id>/<新文章id>/。

文件命名两种规则

看 _categories.json 里那个分类有没有 "sort": "filename" 字段：

模式	例子分类	文件命名
教程类（按学习顺序）	python-basic / ops-corp / docs	`NN-slug.md`（数字前缀决定显示顺序）例：`31-decorators.md`
博客类（按时间倒序）	gamedev / ai / tools / misc	`slug.md`（随意命名，靠 frontmatter `date` 排序）例：`2026-aha-moment.md`

2. Frontmatter 字段（必填）

---
title: 文章标题
date: 2026-05-09        # YYYY-MM-DD
excerpt: 一句话摘要
---

每个字段的用处：

字段	用作
`title`	`<title>` + OG title + 列表项标题 + 搜索结果标题
`date`	排序 + RSS pubDate + Schema.org datePublished
`excerpt`	`<meta description>` + OG description + 列表项摘要

3. 加一个新分类

编辑 content/_categories.json，加一项：

{ "id": "my-cat", "name": "我的新分类", "desc": "一句话说明这个分类。" }

教程类加 "sort": "filename"：

{ "id": "my-tutorial", "name": "我的教程", "desc": "...", "sort": "filename" }

建文件夹 content/my-cat/
用 article.template.md 加几篇 .md 进去
跑 npm run build

左侧栏会自动出现新分类。

4. Markdown 支持

正文用标准 Markdown（marked.js 解析）：

语法	效果
`## Heading`	二级标题（自动加 id 进 TOC）
`### Sub`	三级标题（自动加 id 进 TOC）
`粗体`	粗体
`斜体`	斜体
`[文字](url)`	超链接
反引号包代码	行内代码
三反引号代码块	多行代码块（指定语言会带类名以备语法高亮）
`> 引用`	引用块
`- 项`	无序列表
`1. 项`	有序列表
`---`	分割线
`![alt](img.png)`	图片
`\| 表格 \|`	Markdown 表格

5. 构建命令

命令	作用
`npm run build`	完整构建（manifest + search-index + 所有静态 HTML + sitemap + rss）
`npm run manifest`	只重建 manifest 与搜索索引（一般不用单独跑）
`npm run static`	只重建静态 HTML（manifest 已存在时）
`npm run serve`	起本地服务器 `python -m http.server 5500`

加 / 改 / 删 .md 后跑一次 npm run build 就行。

6. 常见坑

必须跑 npm run build：丢 .md 进去后不跑 build，列表页和文章页不会更新
frontmatter YAML：不能有 Tab，只能空格；冒号后要有空格
id 不能重复：同一文件夹下 .md 文件名唯一（文件名 = 文章 id = URL 一段）
教程类要带 NN- 前缀：否则排序不对
改 site.config.json 后必须重建：影响所有 sitemap / canonical / OG
修改后刷新：build 完保存 → 浏览器 Ctrl + R（必要时 Ctrl + Shift + R 跳缓存）

7. 内置功能

搜索

分类页顶部搜索框，匹配标题 + 摘要 + 正文（懒加载 search-index.json）。匹配高亮 + 命中正文时显示前后文片段。

分页

右上角"每页"下拉框：10 / 30 / 50。浏览器记住选择。

暗色模式

顶部右上角太阳/月亮按钮。首次跟随系统；手动切过之后固定。

TOC（文章右侧目录）

文章有 ≥ 2 个二/三级标题时自动生成。滚动正文时高亮当前段；点击跳转。

8. SEO

每页自动生成：

独立 <title> / <meta description> / <meta keywords>
canonical URL（绝对地址）
OpenGraph 标签（社交分享卡片）
Twitter Card 标签
JSON-LD 结构化数据（TechArticle + BreadcrumbList）
统一 sitemap.xml（所有 URL + lastmod）
robots.txt（含 sitemap 指向）
RSS 2.0 feed（最新 30 篇）

部署后到 Google Search Console / Bing Webmaster / Baidu 搜索资源平台提交 https://你的域名/sitemap.xml 即可。三家都免费。

遇到不会改的，把 tools/build-static.js 或 scripts/app.js 内容贴给 ChatGPT / Claude 问"我想加 XXX 怎么改"——比读文档快十倍。