如何在 DoIt 中编写文章

本文说明在本站（Hugo + DoIt 主题）中如何新增文章、如何填写 front matter，以及如何与 content/ 下的分类、系列、标签、作者等目录配合使用。

1 在 posts 中新增一篇文章

1.1 文件位置与命名

• 路径：所有博文放在 content/posts/ 下。
• 文件名：建议使用英文或拼音，避免空格（可用 - 连接），例如：
  • how-to-DoIt.md
  • An Introduction to Flow Matching and Diffusion Models.md（含空格也可，但 URL 会转义）
• 格式：Markdown（.md），文件开头必须是 YAML front matter（用 --- 包裹）。

1.2 最小可用 front matter 示例

---
title: "文章标题"
date: 2026-02-28
draft: false
---

其余字段会使用 config/_default/params.toml 中 [page] 的默认值。

2 Front Matter 字段说明与填写规范

下面按「常用 → 可选」顺序说明各字段含义、可选值及与 content/ 目录的对应关系。

2.1 标题与描述

规范建议：title 简洁明确；description 可写一两句概括，便于搜索与列表展示。

2.2 时间

规范建议：新文章写上当天的 date；若希望“最后修改”来自 Git，可不写 lastmod 并保持 enableGitInfo = true。

2.3 发布与作者

与 content 的兼容：content/authors/_index.zh-cn.md（及 _index.en.md）是“作者”分类页；具体作者信息可在 data/authors/ 中配置，供 authors 引用。

2.4 分类、系列与标签（与 content 目录的对应）

这三类都会在文章页和列表页显示，且必须与 content 下已有目录/词条对应，否则链接会 404 或显示异常。

规范建议：

• 先有目录再引用：新增分类或系列时，先在 content/categories/ 或 content/series/ 下新建目录并添加 _index.zh-cn.md（及多语言时的 _index.en.md），再在文章里写 categories / series。
• 命名一致：front matter 里的 categories、series 取值要与目录名一致（如 getting-start 对应 content/series/getting-start/）。
• 标签：tags 一般会通过 Hugo taxonomy 自动建页，若你站有 content/tags/xxx/_index.zh-cn.md，则标签名需与 xxx 对应。

示例（与当前站点一致）：

tags: ["Flow Matching", "Diffusion"]
categories: ["documentation"]
series: [getting-start]

即：该文属于分类「文档」、系列「开始使用 DoIt」，并带有两个标签。

2.5 首页与搜索可见性

规范建议：正式发布的文章通常两者都设为 false；测试文或暂不对外展示的可设为 true。

2.6 头图

规范建议：若暂无头图可留空 ""；图片建议放在 static/images/ 下，路径如 /images/xxx.webp。

2.7 目录（TOC）与代码块

未在 front matter 中写的项会使用 config/_default/params.toml 中 [page.toc] 与 [page.code] 的默认值。

示例（长文、代码多时常用）：

toc:
  enable: true
  auto: false

code:
  maxShownLines: 100
  lineNos: true
  copy: true

3 与 content 下各目录的兼容关系小结

多语言：若启用多语言，_index 会有 _index.zh-cn.md、_index.en.md 等；posts 的 front matter 不直接写语言，由文件名或 config 的 defaultContentLanguage 等决定。

4 推荐的新文章模板（复制即用）

---
title: "你的文章标题"
subtitle: ""                    # 可选
date: 2026-02-28                # 建议改成当天
# lastmod: 2026-02-28           # 可选；不写则用 Git 最后提交时间（需 enableGitInfo = true）
draft: false
# authors: [steven]             # 可选；不写则用站点默认作者
description: "一句话描述本文"

tags: ["标签1", "标签2"]
categories: ["documentation"]   # 需存在 content/categories/documentation/
series: [getting-start]         # 需存在 content/series/getting-start/

hiddenFromHomePage: false
hiddenFromSearch: false

featuredImage: ""
featuredImagePreview: ""

toc:
  enable: true
  auto: false

code:
  maxShownLines: 100
  lineNos: true
  copy: true
---

正文从第二个 --- 之后开始写，使用标准 Markdown；如需“摘要与全文分隔”，在摘要结束处插入 <!--more-->。

5 编写规范（约定）

1. 必填：title、date、draft（建议显式写 false 再发布）。
2. 分类/系列：只填写已在 content/categories/、content/series/ 下创建过的名称。
3. 标签：与站点现有标签或 content/tags/ 结构一致，避免临时造词导致大量空标签页。
4. 描述：正式文章建议写 description，便于 SEO 和列表展示。
5. 头图：可选；若用，路径统一用站点内路径（如 /images/...）。
6. lastmod：若希望由 Git 自动反映修改时间，可不写 lastmod 并保持 enableGitInfo = true。

按上述方式在 content/posts/ 下新增或修改文章，即可与 DoIt 主题及本站 content/ 目录结构兼容、正常显示在首页、分类、系列与搜索中。