如何使用文档系统

Stellar 独创了其它 Hexo 主题所没有的 Wiki 文档系统，可以自动找到一个项目的所有文档分页，生成一个目录树，还可以手动指定顺序、标题、分组，而非依赖文件路径、文件名来排序和显示。

基本流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

name: Stellar
title: Stellar - 每个人的独立博客
headline: 每个人的独立博客 # 可选：Wiki 卡片营销标题，空时取 title
subtitle: '每个人的独立博客 | Designed by xaoxuu'
tags: 博客主题
available: Web # 可选：Wiki 列表卡片显示“适用于”范围
icon: https://res.xaox.cc/gh/cdn-x/wiki@main/stellar/icon.svg
cover: https://res.xaox.cc/gh/cdn-x/wiki@main/stellar/icon.svg
description: Stellar 是一个内置文档系统的简约商务风 Hexo 主题，支持丰富的标签和动态数据组件。
pin: 1 # 置顶轮播排序值（可选，设置即置顶，数字越大越靠前，true 视作 1）
repo: xaoxuu/hexo-theme-stellar
search:
  filter: /wiki/stellar/
  placeholder: 在 Stellar 中搜索...
leftbar: 
  - tree
  - timeline_stellar_releases
  - related
comment_title: '评论区仅供交流，有问题请提 [issue](https://github.com/xaoxuu/hexo-theme-stellar/issues) 反馈。'
comments:
  service: giscus
  giscus:
    data-repo: xaoxuu/hexo-theme-stellar
    data-mapping: number
    data-term: 226
base_dir: /wiki/stellar/
tree:
  '快速开始':
    - index
    - examples
    - releases
  '基本使用':
    - theme-settings
    - pages
    - sidebar
    - tag-plugins
    - tag-plugins/express
    - tag-plugins/data
    - tag-plugins/container
    - comments
  '文档系统':
    - wiki-settings
  '进阶玩法':
    - widgets
    - advanced-settings
    - notes
  '技术支持':
    - articles
    - todo
    - contributors

1
2
3
4

---
wiki: hexo-stellar # 这是项目id，对应 /data/wiki/hexo-stellar.yml
title: 这是分页标题
---

1
2

- hexo-stellar
- 其它项目

项目分页索引

指定项目所在文件夹和目录树：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

base_dir: /wiki/stellar/
tree:
  '快速开始':
    - index # 会被关联到 /wiki/stellar/index.md
    - examples # 会被关联到 /wiki/stellar/examples.md
    - releases
  '基本使用':
    - theme-settings
    - pages
    - sidebar
    - tag-plugins
    - tag-plugins/express
    - tag-plugins/data
    - tag-plugins/container
    - comments
  '文档系统':
    - wiki-settings
  '进阶玩法':
    - widgets
    - advanced-settings
    - notes
  '技术支持':
    - articles
    - todo
    - contributors

如果目录树不需要分组，可以这样写：

1
2
3
4
5

base_dir: /wiki/stellar/
tree:
  - index # 会被关联到 /wiki/stellar/index.md
  - examples # 会被关联到 /wiki/stellar/examples.md
  - ...

是否显示封面

项目可以显示一个全屏封面，封面占据一个屏幕的高度，会居中依次显示项目的 logo、标题、描述。开启项目封面方法如下：

1
2

cover: https://res.xaox.cc/gh/cdn-x/wiki@main/stellar/icon.svg
coverpage: true # 默认是 true

如果 logo 中已经包含了项目标题，可以这样设置不显示项目标题：

1

coverpage: [logo, description]

项目首页 Hero 封面

开启 coverpage 后，项目首页会渲染为全屏双栏 Hero。cover 仍只用于 Wiki 列表卡片；Hero 的 background 只接受静态图片 URL，动态效果通过独立的 animation 配置启用。静态图在底部 20% 会渐变模糊并过渡到站点背景色。

animation.type: galaxy 使用四层 WebGL 星场呈现纵深移动、辉光、闪烁与自动旋转，默认带有轻量鼠标排斥。Galaxy 默认透明，可以单独使用，也可以叠加在 background 图片上；两者同时存在时，标题和按钮按图片平均色自适应，动画不可用时仍保留图片。仅配置 Galaxy 时使用纯黑底色。离开视口或页面进入后台时动画自动暂停；浏览器启用“减少动态效果”、不支持 WebGL 或动态层加载失败时只显示静态回退。旧的 background: galaxy 写法不再支持。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

background: https://res.xaox.cc/hero.webp # 可选，可与动画叠加
animation:
  type: galaxy
  params: # 可选，未填写的参数使用默认值
    density: 2
    hueShift: 140
    speed: 0.5
    glowIntensity: 0.2
preview:
  type: terminal # terminal | image
  commands:
    - label: npm
      codes: |
        npm i hexo-theme-stellar
        npx hexo config theme stellar
    - label: pnpm
      codes: |
        pnpm add hexo-theme-stellar
        pnpm exec hexo config theme stellar
actions:
  - title: 在线演示
    url: https://example.com
    icon: default:monitor

Galaxy 支持以下全部参数与默认值：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

