Congo 站点定制记录
目录
这篇只管站点作者怎么调模板。发文流程见：《Hugo + Congo 发文流程》；正文语法见：《Hugo 内容写法备忘》。
页面级 front matter #
基础增强 #
| 参数 | 类型 | 作用 |
|---|---|---|
lastmod | datetime | 最近更新时间 |
keywords | array | 输出到页面 meta keywords |
canonicalUrl | string | 指定 canonical URL |
robots | string | 覆盖页面级 robots |
externalUrl | string | 让文章卡片点击后跳到外链 |
列表 / 封面增强 #
| 参数 | 类型 | 作用 |
|---|---|---|
featuredWeight | int | 精选排序值，越小越靠前 |
feature | string | 指定 feature 图匹配名 |
cover | string | 指定 cover 图匹配名 |
thumbnail | string | 指定缩略图匹配名 |
featureAlt | string | feature 图替代文本 |
coverAlt | string | cover 图替代文本 |
thumbnailAlt | string | 缩略图替代文本 |
coverCaption | string | 文首封面说明 |
单页显示开关 #
这些参数用于单页覆盖站点默认值。
| 参数 | 类型 | 作用 |
|---|---|---|
showBreadcrumbs | bool | 是否显示面包屑 |
showDate | bool | 是否显示发布日期 |
showDateUpdated | bool | 是否显示更新时间 |
showWordCount | bool | 是否显示字数 |
showReadingTime | bool | 是否显示阅读时间 |
showEdit | bool | 是否显示编辑入口 |
showTaxonomies | bool | 是否在单页显示分类 / 标签 |
showTableOfContents | bool | 是否显示目录 |
showSharingLinks | bool | 是否显示文末分享按钮 |
showComments | bool | 是否显示评论 |
showSummary | bool | 列表卡片里是否显示摘要 |
本站自定义标题特调 #
这些不是 Congo 通用字段，而是本站模板额外支持的参数：
| 参数 | 类型 | 用途 |
|---|---|---|
titleStyle | string | 标题样式；当前支持 script |
titleSize | string | 标题尺寸；如 small |
birthLabel | string | 标题下方副标题 |
About 页示例：
YAML
1title: "Ch'eng-Lung Hu"
2birthLabel: "b. 1996.01.01"
3titleStyle: script
4titleSize: small
5showSharingLinks: falseCallout / Fold / Outdated 扩展 #
这块属于站点层能力，不是 Congo 原生全套行为。当前实现由三层组成：
Text
1Markdown 渲染钩子
2 -> layouts/_markup/render-blockquote.html
3
4短代码
5 -> layouts/_shortcodes/callout.html
6 -> layouts/_shortcodes/fold.html
7 -> layouts/_shortcodes/outdated.html
8
9样式
10 -> assets/css/custom/40-callout.css当前能力边界 #
| 能力 | 入口 | 说明 |
|---|---|---|
| GitHub Alerts | render-blockquote.html | 支持 > [!NOTE] / TIP / IMPORTANT / WARNING / CAUTION |
| Obsidian 风格折叠 marker | render-blockquote.html | 支持 + 默认展开、- 默认收起 |
| 站内分色提示框 | callout | 支持扩展类型、标题、折叠、打开状态 |
| 通用折叠块 | fold | 中性折叠或带类型折叠 |
| 过期提示 | outdated | 按基准日和阈值动态显示 |
维护建议 #
Text
1只想写正文
2 -> 直接看《Hugo 内容写法备忘》里的用法
3
4要继续扩类型 / 图标 / 默认标题 / 显示逻辑
5 -> 改 callout / fold / outdated shortcode
6 -> 改 render-blockquote hook
7 -> 改 40-callout.css字段与兼容策略 #
当前站内色系对齐 GitHub Alerts：
notetipimportantwarningcaution
另外保留站内扩展别名：
successforbiddangercritical
其中 GitHub Markdown 只认基础五类；扩展别名仍建议走短代码。
当前模板的实际入口 #
如果要继续扩模板，优先看这些文件：
Text
1layouts/single.html
2layouts/_partials/article-meta.html
3layouts/_partials/extend-head.html
4layouts/_markup/render-image.html
5layouts/_markup/render-codeblock.html
6config/_default/markup.toml
7assets/css/custom/06-page-title.css其中职责可以这样理解：
Text
1single.html
2 -> 单页总装配、标题特调、显示开关
3
4article-meta.html
5 -> 日期、阅读时间、标签等元信息
6
7render-image.html / render-codeblock.html
8 -> Markdown 渲染钩子
9
10extend-head.html + custom CSS
11 -> 字体、额外资源、页面级样式扩展维护建议 #
Text
1普通作者写文章
2 -> 看《Hugo + Congo 发文流程》
3
4需要正文短代码 / 排版效果
5 -> 看《Hugo 内容写法备忘》
6
7需要新增参数、改模板、调显示行为
8 -> 看本文