# 博客与文章

> 开一个博客栏目：目录约定、文章的 front matter、封面图、按日期排序的列表页与 RSS。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

博客文章与文档页的正文写法相同，区别在外壳：文章带日期、作者、标签与封面图，列表按日期倒序排列，栏目带 RSS。本页覆盖博客栏目的建立、文章 front matter、封面图、列表分页与 Feed。

## 博客目录结构 {#layout}
博客是 `content/` 下的一个栏目，`type: blog` 使它使用博客外壳。子目录按发布方与受众划分，文章平铺其中。无需建立年份目录，列表会按文章的 `date` 排序：

```filetree {title="本站的 content/blog/"}
- content/
  - blog/
    - _index.md                      # type: blog + cascade
    - _index.zh.md
    - oink/                          # 工程实践与公告
      - _index.zh.md                 # cascade: images: [/images/oink.webp]
      - oink-announcement.md
      - oink-announcement.zh.md
    - release/                       # 带版本号的发布注记
      - _index.zh.md                 # cascade: images: [/images/releasenote.webp]
      - 0.4.0.md
      - 0.4.0.zh.md
```

栏目根把类型下推给整棵子树，并设定该栏目共用的行为：

```yaml {title="content/blog/_index.zh.md"}
---
title: 博客
description: OINK 工程实践与发布注记
type: blog
icon: fa-solid fa-blog
sidebar_root_for: self      # 博客有自己的侧栏树
cascade:
  type: blog
  feedback: false           # 文章不问「这页有帮助吗」
  comments: true            # 但开评论
---
```

`params.ui.blog_section`（默认 `blog`）指明博客根的位置。目录另起名字时改这个参数，或按上面的写法用 `sidebar_root_for: self`。

侧栏里博客栏目默认展开，条目按日期倒序；给某篇文章写上 `weight` 会把它固定在最前。

## 一篇文章的 front matter {#front-matter}

```yaml {title="content/blog/release/0.4.0.zh.md"}
---
title: Oink 0.4.0 — 面向完整发布流程的场景组件体系
linkTitle: Oink v0.4.0        # 侧栏与翻页器里的短名
date: 2026-08-14              # 发布日期，决定列表顺序
lastmod: 2026-08-14
description: >-
  Oink 0.4.0 交付连续阅读与发布界面、可复用 Landing 页面、
  带稳定引用的 Book 出版能力，以及键盘优先的站点外壳。
author: OINK 维护者
categories: [发布]
tags: [Oink, Release]
---
```

与文档页不同的几点：

- `date` 必填。它决定文章在列表里的位置与 RSS 时间。写在未来的日期默认不构建，`hugo server -F` 可以预览。
- `description` 渲染成正文上方的导语，不只是搜索摘要，因此写成给读者阅读的一句话。
- `author` 支持行内 Markdown，可以写成 `[Vonng](https://vonng.com)`。需要多位作者、头像或作者主页时，改用下面的 `authors` taxonomy；两者互不干扰，没写 `authors` 的文章照旧渲染 `author`。
- 日期显示格式由 `params.time_format_blog` 决定，可以按语言分别设置（本站英文是 `Monday, January 02, 2006`，中文是 `2006年1月2日`）。

双语文章成对存放，两种语言的 `date`、`author`、`weight`、`aliases` 保持一致；标题、描述、标签要翻译，提交 ID、版本号、命令和 URL 不翻译。

## 封面图 {#featured-image}

列表页与标签页的每一行左侧有一张缩略图，按以下顺序解析，第一个命中的生效：

1. 文章 front matter 的 `images`，取第一项；
2. 页面包里文件名匹配 `featured` 或 `feature` 的图片，其次是 `cover` 或 `thumbnail`（会被裁切成缩略图，图片资源自己的 `byline` 会作为图注）；
3. 从祖先栏目 `cascade` 继承来的 `images`，就近生效。

