Collection 配置

版本范围：以 2.0.0-rc.5 为发布基线，并核对截至 2026-09-18 的 main 源码（5c6c7a7c）。标注「main 开发版」的能力尚不包含在 rc.5 中；升级差异见版本记录。

Collection 文件位于 source/_data/wiki/、source/_data/topic/ 或 source/_data/notebooks/。文件路径提供 profile，文件名提供 ID；name 是显示名称；省略时使用 Collection ID 并给出 warning。只需填写当前集合要修改的配置，其余值由主题提供。

基本信息、路径与展示

没有集合封面时不跨字段使用 icon 或横幅补齐；成员文章的根级 cover/tagline 也不继承集合对应字段。

Hero 与横幅

hero 仅用于 Wiki：

Collection 不配置 banner。成员页面用自己的 cover 提供内容横幅图片，用 Front Matter banner.enabled/avatar/headline/tagline 控制横幅内容；集合 cover 不继承到成员。Hero 背景单独使用 hero.background。

视频与滚动视差（main 开发版）

hero:
  enabled: true
  background:
    image: /images/wiki-poster.webp
    video: /videos/wiki-hero.mp4
    parallax: 0.2

video 接受站点资源路径或完整 URL，以静音、循环、自动播放和行内播放方式显示；自动播放仍受浏览器策略约束。设置视频后不加载 effect，image 同时作为视频 poster 和背景底图。静态图片、视频和动态效果都支持 parallax，默认 0.2，范围 0–1；设为 0 或系统启用减少动态效果时关闭位移。视频与未叠加动态效果的图片在 Hero 滚出视口时仍会渐隐，parallax: 0 不关闭该渐隐。

Hero 背景效果

hero.background.image 与动态效果可以同时配置：图片位于 Canvas 下方，动态效果加载失败时仍保留图片。没有图片时，Strands、Galaxy 和普通 Light Rays 使用黑色静态底色，Ferrofluid 使用其 backgroundColor；lightMode: true 的 Light Rays 使用白色底色。Canvas 不接收指针事件，不会遮挡 Hero 中的链接和按钮。

Strands（main 开发版）

流动的发光丝带，可叠加玻璃折射效果。需要浏览器支持 WebGL 2；无背景图片时使用黑色底色。

hero:
  enabled: true
  background:
    effect:
      type: strands
      options:
        colors: ['#F97316', '#7C3AED', '#06B6D4']
        glass: true

数字参数在 Schema 中要求有限数值；运行时将 amplitude、waviness、glow、taper、spread、intensity、saturation 的负值按 0 处理，thickness、scale 最小为 0.0001；玻璃半径按 max(0.0001, 0.46 × glassSize) 计算。未知参数和不合法颜色不属于支持配置。

Ferrofluid

hero:
  enabled: true
  background:
    effect:
      type: ferrofluid
      options:
        colors: ['#ffffff', '#06B6D4', '#E0F2FE']
        backgroundColor: '#03010A'
        speed: 0.5
        flowDirection: down
        mouseInteraction: true

颜色可省略开头的 #；在 YAML 中使用带 # 的颜色时需要加引号。React 组件专用的 className 不属于主题配置。

Light Rays

hero:
  enabled: true
  background:
    effect:
      type: light-rays
      options:
        raysOrigin: top-center
        raysColor: '#00ffff'
        raysSpeed: 1.5
        lightSpread: 0.8
        rayLength: 1.2
        followMouse: true
        mouseInfluence: 0.1
        noiseAmount: 0.1
        distortion: 0.05

Galaxy

hero:
  enabled: true
  background:
    effect:
      type: galaxy
      options:
        starSpeed: 2
        hueShift: 140
        mouseInteraction: true

所有内置效果都支持运行时策略：

hero:
  background:
    effect:
      type: light-rays
      runtime:
        pause_when_hidden: true
        respect_reduced_motion: true

pause_when_hidden 控制 Hero 离开视口或页面进入后台时是否暂停；respect_reduced_motion 控制系统请求减少动态效果时是否停止加载。两项默认都是 true。效果参数中的未知字段、错误类型、非法方向或颜色，以及 Ferrofluid 超过八项的颜色数组或非正数 DPR，都会在构建期报错。

Region 与 Brand

顶部栏、左侧栏、右侧栏（Region）使用 enabled/widgets，Topbar 和 Leftbar 还支持 brand/menu，Leftbar 支持 footer.actions，main 开发版另支持 menu_columns（1–5 的整数，null 继承）。它们沿用主题结构，但作为局部覆盖：省略继承，数组整体替换，[] 清空。

Collection 的 leftbar.brand 额外支持 source: site/collection、back_button。Wiki/Notebook 默认来源是 collection，Topic 默认 site；返回开关只在 collection 来源有效；search、ghrepo、ghuser 沿用共享 Leftbar Brand 字段，搜索适用于两种来源。style: regular/compact 与来源独立。Brand 整体可为 false 或 null；null 继承，false 隐藏。具体字段 null 隐藏对应内容。

成员默认值

具体取值见 Front Matter，它与 Collection 共用这些内容覆盖结构。对象逐字段覆盖并不意味着所有 null 都有相同效果，详见行为规则。

Wiki、Notebook Collection 的 footer.share 默认关闭，Topic 默认继承全局 Article 分享。设置 true 会恢复全局 article.footer.share，数组显式选择服务，false 或 [] 关闭；许可协议同样可用 true 恢复全局 Article 文案。Collection 的 visibility.listed: false 会隐藏集合总入口，并成为成员页的默认列表状态；searchable: false 成为成员页的默认搜索状态。页面可以显式改回 true，详情路由仍然生成。

各集合类型支持的功能

配置项需要符合所属集合类型。例如，Notebook 不能使用 Wiki 的 Hero；即使 YAML 格式正确，Doctor 和站点生成仍会报错。visibility 是三类 Collection 的共享字段；render、seo、inject 只能写在页面中。