animation:
  type: galaxy
  params:
    focal: [0.5, 0.5]
    rotation: [1, 0]
    starSpeed: 2
    density: 2
    hueShift: 140
    speed: 0.5
    glowIntensity: 0.2
    saturation: 0.1
    mouseRepulsion: true
    twinkleIntensity: 0.1
    rotationSpeed: 0.1
    repulsionStrength: 0.1
    autoCenterRepulsion: 0
    transparent: true

参数缺失时逐项使用默认值，未知参数会被忽略。focal 的两个数值限制在 0–1；rotation 接受两个有限数值；hueShift 会归一化到 0–360；速度、密度和强度参数必须为非负有限数值；rotationSpeed 可以为负数以反向旋转；布尔参数只接受 true 或 false。非法值只回退当前参数，不影响其它有效配置。显式设置 transparent: false 时，不透明 Canvas 会覆盖同时配置的背景图片。

终端模式的 commands[].codes 支持多行文本，访客可切换安装方式并一次复制完整命令。图片预览改为：

1
2
3
4

preview:
  type: image
  src: https://res.xaox.cc/demo.webp
  alt: Stellar 首页预览

Hero 顶部左侧是无背景的站点标题按钮，文字取站点 title、颜色沿用 Hero 的 --text-banner，点击返回网站首页。封面左侧会自动显示 name、headline（为空时回退 title）和 description；主标题会随背景明暗切换为高对比的黑或白，并保留同源主题色的柔和发光轮廓。配置 repo 时，内置“源码”按钮及 GitHub 最新 tag 版本信息会自动出现；版本信息加载期间不显示占位文字或边框，成功后淡入，并以新标签页打开 GitHub 返回的链接（缺失时回退到对应 tag 页面）。无 tag 或请求失败时，该按钮会自动移除。“源码”按钮背景与边框使用 --text-banner，文字与图标反转相同颜色，始终与背景形成相反关系。启用 plugins.card_hover 后，源码、文档与自定义 action 按钮会显示鼠标跟随光斑，但不会倾斜或上浮；插件关闭、触屏或减少动态效果时保持原样。最新版本标签的边框取同源主题色的 50% 透明度，文字不受影响。内置“文档”按钮固定跳转到当前首页正文，actions 用于追加在线演示等自定义按钮。直接打开不带 hash 的项目首页时，页面默认停在 Hero 顶部；仅显式访问 #start 或点击“文档”按钮时才定位到正文。内置按钮、终端复制、未命名命令序号与辅助标签会随站点 language 切换；actions[].title 是项目自定义文案，不会由主题翻译。图片背景与仅 Galaxy 的黑色底图都会沿用 Wiki 列表封面的文字自适应逻辑：标题取高对比色，说明与玻璃按钮取同源主题色；终端预览则将该主题色与透明色各混合 50%，再叠加背景模糊，主题色尚不可用时回退站点背景色。图标使用主题内置的 default:* 名称，例如 default:monitor。

项目文档标签

如果您有很多项目，有些项目是有相关性的，可以相同的 tags 值：

1

tags: 博客主题

也可以设置多个 tags 值：

1

tags: [博客主题, 开源项目]

项目的 GitHub 仓库信息

设置了 repo 值就会在右上角显示项目仓库的相关链接：

1

repo: xaoxuu/hexo-theme-stellar

提示：如果项目首页（如 source/wiki/{id}/index.md）正文为空，且配置了 repo（可选 branch），该页会自动以 GitHub 仓库的 README.md 作为主页正文——标题自动适配文章格式，相对图片/链接解析到仓库镜像地址，右侧目录也会在渲染后自动生成。branch 缺省使用仓库默认分支；首页正文非空时以本地内容为准。

说明：正文为空的 README 主页（以及其它 wiki 页）的 meta description / og:description / JSON-LD 描述会优先取用项目 YAML 中的 description 作为备用方案；页面 front matter 显式设置 description（或 open_graph.description）时以页面级描述为准。

项目评论设置

如果希望项目的所有分页使用相同的评论数据，可以在这里覆盖评论配置：

1
2
3
4
5
6

comment_title: '评论区仅供交流，有问题请提 [issue](https://github.com/xaoxuu/hexo-theme-stellar/issues) 反馈。'
comments:
  giscus:
    data-repo: xaoxuu/hexo-theme-stellar
    data-mapping: number
    data-term: 226

侧边栏组件

如果您希望自定义某个项目的侧边栏组件，可以设置 sidebar 值：

可以覆盖组件：

1
2
3
4

leftbar:
  - tree
  - timeline_stellar_releases
  - related

todo

在目录树中隐藏某篇文章

可以在 front-matter 中不设置 title 标题，或者将 title 改为 seo_title：

1

title: 原本的标题

todo

显示许可协议

沿用主题配置文件中设置的：

1

license: true

也可以指定协议内容：

1

license: '本文采用 [署名-非商业性使用-相同方式共享 4.0 国际](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可协议，转载请注明出处。'

显示分享

1

share: true

修改 wiki 路径

修改如下配置：

1
2
3

site_tree:
  wiki:
    base_dir: wiki # books / products ...