栏目级默认封面用 Hugo 原生的 `cascade` 覆盖整棵子树，本站两个子栏目各设一张：

```yaml {title="content/blog/release/_index.zh.md"}
cascade:
  images: [/images/releasenote.webp]
```

要取消某篇文章继承来的封面，在它的 front matter 写 `images: []`；整个子栏目取消继承，就写进那一层的 `cascade`。这不会抑制页面包自身提供的图片。只想关闭文章里的题图时，用 `featured_image: none`；列表缩略图与分享卡片仍各自生效。站点级的 `params.images` 只做分享卡片，不会渲染成列表缩略图。

### 渲染到文章正文里 {#featured-image-article}

默认情况下，解析出来的图片显示在列表行与社交卡片里。设置 `params.ui.featured_image`，即可把同一张图显示在文章里：

| 模式 | 文章里显示什么 |
| --- | --- |
| `none` | 文章不显示题图，主题默认值 |
| `banner` | 标题上方一张固定 16:9 的图，连着读一串文章时节奏统一 |
| `wash` | 图片淡化后铺在文章头部背后，在正文开始前渐隐 |
| `hero` | 占满页面宽度的沉浸式图片头部 |

```yaml {title="hugo.yml"}
params:
  ui:
    featured_image: banner
```

页面键是 `featured_image`，所以某个子栏目的 `cascade` 可以只为那棵树打开它，单篇文章也可以退出。没有图片的文章在任何模式下都不显示题图，因此只有部分文章配图的栏目也可以整体开启。这些模式无需额外脚本。

```yaml {title="content/blog/release/_index.md"}
cascade:
  featured_image: wash
```

## 列表页与分页 {#list}

栏目 `_index.md` 的正文之后，主题自动接上文章列表：按日期倒序平铺，不按年份分组；每条显示标题、日期、所属子栏目、标签、缩略图与正文前 250 字的摘要。

列表与卡片默认每页 12 篇，用主题的 `blog_index_size` 在 `hugo.yml` 里调整：

```yaml {title="hugo.yml"}
params:
  ui:
    blog_index_size: 20
```

博客栏目 front matter 中的同名键可以覆盖站点值。主题会把这个大小显式传给 Hugo 分页器，因此 `pagination.pagerSize` 不控制这里的列表。

### 卡片形态 {#list-cards}

`params.ui.blog_index: cards` 把同一份列表渲染成内容卡片网格而不是行列表：文章题图的 16:9 裁切在上，标题、日期与子栏目行居中，下面三行摘要。

```yaml {title="hugo.yml"}
params:
  ui:
    blog_index: cards
    blog_index_columns: 3
```

列表与卡片共用日期排序、分页与 `manual_link` 的规则。列数只在 xl 断点以上生效；md 到 xl 之间为两列，md 以下一列。博客根目录的 front matter `blog_index` 或它的 `cascade` 可以按栏目设置。分类项页与分类法首页保持行列表。

单独使用 `blog_index: table` 且 `blog_index_toggle: false` 时，表格列出整个栏目，不分页。设置 `blog_index_toggle: true`，读者即可在列表、卡片、表格之间切换：

```yaml {title="content/blog/_index.zh.md"}
blog_index: cards
blog_index_toggle: true
```

开启切换时，三种形态显示同一页文章，都使用 `blog_index_size`。只有 `blog_index_toggle: false` 的独立表格才显示整个栏目；隐藏形态不会加载图片。

卡片题图只要资源可处理就走 Hugo 的 `.Fill`，一屏卡片不会为此下载一堆原图。

## RSS {#rss}

哪些页面产出 Feed 由 `outputs` 决定。给 `section` 加上 `RSS`，每个栏目就有自己的 Feed：

```yaml {title="hugo.yml"}
outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]
```

`outputs` 一旦写出就整体替换 Hugo 的默认值，`RSS` 必须显式写回。漏写等于关闭该类页面的 Feed，构建不会报错。

