首页与落地页
首页不是模板,是一份数据:data/home/<语言>.yaml 里的 sections 列表决定页面从上到下有哪些分区,每个分区的内容在同一份文件里按名字取。普通页面加 layout: landing 也能用同一套分区。
分区全部在服务端渲染。价格、star 数、截图、头像、下载状态都必须在 Hugo 启动前就存在于仓库中,没有分区会在浏览器里取数据。
从 Docsy 的 blocks/* 首页迁移过来的站点要重写首页:主题没有 blocks/cover、blocks/section、blocks/feature 这些 shortcode,保留它们会让构建报 template for shortcode "blocks/cover" not found。两条出路是本页讲的 data/home/<语言>.yaml,或者给一个普通页面加 layout: landing。
首页的数据来源
首页的内容文件只留标题与描述:
分区数据按语言分文件:
首页数据
data/
home/
- en.yaml英文站首页
- zh.yaml中文站首页
查找顺序是 data/home/<当前语言>.yaml → data/home/en.yaml → 单语言站点的 data/home.yaml。
文件结构只有两层:一个 sections 列表,加上被列表引用的同名键。
这是本站首页的写法,完整文件见仓库的 data/home/zh.yaml。
最小可用首页
粘贴下面这段,替换文字与链接即可发布。链接写成不带前导斜杠的站内路径,主题会补上当前语言前缀(docs/start/ → /zh/docs/start/)。
Hero
Hero 是首屏,唯一一个带大标题与配图的分区。
不写 title_lines 时用 title,两者都没有时用站点标题。配图是 CSS 背景图,alt 有值时容器带 role="img",无值时对辅助技术隐藏。
align: center 是纯文字的居中首屏:文案块加宽居中,标题自动平衡换行,note 挪到按钮下方。它不接受 image,两者同时出现构建失败。
分区注册表
22 种分区,名字用连字符(旧数据里的下划线会被规范化)。除 Hero 之外,每种都共用 eyebrow / title / desc(或 text)三个抬头字段与一个 class。
| 类型 | 放什么 |
|---|---|
hero |
首屏:大标题、按钮、跟随主题的配图 |
metrics |
数字事实,可选计数动画与来源链接 |
capabilities |
左右交替的能力叙事 + 专用视觉面板 |
principles |
编号的产品原则 |
cards |
通用卡片集合:功能、场景、入口 |
logo-wall |
工具与伙伴,网格或纯 CSS 跑马灯 |
gallery |
截图墙 |
testimonials |
引语与署名 |
contributors |
人、角色、头像与链接 |
faq |
折叠或平铺的问答 |
markdown |
一段自由 Markdown |
cta |
结尾的行动号召 |
pricing |
价格档位卡片 |
pricing-compare |
档位功能对比矩阵 |
command-box |
一条可复制的命令 |
steps |
有序流程,可带命令 |
timeline |
带日期的里程碑 |
code-plate |
展示面板里的代码 |
preview |
一段 Markdown 源码与它渲染出来的样子并排 |
case-study |
案例:指标 + 引语 + 出处 |
download |
一个或多个 data/download/ 记录 |
bar-chart |
不用图表 JS 的数值对比 |
写错类型名不会静默消失:构建时给一条 unknown section type 警告并跳过该分区。CI 里加上 --panicOnWarning 即变成构建失败。
常用分区的最小写法
卡片与能力面板是最常用的两种。cards 用 columns 控制列数:
capabilities 是一屏一条能力,右边配一块结构化的视觉面板,visual.type 只能是 shell、components、code、image、card 五种之一:
另外十种场景分区的最小 YAML
这些片段摘自主题仓库的可执行回归夹具
tests/site/data/landing/demo/en.yaml,字段名可照抄。
download 分区消费的就是发布与下载页里那份 data/download/<key>.yaml,不引入第二套版本模型。
任意页面做落地页
普通内容页加两行 front matter 即成为落地页:全宽画布,保留顶栏、命令面板与页脚,去掉侧栏与目录。
数据放在与首页平行的目录下,同样按语言分文件:
落地页数据
data/
landing/
pricing/
- en.yaml
- zh.yaml
非首页落地页按这个顺序查找数据,找不到则构建失败,不会渲染空页面:
- 页面 front matter 里的
sections; data/landing/<key>/<精确语言>.yaml;- 单文件
data/landing/<key>.yaml里的精确语言条目; - 英文或无语言后缀的记录。
数据量小时可以写在 front matter 里,但 landing: 与 sections: 互斥:
分区条目写法
sections 的每一项可以是一个类型名字符串,也可以是一个 Map:
| 键 | 作用 |
|---|---|
type |
分区类型;省略时用 key 当类型 |
key |
从哪个键取数据,默认与 type 同名;同一种分区用两次时用它区分 |
data |
内联数据,不再到顶层查找键 |
id |
分区的锚点 ID,默认由 key / type 生成 |
enabled: false |
停用这个分区,保留数据 |
partial |
换成站点自己的 partial。属于本地模板约定,不是可移植的 Landing 数据 |
多语言与本地事实
叙事文字优先分语言文件(zh.yaml / en.yaml)。共享的事实记录也可以在字段级回退:<字段>_<精确语言> → <字段>_<主语言> → <字段>,语言标签里的 - 规范化成 _。中文站解析 title_zh_cn、title_zh、title。不接受 camelCase 后缀。
分区里的显示文字是站点数据,不是主题的 i18n 字符串。只有跑马灯暂停、定价状态这类主题自带控件用翻译键。多语言站点的整体配置见多语言。
落地页外壳上的几个可选事实也是本地的,写在 hugo.yml 里,运行时不会去取它们:
页脚不属于首页数据:它读 data/footer/<语言>.yaml(单语言站点用 data/footer.yaml),本站两种语言各一份。data/home/<语言>.yaml 里残留的 footer 键会让构建失败并提示新位置。写法见导航与菜单。
输出形态
| 输出 | 呈现 |
|---|---|
| HTML | 完整的静态分区内容,再按需加载 landing.js 做渐显、计数、复制与主题图片切换 |
| 打印 | 内容保留,跑马灯之类的动态面变成静态网格,控件移除 |
| Markdown | 标题、正文、列表、表格与代码,不带组件 class |
| RSS | 不输出 Landing 分区 |
禁用 JavaScript 后服务端文档仍然完整。跑马灯的副本轨道不进无障碍树,暂停用的是不依赖 JavaScript 的复选框;读者开启减少动态效果偏好时,移动与渐显关闭。
验证
- 构建零告警:
hugo --printPathWarnings --panicOnWarning。类型写错、数据键不存在、landing与sections同时出现都在这一步暴露。 - 打开首页与落地页,逐个分区对照数据文件,每种语言各看一遍。
- 禁用 JavaScript 后刷新:内容仍在,只是没有动效。
- 深浅色各看一遍,确认
image.light/image.dark都给对。 - 部署到子路径时,确认站内链接与图片都带上了前缀。
相关
- 品牌外观 — 站名、Logo、配色与字体
- 导航与菜单 — 顶栏、页脚与语言菜单
- 发布与下载页 —
download分区的数据来源 - 多语言 — 语言启用与数据分文件
- 配置总览 —
params.ui.landing_search等参数的完整定义