之前写文章，通常是打开本地编辑器，找到 content/posts，新建一个 Markdown 文件，再手动检查 front matter、图片路径和构建结果。这个流程没有什么问题，只是每次想在别的电脑上改两句话，都要先找到仓库，再把环境准备好。

Pages CMS 解决的不是“怎么写 Markdown”这个问题，而是把这件事搬到了一个可以直接登录使用的网页里。文章仍然保存到 GitHub，Hugo 仍然负责构建，Cloudflare Pages 仍然负责发布，只是中间多了一个更适合写作的入口。

这篇文章把整个流程记下来：怎么连接仓库，怎么写第一篇文章，什么时候要切到 Source mode，以及文章保存以后，AI 摘要是怎么自动生成的。

先看一遍发布链路

这个项目没有把 CMS 当成一个独立的数据库。Pages CMS 改的还是仓库里的 Markdown 文件，保存后直接提交到 main 分支。

所以，一次正常发布大致会经过这些步骤：

1. 在 Pages CMS 中编辑或新建文章。
2. CMS 把修改提交到 main。
3. GitHub Actions 运行 Deploy to Cloudflare Pages。
4. 对没有摘要的文章生成 ai_summary。
5. 使用 Hugo Extended 构建站点并检查产物。
6. 将站点部署到 Cloudflare Pages。

Pages CMS 不需要再点击一个单独的“部署”按钮。文章提交成功后，后面的事情交给 Actions 就可以了。

连接 Pages CMS

第一步：登录

打开 Pages CMS，使用 GitHub 登录。第一次进入时，需要授权 Pages CMS 访问 GitHub 仓库，按页面提示完成即可。

登录之后，选择博客对应的仓库：

kemiao-moretti/meowloge

进入仓库后，确认当前查看的是 main 分支。这个项目采用直接提交 main 的方式，没有另外维护用于写作的 edit 分支。

第二步：确认内容集合

仓库根目录的 .pages.yml 是 Pages CMS 的配置文件。当前项目只开放两个内容集合：

• Posts / 文章：对应 content/posts；
• Changelog / 更新日志：对应 content/changelog。

第一次连接后，先确认这两个集合能正常显示。如果看到了 _index.md，不要把它当成普通文章编辑。它是 Hugo section 的索引文件，负责文章列表页的标题和描述。

第三步：配置自动发布所需的变量

如果只是编辑已经有 ai_summary 的文章，CMS 本身不需要 AI Key。但新文章发布时，Actions 可能需要调用摘要接口，所以 GitHub 仓库里要提前配置好变量。

进入 GitHub 仓库的：

Settings → Secrets and variables → Actions

在 Secrets 中配置：

AI_SUMMARY_API 也可以作为 Secret 配置，用来覆盖默认的 OpenAI 兼容接口地址。

在 Variables 中可以配置：

密钥只放在 GitHub Secrets 或本地 .env，不要写进 .pages.yml、hugo.yaml、文章 front matter 或正文代码块里。

在 Pages CMS 里写第一篇文章

进入 Posts / 文章 集合，点击新建文章。这里的字段基本对应文章 front matter。

这些字段怎么填

• title：文章标题。
• slug：文章地址使用的小写英文标识，只允许小写字母、数字和连字符，例如 pages-cms-writing-guide。
• date：发布日期和时间，站点时区是 Asia/Shanghai。
• description：文章列表、搜索和分享时使用的描述。
• cover：可以填写 /img/... 的本地图片，也可以填写外部 HTTPS 图片地址。
• categories、tags、series：按需要填写数组。
• toc：文章较长、需要目录时打开。
• comment：是否开启评论。
• locate：文章位置说明，不需要时可以留空。
• recommend：只有确实要推荐文章时才打开。

新文章的文件名由 slug 生成：

content/posts/<slug>.md

这个博客的文章链接由 Hugo 配置为 /p/:slug，所以 slug 不是一个随手填写的内部字段。文章发布以后，尽量不要再改它，否则公开 URL 也会跟着变化。

普通内容用 Editor mode

标题、段落、列表、普通链接和普通图片，都可以直接使用 Pages CMS 的 Editor mode。这个模式适合日常写作，写完之后看起来和普通 Markdown 编辑器差不多。

例如下面这段内容不需要特殊处理：

## 这是一节标题