本站因此有 `/zh/blog/index.xml`（整个博客）与 `/zh/blog/release/index.xml`（只有发布注记）。栏目 Feed 递归包含所有子栏目的文章，订阅 `/zh/blog/` 即可收到全部。单篇文章没有自己的 `.xml`。

每种语言有各自的 Feed，地址是该语言路由加 `index.xml`。条数上限由 Hugo 的 `services.rss.limit` 控制。在博客根与它的一级子栏目页上，标题行右侧操作按钮的首位是 RSS 链接，读者不必手拼地址。

全站不需要 Feed 时用 `disableKinds` 关闭这一类输出，比逐个页面类型删除 `RSS` 更彻底：

```yaml {title="hugo.yml"}
disableKinds: [RSS]
```

组件在 Feed 里退化成静态形态：折叠块展开、交互控件去掉。四态输出的规则对博客与文档一致。

## 分类与标签 {#taxonomy}

`tags` 与 `categories` 是 Hugo 的分类体系，主题把它们渲染成文章头部的 chip、右栏的标签云和顶栏的筛选菜单。启用、双语标签与按内容类型开关见[分类体系](/zh/docs/customize/taxonomy/)。

## 发布注记 {#release-notes}

带版本号的发布公告写成普通文章，惯例放在 `blog/release/` 下，`linkTitle` 带版本号（`Oink v0.4.0`）。需要发布卡片、资产表与校验和的下载页见[发布与下载页](/zh/docs/write/releases/)。

## 文章里用组件 {#components}

提示块、标签页、代码块、图片、表格的用法与文档页相同，语法见[组件总览](/zh/docs/components/)。文章正文的标题同样写显式英文 `{#id}`。

