Hugo + Congo 发文流程

这篇只回答一个问题：怎样从 0 到 1 发出一篇文章。

如果你要查正文语法或站点特调，不要继续在这一篇里翻：

正文能力见：《Hugo 内容写法备忘》
模板特调见：《Congo 站点定制记录》

新建文章 #

Hugo 不会「猜」你今天该放哪：你给出内容路径，它用 archetypes/default.md 生成 front matter，再按 config 里的 permalink 出站。本站磁盘目录与对外 URL 解耦。

目录约定 #

1content/posts/
2  {十年桶}/
3    {年}/
4      {月}/
5        YYYY-MM-DD-标题/index.md   # 推荐：page bundle
6        # 或 YYYY-MM-DD-标题.md    # 单文件亦可

层	作用	是否进对外 URL
`2010s` / `2020s`	十年整理桶	否
`2026`	年	否，URL 年份来自 front matter `date`
`07`	月	否，只用于本地整理
文章目录或 `.md`	正文	路径不进 URL；`slug` 进 URL

十年 / 年 / 月的 _index.md 一律：

1build:
2  render: never
3  list: never

对外固定规则：

1/posts/:year/:slug/

推荐：`create.py` #

仓库根目录执行；按 Asia/Shanghai 当天 拼路径、补 _index.md、写草稿 front matter。

1python create.py 今日随笔

会先问形态：

11) 单文件  2026-07-20-今日随笔.md
22) bundle  2026-07-20-今日随笔/index.md

后续流程：

1hugo server -D    # draft: true 需 -D
2# 定稿后改成 draft: false
3hugo

不依赖脚本时，也可以直接：

1hugo new content "posts/2020s/2026/07/2026-07-20-今日随笔.md"
2hugo new content "posts/2020s/2026/07/2026-07-20-今日随笔/index.md"

常用 front matter #

archetypes/default.md 当前实际生成的是：

1title: "（由文件名推导，可改）"
2date: （创建时刻）
3draft: true
4slug: "20060102150405"
5categories: ["随笔"]
6tags: []
7summary: ""
8featured: false
9# featuredWeight: 1

普通文章最常用的字段只有这些：

参数	类型	作用
`title`	string	文章标题
`date`	datetime	发布时间；URL 年份、归档都看它
`draft`	bool	草稿开关
`slug`	string	URL 末段
`categories`	array	分类
`tags`	array	标签
`summary`	string	列表摘要
`featured`	bool	是否进入首页精选

推荐最小集：

1title: "今日随笔"
2date: 2026-07-20T12:42:00+08:00
3draft: true
4slug: "20260720124200"
5categories: ["随笔"]
6tags: []
7summary: ""
8featured: false

封面图 #

Congo 的封面来自 页面资源（page resources）。图必须和这篇 index.md 放在同一个目录。

1文章目录
2  ├─ index.md
3  ├─ feature.jpg   -> 列表缩略图 + 文首封面（优先）
4  ├─ cover.jpg     -> 仅文首封面
5  └─ thumb.jpg     -> 仅列表缩略图

只要一张图时，直接命名为 feature.jpg / feature.png 即可。

对应的可选说明文字：

1featureAlt: "封面图替代文本"
2coverCaption: "封面图说明"

站内文章链接 #

站内文章不要手写最终 URL，优先用 relref：

1使用方式见：[《Hugo 内容写法备忘》]({{< relref "/posts/2020s/2026/07/2026-07-24-Hugo-内容写法备忘/index.md" >}})

这样以后你改 slug 或 permalink 规则时，链接仍能跟着走。

发文时的两套心智模型 #

1普通文章（无封面）
2  -> title / date / draft / slug / categories / tags / summary
3
4带封面或想进精选
5  -> 上面那套
6  -> + feature.jpg（放同目录）
7  -> + featureAlt / coverCaption
8  -> + featured / featuredWeight

新建文章 #

目录约定 #

推荐：create.py #

常用 front matter #

封面图 #

站内文章链接 #

发文时的两套心智模型 #

延伸阅读 #

推荐：`create.py` #