这里是一段普通正文，里面可以放一个[站外链接](https://gohugo.io/)。

- 第一项
- 第二项

写作时可以先不用考虑 AI 摘要。正文保存后，后面的工作流会自动处理它。

遇到 shortcode 就切换 Source mode

这个主题提供了不少 Hugo shortcode，比如提示框、折叠面板、标签页、Mermaid 和卡片。Pages CMS 不负责解析它们，只是把文章里的 Markdown 保存回 GitHub。

因此，正文里出现下面这些内容时，建议切换到 Source mode：

• {{< note >}}、{{< fold >}} 这类 Hugo shortcode；
• Mermaid 流程图或 Chart.js 数据；
• 复杂 HTML；
• shortcode 的示例代码；
• 需要保留精确缩进、空格和成对标签的内容。

比如这段提示框就应该在 Source mode 中编辑：

{{< note type="success" >}}
文章已经保存，接下来等待 GitHub Actions 构建。
{{< /note >}}

这里代码块里的 /* 和 */ 是为了让示例原样显示，实际文章中使用 shortcode 时不需要加这层转义。

如果把包含大量 shortcode 的文章交给 Editor mode，编辑器可能会重新排列 Markdown，或者把 shortcode 当成普通文本处理。文章看起来可能没问题，但构建时才发现标签没有闭合。遇到这类文章，Source mode 更稳妥。

图片怎么上传

Pages CMS 的媒体配置指向 static/img，文章正文图片建议放在：

static/img/posts/

上传后，在文章中使用公开路径：

![文章示例](/img/posts/example.webp)

提交前检查三件事：

1. GitHub 中的文件确实位于 static/img/posts/；
2. Markdown 里的文件名大小写和实际文件一致；
3. 引用使用 /img/posts/...，而不是 static/img/posts/...。

图片不会放进 content/posts。文章目录存 Markdown，静态资源目录存图片，这是 Hugo 处理静态文件的方式。

保存之后会发生什么

在 CMS 中保存文章以后，先确认页面提示已经提交成功，再打开 GitHub Actions 查看 Deploy to Cloudflare Pages。

Actions 会先运行摘要脚本。它会读取 content/posts 下的文章，清理 front matter、代码块、图片地址、HTML 标签和 Markdown 符号，然后把正文发送给配置好的 OpenAI 兼容接口。

生成结果会写回 front matter：

ai_summary: >-
  这里是根据文章内容生成的一段中文摘要。

随后 Hugo 使用带有摘要的工作树继续构建，Cloudflare Pages 部署的也是这次构建结果。

普通发布不会重复生成

摘要脚本默认只处理没有 ai_summary 的文章。这样修改一篇已有文章时，不会因为普通发布再次消耗模型额度，也不会让摘要在每次构建时发生变化。

如果确实需要重新生成已有文章的摘要，可以在 GitHub Actions 页面手动运行工作流，并把：

force_summaries = true

设为 true。

有一种情况会始终跳过：文章明确写了：

ai_summary: false

这表示作者不希望这篇文章生成摘要。普通发布和强制重新生成都不会覆盖这个停用标记。

本地也可以先试跑

如果想在提交前检查哪些文章会被处理，可以在博客仓库根目录执行：

node scripts/generate-ai-summary.mjs --dry-run

这条命令只列出候选文章，不调用 AI 接口，也不会修改文件。确认配置和文章都没有问题后，再运行完整命令：

node scripts/generate-ai-summary.mjs
hugo --gc --minify

本地摘要配置放在 .env 中：

AI_SUMMARY_API=https://api.siliconflow.cn/v1/chat/completions
AI_SUMMARY_API_KEY=你的 API Key
AI_SUMMARY_MODEL=Qwen/Qwen3-8B

.env 已经被 Git 忽略。不要把真实 Key 填进 .env.example，更不要把它放进文章里作为示例提交。

几个容易踩到的地方

Source mode 和 Editor mode 混着用

普通段落用 Editor mode 没问题，但一篇文章只要包含多个 shortcode，最好从头到尾在 Source mode 中检查一次。尤其要确认：

• 每个块级 shortcode 都有对应的结束标签；
• Mermaid、Chart.js 的内容仍然是合法格式；
• 代码块中的 shortcode 示例没有被提前解析；
• HTML 标签的引号和缩进没有被编辑器改坏。

AI 摘要失败后继续等部署

摘要接口返回错误、Key 缺失、模型名称错误或接口超时，Actions 会失败，后面的 Hugo 构建和 Cloudflare 部署不会继续执行。

这时先看 Actions 日志中的失败文件和错误信息，检查 AI_SUMMARY_API_KEY、接口地址、模型名称以及服务商状态。配置修好后，在原来的 workflow 页面重新运行即可。

把摘要当成 SEO 描述

ai_summary 是文章正文前的展示内容，description 才是文章的描述字段。两者用途不同，不要为了显示摘要而删掉 description，也不要把 API 返回结果直接塞进站点全局配置。

最后检查一下

现在这套流程可以概括成一句话：Pages CMS 负责写，GitHub 负责存，Actions 负责补齐摘要和构建，Cloudflare Pages 负责发布。

第一次使用时，我建议按下面的顺序走一遍：

1. 连接 kemiao-moretti/meowloge，确认分支是 main。
2. 检查 Posts 集合是否对应 content/posts。
3. 创建一篇测试文章，使用英文 slug。
4. 普通正文用 Editor mode，包含 shortcode 时切到 Source mode。
5. 上传一张图片，确认它最终位于 static/img/posts/。
6. 保存后查看 GitHub commit 和 Actions 运行结果。
7. 打开文章，确认摘要显示在正文前，图片、代码块和 shortcode 都正常。

这样以后想写文章时，不必先打开本地开发环境。打开 Pages CMS，写完，保存，等它跑完发布流程就可以了。偶尔需要改主题或调脚本时，再回到仓库里处理，两套入口各自负责擅长的事情，反而更清楚。

开始之前

Hugo shortcode 有两种边界符：{{< shortcode >}} 适合普通参数，{{% shortcode %}} 会先处理内部 Markdown。Solitude 的块级组件已经按各自用途处理正文，通常直接使用尖括号写法即可。

文本与状态

彩色文本与标签

p 用于整段文字，span 用于行内文字，label 用于短小的状态标记。颜色参数可使用 blue、green、orange、red、purple 等主题色名称。

写法

{{< p color="blue" >}}这是一段蓝色文字{{< /p >}}
正文中的 {{< span color="red" >}}重点文字{{< /span >}}
{{< label color="green" >}}已完成{{< /label >}}

效果

这是一段蓝色文字，用于在正文中形成较强的段落提示。

正文中的 重点文字 可以和普通内容自然排列。

已完成 信息 注意 扩展

提示框

note 是主要提示组件，subnote 适合在一个主题下继续补充次级信息。

写法

{{< note type="info" style="flat" >}}
提示内容，支持 Markdown。
{{< /note >}}

{{< subnote type="warning" >}}次级提示{{< /subnote >}}

效果

选择、快捷键与隐藏文字

这组组件适合展示只读状态和行内补充信息。checkbox 与 radio 仅负责表达，不会提交表单。

{{< checkbox checked=true >}}已完成事项{{< /checkbox >}}
{{< radio checked=false >}}未选择事项{{< /radio >}}
{{< keyboard >}}⌘ K{{< /keyboard >}}
{{< spoiler >}}移入或聚焦后显示{{< /spoiler >}}
{{< bubble position="left" >}}气泡消息{{< /bubble >}}

按下 ⌘ K 打开搜索；答案是 隐藏内容 。气泡消息left

链接、按钮与媒体

按钮与链接卡片

button 提供主题按钮，并通过 option 组合颜色、描边和整行样式；link 将链接呈现为带说明的资源卡片。站外链接会自动在新窗口打开并附带安全属性。

写法

{{< button url="https://gohugo.io/" text="Hugo 官网" icon="fas fa-link" >}}
{{< button url="/" text="描边按钮" icon="fas fa-house" option="blue outline" >}}
{{< link url="/" title="站内链接" desc="返回示例站首页" >}}

效果

Hugo 官网 描边按钮 适合移动端换行的整行按钮

图片

img 用于带说明的块级图片，inlineImg 用于跟随文字排列的小图片。

{{< img src="/img/default.avif" alt="示例图片" caption="主题默认封面" >}}
{{< inlineImg src="/img/avatar.webp" alt="Logo" height="24px" >}}

Solitude 与 Hugo 可以出现在同一行文字中。

视频与音频

YouTube、哔哩哔哩、原生音频和原生视频分别使用独立组件。外部媒体是否可播放仍取决于来源站点、网络环境与浏览器策略。

{{< youtube id="dQw4w9WgXcQ" >}}
{{< bvideo bvid="BV1xx411c7mD" >}}
{{< audio url="/media/example.mp3" name="示例音频" >}}
{{< video url="/media/example.mp4" poster="/img/default.avif" >}}

折叠、隐藏与卡片

折叠面板

fold 使用原生 details 结构，支持鼠标、触摸和键盘操作。添加 open=true 可让内容默认展开。

{{< fold title="展开内容" open=true >}}
折叠区域内支持 **Markdown**。
{{< /fold >}}

点击后显示

三个隐藏组件的区别只在呈现方式：hideInline 适合一句话，hideBlock 适合独立内容块，hideToggle 适合带标题的可切换区域。

{{< hideInline text="查看答案" >}}答案{{< /hideInline >}}
{{< hideBlock text="展开内容" >}}块级内容{{< /hideBlock >}}
{{< hideToggle title="阅读更多" >}}可切换内容{{< /hideToggle >}}

哪个组件适合藏在一句话里？查看答案

内容卡片

card 用于推荐项目、文章或资源。封面是可选项，没有封面时会自动切换到纯内容布局。

{{< card title="Hugo 卡片" url="https://gohugo.io/"
    cover="/img/default.avif" tag="资源" star="5" >}}
卡片说明
{{< /card >}}

数据与可视化

Mermaid 流程图

mermaid 直接接收 Mermaid 语法，适合流程图、时序图、状态图等结构化图形。

{{< mermaid >}}
flowchart LR
  Hexo --> Hugo
  Hugo --> HTML
{{< /mermaid >}}

Chart.js 图表

chartjs 支持 id、layout、width 和 description 参数。正文必须是合法 JSON。

{{< chartjs description="三期构建趋势" >}}
{"type":"line","data":{"labels":["一","二","三"],"datasets":[{"label":"趋势","data":[1,3,2]}]}}
{{< /chartjs >}}

{"type":"line","data":{"labels":["一","二","三"],"datasets":[{"label":"趋势","data":[1,3,2]}]}}

乐谱与动态文字

score 使用 ABC 记谱文本，typeit 用 speed 控制逐字显示速度。

{{< typeit speed="60" >}}TypeIt 动态文本{{< /typeit >}}

仓库与站点资源

仓库卡片

四个仓库组件使用同样的 repo="组织/仓库" 写法；自建 Gitea 还需要提供 host。仓库数据由浏览器访问对应平台 API，因此加载状态可能受网络或频率限制影响。

{{< github repo="gohugoio/hugo" >}}
{{< gitlab repo="gitlab-org/gitlab" >}}
{{< gitee repo="mirrors/hugo" >}}
{{< gitea repo="go-gitea/gitea" host="https://gitea.com" >}}

GitHub

hugo

正在读取仓库信息…

——

加载中

GitLab

gitlab

正在读取仓库信息…

——

加载中

Gitee

hugo

正在读取仓库信息…

——

加载中

Gitea

gitea

正在读取仓库信息…

——

加载中

友链列表

flink 的正文是 YAML 数据。一个组件可以包含多个分组，每个分组下可以继续放置多个站点。

{{< flink >}}
- class_name: 官方资源
  class_desc: Hugo 官方网站
  link_list:
    - name: Hugo
      link: https://gohugo.io/
      avatar: https://gohugo.io/images/hugo-logo-wide.svg
      descr: 世界上最快的网站构建框架
{{< /flink >}}

官方资源

Hugo 官方网站

Hugo 世界上最快的网站构建框架

布局与内容集合

图库与图库分组

gallery 负责瀑布流容器，内部使用 galleryItem 放置不同宽高的图片；columns 可指定桌面端列数。galleryGroup 则用于创建带封面、说明和链接的图库入口。

{{< gallery columns="2" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 1" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 2" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 3" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 4" >}}
{{< /gallery >}}

标签页

tabs 作为容器，每个 tab 提供标题和内容。为同一篇文章里的每组标签页设置唯一 id，可以避免状态互相影响。

{{< tabs id="demo-tabs" >}}
{{< tab title="第一个" >}}第一个标签页{{< /tab >}}
{{< tab title="第二个" >}}第二个标签页{{< /tab >}}
{{< /tabs >}}

时间线

时间线由 timeline 和一个或多个 timenode 组成。时间与标题应保持简短，详细说明放在节点正文中。

{{< timeline title="迁移时间线" >}}
{{< timenode time="2026-08-21" title="Hugo 版本" >}}
完成原生主题迁移。
{{< /timenode >}}
{{< /timeline >}}

系列文章与视频集合

series 会读取文章 Front Matter 中同名的 series，并按日期生成文章列表。videos 则把正文中的每行地址渲染为一个原生视频播放器。

{{< series name="官方示例" >}}

{{< videos col="2" >}}
/media/shortcodes/flower.mp4
/media/shortcodes/friday.mp4
{{< /videos >}}

1. Solitude Hugo Shortcode 使用指南

聊天记录

chat 使用简洁的行文本语法展示对话：{.名称} 切换到右侧发送者，{名称} 切换到左侧发送者；随后直接写消息内容，连续内容用 \\ 换行；{:内容} 是居中的系统提示（包括时间和撤回提示）。

{{< chat >}}
{:2024-11-09 23:39:30}
{.也许}
{.我们可以聊聊天}
{~克喵}
{.我还可以有名字}
{!克喵撤回了一条消息}
{用户 1}
{有趣}
{我学到了。}
{{< /chat >}}

1. 先用标准 Markdown 完成正文，只在标准语法无法表达时引入 shortcode。
2. 一个组件解决一种内容关系，避免为了装饰而层层嵌套。
3. 图片和媒体补全替代文本或标题，并优先选择稳定、可控的资源地址。
4. 发布前执行完整构建，再在桌面端与移动端检查长标题、代码块、表格和交互组件。