内容 · 栏目与引用
用目录组织正文
分类通过栏目层级和文章引用实现,栏目名称由站点定义。Banyan 最小演示用 articles、articles-all 展示文章分类与全部列表,
用 products、products-all 展示产品分类与全部列表。这些目录名可以按本站需要修改。
正文放在所属目录中,栏目列表直接使用这些文件。需要把同一篇文章列入其他栏目时,
在目标栏目放入 _map.toml,添加栏目文章引用。
content/
├─ articles/
│ ├─ _index.md
│ └─ category1/
│ ├─ _index.md
│ └─ example/
│ └─ index.md
├─ articles-all/
│ └─ _index.md
├─ products/
│ ├─ _index.md
│ └─ examples/
│ ├─ _index.md
│ └─ _map.toml
└─ products-all/
└─ _index.md
示例省略同路径的中文译文。有子文章的栏目使用 _index.<lang>.md,其中的标题、
介绍和正文属于该栏目。单篇文章统一使用 name/index.<lang>.md 叶子包,
文章资源放在同一目录。index.<lang>.md 不用于容纳下级文章的栏目。
默认语言文件可以省略语言后缀。
文章模板由站点根 archetypes/banyan.md 维护,Module 和传统主题目录不提供。
swban base/hugo new content --kind banyan articles/my-post/index.zh.md #新建中文文章
生成后编辑标题、说明和正文,发布前将 draft 改为 false。完整操作见添加第一篇文章。栏目布局和文章布局由上级 cascade 继承,无须为每篇文章再写分类字段。
列表配置见 列表与产品声明。
每篇正文直接声明固定网址,例如 url: p/example-product/。
各语言保留自己的语言前缀;移动正文或修改标题时,保留 url 即可保持发布网址。
如果构建报告网址冲突,修改其中一篇的 url。
栏目页仍使用目录网址。新增顶层正文栏目无需追加路由配置。
新增栏目
例如要在文章下新增“笔记”栏目:
- 创建
content/articles/notes/。 - 在其中创建
_index.zh.md,写入下方内容。它继承参考站articles/的列表与文章布局。 - 将中文文章放入该目录下的独立页面包,如
notes/first-note/index.zh.md,或用下一节的方法引用已有文章。 - 预览中文文章栏目,确认“笔记”入口与文章都能打开。
---
title: 笔记
description: 收录日常笔记。
---
其他语言在同一目录创建对应的 _index.<语言代码>.md。新建顶层栏目时,还需配置布局及后代页面默认值,可复制参考站 content/articles/_index*.md 后修改标题、顺序与说明。
引用到其他栏目
在目标栏目创建 _map.toml。例如 content/products/examples/_map.toml:
refs = ["/articles/category1/example"]
路径指向内容,不写语言、域名或文件扩展名。一份 _map.toml 供同目录各语言栏目共用。
列表使用当前语言的原文标题、描述、日期、图标和网址。
该语言没有原文时,这一语言不显示该引用。
文章默认归属由实际目录确定,额外归属由引用它的栏目确定。 文章元信息列出实际目录路径和额外栏目路径;从引用栏目进入时,面包屑导航显示该来源。 正文始终只有一个地址,不生成引用页或正文副本。移动原文后,需要更新引用路径。
含 _map.toml 的栏目及其祖先须使用 build.list: always 或 local。
同一篇文章经不同子栏目汇总到共同祖先时,只显示、计数和订阅一次。
引用不创建新页面地址。站点地图不会重复收录;llms.txt 可以在所属栏目和引用栏目中分别列出同一正文。
产品目录
产品目录同样使用真实文章和 _map.toml。Banyan 演示只在 products/examples/ 放一份
_map.toml,引用 /articles/category1/example。该栏目从 products 根继承
layout: page-collection-products;products-all 使用 page-collection-products-all 并通过 params.aggregate: /products 汇总产品目录。
articles-all 使用 page-collection-directory-all 和 params.aggregate: /articles,汇总文章目录中的正文。
目录名和汇总入口可以修改。
正文的 params.offer 提供价格,并可保留版本定义值,不控制收录。
详见 怎样收录产品。
演示站根配置保留空的 [taxonomies],关闭 Hugo 默认的 tags 和 categories。
目录与引用不依赖原生 taxonomy。