文章末尾的反馈 / 最后修改 / 翻页器 / 评论四块与文档页一致，见[编写页面](/zh/docs/write/pages/#page-end)。博客通常关闭反馈、保留评论。

## 作者与署名 {#authors}

声明这个 taxonomy 就是全部开关，主题不为此增加任何参数：

```yaml {title="hugo.yml"}
taxonomies:
  category: categories
  tag: tags
  author: authors
```

文章按顺序写出作者：

```yaml
authors: [vonng, ada-example]
```

文章头部按这个顺序显示头像与带链接的名字，列表行显示名字；博客 Feed 除了站点级的 `managingEditor`，还会包含文章的每位作者。

作者主页就是分类项页，无需另建 `data/authors` 文件：

```markdown {title="content/authors/vonng/_index.md"}
---
title: Vonng
description: OINK 与 Pigsty 的维护者。
images: [portrait.webp]
---

正文是长介绍，渲染在主页上名字下方。
```

显示名取的是 term 页的链接标题——写了 `linkTitle` 就用它，否则用 `title`——所以主页可以挂全名、署名处用短昵称。`description` 是一句话介绍，正文是长介绍，头像则是题图解析器为这一页选中的那张——`images:` 与页面包里的肖像文件，走的是文章题图那套同样的规则。双语主页就是旁边一个 `_index.zh.md`。文章写了、但没人给它建主页的名字照样出署名：链接标题、一个首字母，以及指向归档页的链接。

0.4 的 `author:` 字符串在没有 `authors` 的地方原样保留，两种写法互不告警。

## 系列 {#series}

系列是一条穿过若干篇各自独立成文的文章的阅读路径。编号、交叉引用与聚合输出属于[书籍](/zh/docs/write/book/)，这里是更轻的那个东西。声明 taxonomy 同样就是全部开关：

```yaml {title="hugo.yml"}
taxonomies:
  series: series
```

文章写出系列名，也可以给自己定个位置：

```yaml
series: [shell-internals]
series_weight: 20
```

它的正文上方就会出现一条横幅，写明系列名、自己是第几篇、下一篇是哪篇，以及折在 `<details>` 里的完整列表——不用 JavaScript，也不增加打包成员。term 页 `content/series/<name>/_index.md` 是系列的引言，旁边放一个 `_index.zh.md` 就成双语。

写了 `series_weight` 的文章按该值升序排在前，其余按日期从旧到新排列，同序时按内容路径排序。系列横幅与分类项页使用相同的阅读顺序；实现规则见[作者与系列](/zh/docs/design/shell/#authors-and-series)。

一篇文章属于多个系列时只显示一条横幅，取它写在最前面的那个系列。只有一篇的系列不显示横幅。

`authors` 与 `series` 都不出现在文章的通用 taxonomy 标签行里，因为它们各自有专门的呈现面。想把某一个放回去，就在 `params.taxonomy.page_header` 里写上它的名字。

## 分享 {#share}

`params.ui.share` 在页尾最前面放一条分享栏。它默认为空，所以在站点写出目标之前什么都不渲染；写出来的顺序就是渲染顺序：

```yaml {title="hugo.yml"}
params:
  ui:
    share: [x, bluesky, mastodon, reddit, hackernews, email, copy]
```

可选的目标有十六个：`x`、`bluesky`、`mastodon`、`facebook`、`linkedin`、`reddit`、`hackernews`、`telegram`、`whatsapp`、`line`、`pinterest`、`weibo`、`chatgpt`、`claude`、`email`、`copy`。未知的名字告警并丢弃。Discord 是故意没有的：它根本没有公开的 share-intent URL，与其让主题去猜一个私有 scheme，不如用 `copy` 顶上。

页面键是 `share`，所以 `cascade` 可以把这条栏限定在一棵树里，页面自己的列表会整体替换继承来的那份，`share: false` 则让单页退出：

```yaml {title="content/blog/_index.md"}
cascade:
  share: [x, bluesky, email, copy]
```

只有普通页面渲染分享栏——列表页、term 页与首页没有「唯一被分享的那个东西」——打印、Markdown 与 RSS 一概不带。

分享栏由携带页面永久链接与标题的链接，以及一个本地复制按钮组成。它不加载第三方脚本或样式表，只有读者点击链接时才会访问对应目标。实现规则见[分享契约](/zh/docs/design/shell/#share)。

`chatgpt` 与 `claude` 是把同一个构建期 permalink 交给助手，附一句「请读这一页」。它们不是页面操作菜单里的「在 ChatGPT 中打开」/「在 Claude 中打开」——那两条由运行时在激活时改写成浏览器里的实时 URL，因此留在 `page_context_menu.assistant_links` 后面。

复制按钮就是内置的 `copy_link` 动作，也就是说不管有没有配分享栏，命令面板在每个站点的每一页上都带着它。

## 验证 {#verify}

```bash
hugo --printPathWarnings --panicOnWarning
```

必须 `Total in …`，没有 ERROR / WARN。随后确认：

1. 文章在 `/zh/blog/` 中按正确的日期顺序排列，日期显示为中文格式；
2. `public/zh/blog/index.xml` 存在，里面有这篇文章，链接是完整的绝对地址；
3. 缩略图出现在列表里（缺失说明三条封面来源都没命中）；
4. 标签 chip 能点进对应的标签页。

## 相关 {#related}

- [编写页面](/zh/docs/write/pages/) — 正文怎么写
- [页面参数](/zh/docs/write/frontmatter/) — `author`、`images` 等键的完整定义
- [组织内容](/zh/docs/write/organize/) — 目录与侧栏
- [分类体系](/zh/docs/customize/taxonomy/) — 标签与分类
- [发布与下载页](/zh/docs/write/releases/) — 版本卡片与资产表

---

反链：

- [配置总览](/zh/docs/customize/config/)
- [仓库与页面信息](/zh/docs/customize/repository/)
- [分类体系](/zh/docs/customize/taxonomy/)
- [创作内容](/zh/docs/write/)
- [页面参数](/zh/docs/write/frontmatter/)
- [发布与下载页](/zh/docs/write/releases/)