P1neConeeのblog
设置

2026年9月8日，正式开启博客记录，下面是用ds生成的易于掌握的hexo博客，stellar主题部署使用手册

前言：这本手册该怎么读

这本手册是给谁看的

如果您是第一次接触 Hexo 或 Stellar，对命令行感到陌生，对”Front Matter”、”Collection”、”Widget”这些词一头雾水——那这本手册就是为您写的。它把官方技术文档翻译成了人话，并补充了大量”为什么要这样做”的解释。

这本手册和官方文档的关系

官方文档 本手册
定位 技术参考辞典 从零到一的教程 + 辞典
适合谁 已经熟悉 Stellar 的人 新手 + 需要快速查阅的人
内容 完整但零散 完整 + 按场景组织 + 步骤化
更新 跟随最新版本 基于本站 v2.0.0-alpha.1

本手册的目标：覆盖官方文档 100% 的配置项和功能点，但用更易懂的语言重新表述，并按照”第一次做某件事”的场景来组织章节。您既可以按顺序通读，也可以在遇到具体问题时直接跳到对应章节。

本手册的结构

章节 内容 适合什么时候读
第一章 环境准备与安装 第一次搭建站点时
第二章 目录结构与文件职责 理解项目框架，知道什么文件放哪里
第三章 站点配置完全参考 需要改任何配置时查阅
第四章 Front Matter 完整参考 写任何内容前查阅字段含义
第五章 四类内容完全指南 决定写什么类型的内容时
第六章 Collection 登记与导航 创建专栏/知识库/笔记本时
第七章 三栏布局与 Widget 完全指南 想调整左右侧栏显示什么时
第八章 标签插件速查大全 想在文章里插入特殊内容块时
第九章 功能开关速查 需要开启/关闭某个功能时
第十章 命令与日常工作流 日常写作时快速查阅
第十一章 版本说明与避坑指南 升级主题或遇到费解错误时

配套资源

第一章 环境准备与安装

建议看这篇文章

https://cloud.tencent.com/developer/article/2522029

1.1 您需要准备什么

在开始之前，请确认您的电脑上有以下工具：

  • Node.js（版本 16 或以上）：在终端输入 node -v 可以查看版本。如果未安装，去 nodejs.org 下载 LTS 版本。
  • Git：在终端输入 git --version 可以查看版本。如果未安装，去 git-scm.com 下载。
  • 一个代码编辑器：推荐 VS Code（免费），也可以使用任何文本编辑器。

安装完成后，重新打开终端，确保新安装的命令可用。

1.2 克隆站点到本地

您已经有了一个完整的站点项目（就是包含 package.json 和 _config.yml 的这个文件夹）。把它放在您电脑上方便找到的位置。

用终端 cd 进入到这个文件夹：

1
cd /path/to/stellar-knowledge

小提示：在 Windows 上，可以打开文件夹，在地址栏输入 cmd 回车，就能快速打开终端并定位到当前目录。在 macOS 上，可以右键点击文件夹选择”在终端中打开”。

1.3 安装依赖

在项目根目录下运行：

1
npm install

这会安装所有需要的依赖包。首次安装可能需要 1-3 分钟，取决于网络速度。您会看到终端里滚动很多文字，耐心等待即可。看到 added xxx packages 字样就说明成功了。

如果安装失败：可能是网络问题，可以尝试使用国内镜像：

1
npm install --registry=https://registry.npmmirror.com

1.4 验证安装

运行以下命令检查环境是否就绪：

1
npm run doctor

这是 Stellar 自带的环境检查工具。它会检查：

  • Node.js 版本是否兼容
  • 主题是否正确安装
  • 配置文件是否有语法错误
  • 集合登记是否完整
  • 页面字段是否有效
  • Widget 放置位置是否正确

如果看到绿色的 ✔ 和 Everything is OK，说明一切就绪。如果有 ✖（错误）或 ⚠（警告），请根据提示修复。Doctor 是您最好的朋友，遇到任何问题都应该先运行它。

1.5 启动本地预览

1
npm run server

这会启动一个本地服务器。当终端显示 Hexo is running at http://localhost:4000/ 时，打开浏览器访问这个地址，您应该能看到站点的首页。

任何时候想停止预览服务器：在终端按 Ctrl + C。

第二章 目录结构与文件职责

2.1 完整目录结构图

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
stellar-knowledge/                    # 项目根目录（您用终端打开的地方）
│
├── _config.yml                       # ★ 站点核心配置（标题、语言、网址、分页等）
├── _config.stellar.yml               # ★ 主题核心配置（外观、导航、侧栏、功能开关）
├── package.json                      # 依赖清单（一般不用手动修改）
│
├── source/                           # ★ 唯一的内容目录（您写的内容都放这里）
│   │
│   ├── _data/                        # ★ 登记数据（告诉系统有哪些专栏/知识库/笔记本）
│   │   ├── wiki.yml                  # 知识库书架清单（哪些知识库上架展示）
│   │   ├── wiki/                     # 每个知识库的描述文件
│   │   │   ├── site-handbook.yml     # 例如：建站手册的详细配置
│   │   │   └── knowledge-management.yml
│   │   ├── topic/                    # 每个专栏的描述文件
│   │   │   └── system-thinking.yml   # 例如：系统化整理专栏的配置
│   │   ├── notebooks/                # 每个笔记本的描述文件
│   │   │   └── reading-notes.yml     # 例如：阅读笔记的配置
│   │   └── widgets.yml               # （可选）自定义 Widget
│   │
│   ├── _posts/                       # ★ 文章目录（博客文章和专栏文章都放这里）
│   │   ├── hello-world.md            # 普通博客文章
│   │   └── system-01-intro.md        # 专栏文章（通过 Front Matter 归属到专栏）
│   │
│   ├── wiki/                         # ★ 知识库文档目录
│   │   └── site-handbook/            # 对应一个知识库项目（id 为 site-handbook）
│   │       ├── index.md              # 首页（通常是第一个页面）
│   │       ├── navigation.md         # 其他页面
│   │       └── publishing.md
│   │
│   ├── notebooks/                    # ★ 笔记本笔记目录
│   │   └── reading-notes/            # 对应一个笔记本（id 为 reading-notes）
│   │       ├── 2026-08-20-note-1.md
│   │       └── 2026-09-01-note-2.md
│   │
│   └── assets/                       # 图片等资源文件
│       ├── brand.webp                # 站点品牌图标
│       └── cover.webp                # 文章封面图
│
├── 文章模板/                         # ★ 写作模板库（复制粘贴用，不会被发布）
│   ├── 00-使用说明.md
│   ├── 01-博客普通文章模板.md
│   ├── 02-博客图片记录模板.md
│   ├── 03-博客专栏文章模板.md
│   ├── 04-Wiki知识库文档模板.md
│   └── 05-内容登记片段速查.md
│
└── public/                           # hexo generate 生成的网站文件（自动生成，不要手动修改）

2.2 核心规则（记住这三条就够了）

规则一：文件放在哪决定了它是什么

文件位置 内容类型 示例
source/_posts/*.md 博客文章或专栏文章 日常记录、系列教程
source/wiki/<项目名>/*.md 知识库文档 产品手册、使用指南
source/notebooks/<笔记本名>/*.md 笔记本笔记 读书笔记、学习摘录

规则二：文件名就是网址的一部分

文件位置 文件名 访问地址
source/_posts/my-post.md my-post /posts/my-post/
source/wiki/handbook/index.md index /wiki/handbook/index/
source/notebooks/reading/note-1.md note-1 /notebooks/reading/note-1/

⚠️ 极其重要：发布后不要再改文件名。一旦网站上线、有了访问量，改名会让旧链接失效，导致读者打不开页面。如果必须改名，需要在旧地址做重定向。

规则三：source/ 之外的文件都不会被发布

所以 文章模板/ 文件夹里的模板文件可以放心放，它们不会出现在您的网站上。同样的，根目录下的 使用与配置手册.md 也不会被发布。

2.3 数组配置与对象配置的合并规则

在 _config.stellar.yml 中，有两种不同的配置合并方式，理解这一点对修改配置非常重要：

配置类型 合并方式 示例 实际效果
数组（以- 开头的列表） 整体替换 menu: [A, B, C] 站点里只会显示 A、B、C，默认菜单完全消失
对象（键值对） 按层合并 features: { math: { provider: katex } } 只覆盖math 这一项，其他 features 保持默认

数组整体替换的示例：

_config.stellar.yml 中写了：

1
2
3
4
leftbar:
  menu:
    - { id: post, title: 近期发布, url: / }
    - { id: topic, title: 专栏, url: /topic/ }

那么菜单只有这两个项，主题默认菜单里的其他项全部消失。所以要新增菜单项时，必须把想保留的默认项也一起写进去。

对象按层合并的示例：

主题默认有：

1
2
3
4
features:
  reveal: { enabled: true }
  card_hover: { enabled: true }
  lightbox: { enabled: false }

_config.stellar.yml 中写了：

1
2
features:
  lightbox: { enabled: true }

最终结果是：

1
2
3
4
features:
  reveal: { enabled: true }    # 保留
  card_hover: { enabled: true } # 保留
  lightbox: { enabled: true }   # 被覆盖为 true

清空数组：用 [] 表示空数组。例如 widgets: [] 表示该区域不显示任何 Widget。

隐藏对象：用 null 表示置空。但不同位置对 null 的解读不同，有些是”隐藏”，有些是”继承默认值”，需要看具体字段说明。

第三章 站点配置完全参考

3.1 _config.yml —— 站点基本设置（Hexo 基础配置）

这是 Hexo 的基础配置文件，控制网站的”身份信息”和基础行为。带 ★ 的是您最常改的。

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
# ====== 站点身份信息 ======
title: P1neConeeのblog          # ★ 网站标题（显示在浏览器标签栏、顶栏和侧栏）
subtitle: 使用 Stellar 构建的真实场景  # ★ 网站副标题
author: 思远                    # ★ 默认作者名（如果文章 Front Matter 没写 author，就用这个）
language: zh-CN                # 语言（影响日期格式、UI 文字）
timezone: Asia/Shanghai        # 时区（影响日期显示）

# ====== 网址设置 ======
url: http://localhost:4000     # ★ 发布时改成您的真实域名（如 https://yourdomain.com）
root: /                        # 站点根路径（如果部署在子目录如 /blog/，就改成 /blog/）

# ====== 目录设置 ======
source_dir: source             # 源文件目录（一般不改）
public_dir: public             # 生成文件目录（一般不改）

# ====== 文章链接格式 ======
new_post_name: :title.md       # hexo new 命令创建文章时的命名格式
default_layout: post           # 默认布局
permalink: posts/:title/       # ★ 文章固定链接格式（:title = 文件名）
                               # 例如 my-post.md → /posts/my-post/

# ====== 日期格式 ======
date_format: YYYY-MM-DD        # 日期显示格式
updated_option: date           # 没写 updated 时沿用 date（而不是文件修改时间）

# ====== 分页设置 ======
per_page: 10                   # 归档/分类/标签等页面的每页条数
index_generator:               # 首页博客列表生成器
  path: ''                     # 首页路径
  per_page: 5                  # ★ 首页每页显示几篇文章
  order_by: -date              # 按日期倒序（最新在前）

# ====== 归档/分类/标签路由 ======
archive_dir: archives          # /archives/
category_dir: categories       # /categories/
tag_dir: tags                  # /tags/

# ====== 主题 ======
theme: stellar                 # 必须保持为 stellar，不要改

注意：Hexo 的自定义字段（如 highlight、deploy 等）与 Stellar 主题无关，按您的需求配置即可。Stellar 主题不读取 _config.yml 里的主题相关字段（那些在 _config.stellar.yml 里配置）。

什么时候需要改这个文件？

需求 改哪里
改网站标题 title
改网站作者 author
准备发布到互联网 url 改成真实域名
想调整首页文章数量 index_generator.per_page
部署到子目录 root 改成 /子目录名/

3.2 _config.stellar.yml —— 主题配置（完整注释版）

这是 Stellar 主题的配置文件，控制网站长什么样、导航栏有什么、侧栏显示什么、哪些功能开启。带 ★ 的是您最常改的。

主题的默认值位于 node_modules/hexo-theme-stellar/_config.yml，本站的 _config.stellar.yml 只写需要覆盖的项。也就是说，您在 _config.stellar.yml 里没写的配置项，会使用主题的默认值。

3.2.1 顶层分区一览

在开始逐项讲解前，先了解 _config.stellar.yml 的整体结构：

分区 管什么
topbar 顶部导航栏：是否显示、品牌标识、菜单项、Widget
leftbar 左侧边栏：品牌信息、主菜单
rightbar 右侧边栏（配置方式同 leftbar）
footer 页脚：底部链接分栏、版权信息
profiles 不同页面类型的专属配置：菜单高亮、左右栏 Widget
article 文章展示：列表摘要长度、标签显示、阅读时间、相关文章
notebook 笔记本：列表排序、标签图标
settings /settings/ 页面的关于信息
appearance 外观：预设风格、配色、字体、圆角、背景
search 站内搜索：local / algolia
comments 评论服务（默认关闭）
tags 标签插件默认行为：note 颜色、gallery 尺寸等
features 功能开关：深浅色切换、懒加载、灯箱、公式、图表
services 数据服务端点：评分、投票、GitHub 等
canonical 权威链接设置
open_graph Open Graph 元数据
structured_data 结构化数据（利于 SEO）
inject 自定义注入（head_end、body_end 等）

3.2.2 顶部导航栏（topbar）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
topbar:
  enabled: true                     # ★ 是否显示顶部栏（全站常驻，一般保持 true）
  brand:                            # 品牌标识区域
    image:                          # 品牌小图标
      src: /assets/brand.webp       # 图片路径
      variant: plain                # 可选：avatar（圆形）/ icon（方形）/ plain（普通）
    name: P1neConeeのblog           # ★ 顶栏显示的品牌名称
    href: /                         # 点击品牌图跳转的地址（通常是首页）
  menu:                             # ★ 顶栏快捷菜单（数组，整体替换）
    - { id: post, title: 首页, url: / }
    - { id: topic, title: 专栏, url: /topic/ }
    - { id: wiki, title: 知识库, url: /wiki/ }
    - { id: notebook, title: 笔记本, url: /notebooks/ }
    - { id: archives, title: 归档, url: /archives/ }
  widgets:                          # ★ 顶栏上的 Widget（顶栏专用）
    - menu                          # 渲染上面的菜单
    - spacer                        # 弹性占位（把后面的内容推到右边）
    - settings                      # 外观设置入口（深浅色切换）

关于 widgets 的说明：

  • 顶栏的 widgets 会从左到右依次渲染
  • menu 是特殊 Widget，它会把 topbar.menu 数组渲染成顶栏菜单
  • spacer 只存在于顶栏，作用是占据剩余空间，把后面的 Widget 推到右侧
  • settings 显示一个齿轮图标，点击后弹出外观设置面板（深浅色切换、字体等）

如果要新增顶栏菜单项：必须把现有菜单项全部写出来，再加上新的。因为数组是整体替换。

3.2.3 左侧边栏（leftbar）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
leftbar:
  brand:                            # 侧栏品牌区域（比顶栏更详细）
    name: P1neConeeのblog           # ★ 侧栏显示的品牌名
    tagline: 记录、连接并重新发现知识  # ★ 品牌标语
    image:                          # 品牌图标
      src: /assets/brand.webp
  menu:                             # ★ 主菜单（数组，整体替换默认菜单）
    - { id: post, title: 近期发布, icon: default:documents, url: /, accent: '#1BCDFC' }
    - { id: categories, title: 分类, icon: default:category, url: /categories/, accent: '#FFB300' }
    - { id: tags, title: 标签, icon: default:hashtag, url: /tags/, accent: '#E91E63' }
    - { id: topic, title: 专栏, icon: default:pin, url: /topic/, accent: '#F44336' }
    - { id: wiki, title: 知识库, icon: default:documents, url: /wiki/, accent: '#3DC550' }
    - { id: notebook, title: 笔记本, icon: default:calendar, url: /notebooks/, accent: '#26A69A' }
    - { id: archives, title: 归档, icon: default:calendar, url: /archives/, accent: '#7C4DFF' }
    - type: search                  # 底部搜索入口（type: search）

每个菜单项的字段含义：

字段 含义 示例
id 菜单唯一标识（kebab-case），用于和active_menu 配对 post、wiki
title 菜单显示文字 近期发布
icon 菜单图标（default:图标名 使用主题内置图标） default:documents
url 点击跳转的地址 /、/wiki/
accent 菜单项左侧的强调色 '#1BCDFC'
type 特殊类型（如search） search

菜单项 id 的作用：

  • 用于 profiles 中的 active_menu 配对——当用户访问某个页面时，对应的菜单项会高亮
  • 例如访问首页时，active_menu: post 会让 id 为 post 的菜单项高亮

如果不想显示某个菜单项：直接删除该行即可。注意数组是整体替换，所以删除后也不会从别处冒出来。

3.2.4 页脚（footer）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
footer:
  sections:                         # ★ 页脚链接分栏（数组，整体替换）
    - title: 浏览内容
      items:
        - { title: 近期发布, url: / }
        - { title: 专栏, url: /topic/ }
        - { title: 笔记本, url: /notebooks/ }
    - title: 查找资料
      items:
        - { title: 知识库, url: /wiki/ }
        - { title: 分类, url: /categories/ }
        - { title: 标签, url: /tags/ }
    - title: 历史记录
      items:
        - { title: 文章归档, url: /archives/ }
        - { title: 站点设置, url: /settings/ }

每个 section 是一列，items 是列中的链接列表。可以增删改任意列和链接。

3.2.5 页面类型配置（profiles）

这是 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
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
51
52
53
54
55
56
57
58
59
60
61
profiles:
  # 首页（文章列表）
  home:
    active_menu: post               # 高亮 id=post 的菜单项
    leftbar: { widgets: [] }        # 左侧不加额外组件（只保留菜单本身）
    rightbar: { widgets: [recent, tagcloud] }  # 右侧：最近更新 + 标签云

  # 博客文章列表页（/page/2/ 等）
  blog_index:
    active_menu: post
    leftbar: { widgets: [] }
    rightbar: { widgets: [recent, tagcloud] }

  # 文章详情页
  post:
    active_menu: post
    # leftbar 未覆盖 = 继承主题默认
    # rightbar 未覆盖 = 继承主题默认

  # 知识库首页（/wiki/ 项目墙）
  wiki_index:
    active_menu: wiki
    rightbar: { widgets: [tagcloud] }

  # 知识库文档页
  wiki:
    active_menu: wiki
    # 默认隐藏固定菜单，只留目录树

  # 笔记本总览页（/notebooks/）
  notebook_index:
    active_menu: notebook
    rightbar: { widgets: [tagcloud] }

  # 单本笔记本的笔记列表
  note_index:
    active_menu: notebook

  # 单条笔记详情
  note:
    active_menu: notebook

  # 专栏文章页
  topic:
    active_menu: topic

  # 作者页
  author:
    active_menu: post

  # 普通独立页（如 /about/）
  page:
    # 未覆盖 = 继承主题默认

  # 设置页
  settings:
    # 未覆盖 = 继承主题默认

  # 404 错误页
  error:
    # 未覆盖 = 继承主题默认

覆盖语义：

  • 省略某个配置项 = 继承主题默认值
  • widgets: [] = 该区域不显示任何 Widget（清空）
  • widgets: [a, b] = 只显示 a 和 b（整体替换）

注意：Wiki 内容页默认隐藏固定菜单（只留目录树），所以不要在 profiles.wiki 上设置指向隐藏菜单的 active_menu，否则会报错。

3.2.6 文章展示（article）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
article:
  # 列表卡片设置
  listing:
    show_tags: true                 # ★ 列表卡片是否显示标签
    excerpt_length: 120             # 没有手动写 description 时，自动截取正文前 N 个字作为摘要
    # show_cover: true              # （可选）是否显示封面图
    # show_categories: true         # （可选）是否显示分类

  # 文章详情页
  show_reading_time: true           # ★ 是否显示阅读时间
  # related_posts_limit: 0          # 相关文章数量（>0 需要安装 hexo-related-popular-posts 插件）

  # 文章页脚
  footer:
    # license: 本文采用 CC BY-NC-SA 4.0 许可协议。  # 版权声明
    # share: [wechat, link, system]                    # 分享按钮：微信/链接/系统分享；[]=隐藏

3.2.7 笔记本设置（notebook）

1
2
3
4
5
6
7
notebook:
  listing:
    order: date_desc                # ★ 笔记本列表的排序方式
                                    # date_desc = 最新创建在前
                                    # updated_desc = 最近更新在前
                                    # title_asc = 按标题 A-Z
  # tag_icon: hashtag               # 标签树的默认图标

3.2.8 设置页（settings）

1
2
3
4
5
6
7
8
settings:
  about:                            # /settings/ 页面的关于信息
    title: 关于本站
    description: |
      这是一个使用 Stellar 主题构建的知识库站点。
    # avatar: /assets/avatar.webp
    # social:
    #   - { name: GitHub, url: https://github.com/xxx, icon: brand:github }

3.2.9 外观（appearance）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
appearance:
  preset: card                      # ★ 内置风格预设
                                    # card = 卡片风格（默认）
                                    # glass = 毛玻璃风格
                                    # minimal = 极简风格
                                    # flat = 扁平风格
  color_scheme: auto                # ★ auto / light / dark
                                    # auto = 跟随系统
                                    # light = 强制浅色
                                    # dark = 强制深色
  # typography:                     # 排版设置
  #   content_align: left           # left / center / justify
  # background:                     # 背景设置（可自定义图片）
  #   image: /assets/bg.webp
  #   size: cover
  # radius:                         # 圆角大小
  #   default: 8px
  #   card: 12px

3.2.10 搜索（search）

1
2
3
4
5
6
7
8
9
10
11
search:
  provider: local                  # ★ local / algolia / null（null = 关闭搜索）
  local:
    scope: all                     # 索引范围：all（全部）/ post（仅文章）/ page（仅页面）
    include_content: true          # 是否索引正文内容
    # include_images: false        # 是否索引图片 alt 文字

  # algolia:                       # 如果使用 Algolia，配置在这里
  #   app_id: 你的 App ID
  #   api_key: 你的 API Key
  #   index_name: 你的索引名

什么时候用 Algolia：如果您的站点文章非常多（几百篇以上），本地搜索可能较慢，可以考虑使用 Algolia 提供的云搜索服务。

3.2.11 评论（comments）

1
2
3
4
5
6
7
8
9
10
11
12
13
comments:
  provider: null                   # ★ null = 关闭；支持 waline / twikoo / giscus / valine / utterances
  # 以下是各评论服务的配置示例（只配置用到的那个）：
  # waline:
  #   server_url: https://your-waline-server.vercel.app
  #   lang: zh-CN
  # twikoo:
  #   env_id: https://your-twikoo-server.vercel.app
  # giscus:
  #   repo: 用户名/仓库名
  #   repo_id: 你的 repo_id
  #   category: 分类名
  #   category_id: 你的 category_id

评论服务默认关闭。如果需要开启，选择一个服务并填写对应参数。

3.2.12 标签插件默认行为（tags）

1
2
3
4
5
6
7
tags:
  note:
    color: cyan                    # note 标签插件的默认颜色
  # gallery:                       # 图片画廊默认设置
  #   columns: 3
  #   gap: 8px
  #   rounded: true

3.2.13 功能开关（features）

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
features:
  # 深浅色切换
  color_scheme_switch: { enabled: true }   # ★ 允许用户手动切换深浅色

  # 滚动动画
  reveal: { enabled: true }                # 页面滚动时渐入动画

  # 卡片悬停
  card_hover: { enabled: true }            # 鼠标悬停卡片时的光效

  # 图片懒加载
  lazy_loading:
    enabled: false                         # 是否启用懒加载
    # transition: fade                     # 加载过渡效果：fade / blur / zoom

  # 图片灯箱
  lightbox:
    enabled: false                         # 点击图片放大查看

  # 数学公式
  math:
    enabled: false                         # 是否启用
    # provider: katex                      # katex / mathjax

  # 图表
  diagrams:
    enabled: false                         # 是否启用
    # provider: mermaid                    # 目前仅支持 mermaid

  # 中文排版优化
  heti:
    enabled: false                         # 中文排版优化（标题自动加空格等）

开启功能的步骤：

  1. 把 enabled: false 改成 enabled: true
  2. 对于 math 和 diagrams，还需要指定 provider
  3. 运行 npm run build 重新生成（首次开启可能需要安装额外依赖）

3.2.14 服务端点（services）

1
2
3
4
5
6
7
8
9
10
11
12
13
services:
  # 评分功能（需要对应的后端服务）
  # rating:
  #   url: https://your-api.com/rating
  #   key: your-api-key

  # 投票功能
  # vote:
  #   url: https://your-api.com/vote

  # GitHub 集成
  # github:
  #   token: your-github-token

这些通常用于高级功能，一般用户不需要配置。

3.2.15 SEO 相关

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
canonical:
  host: https://你的域名             # ★ 发布后建议设置，防止搜索引擎抓取到 localhost

open_graph:                         # Open Graph 元数据（社交分享用）
  # title: 默认标题
  # description: 默认描述
  # image: /assets/og-image.webp

structured_data:                    # 结构化数据（利于搜索引擎理解页面）
  # enabled: true

inject:                             # 自定义代码注入
  # head_begin: ''                 # 在 <head> 开头插入
  # head_end: ''                   # 在 </head> 之前插入
  # body_begin: ''                 # 在 <body> 开头插入
  # body_end: ''                   # 在 </body> 之前插入

3.3 修改配置后的生效步骤

每次修改了 _config.yml 或 _config.stellar.yml：

1
2
3
npm run clean      # 清理缓存（改了重要配置时建议执行）
npm run build      # 重新生成
npm run server     # 启动预览查看效果

第四章 Front Matter 完整参考

4.1 什么是 Front Matter

每篇 Markdown 文件最顶部的 --- 包围起来的部分，就是 Front Matter。它用 YAML 格式写，告诉系统这篇文章的标题、日期、分类、标签、归属等信息。

1
2
3
4
5
6
7
8
9
10
---
title: 我的文章标题          # 显示标题
date: 2026-09-08 10:00      # 发布日期
description: 一句话摘要       # 卡片和 SEO 用
tags:                       # 标签（列表格式）
  - 技术
  - 教程
---

这里是正文内容...

⚠️ 语法警告：Stellar 主题会对 Front Matter 字段做严格校验，写错字段或格式错误会导致构建报错。Doctor 命令会明确指出错误来源和修复方向。

4.2 字段完整速查表

字段 适用内容 类型 说明
title 全部 字符串 显示标题（不是网址，网址由文件名决定）
date 全部 YYYY-MM-DD HH:mm 发布日期
updated 全部 YYYY-MM-DD HH:mm 更新日期（可选，不写则沿用 date）
description 全部 字符串 摘要，用于列表卡片和 SEO meta
categories 博客文章 字符串列表 分类（建议用稳定的领域名：方法/工具/学习/思考/观察）
tags 全部 字符串列表 标签（笔记中可用/ 表示层级，如 阅读/方法）
cover 文章/笔记/集合 URL 字符串 列表卡片封面图，如/assets/cover.webp
permalink Wiki 页面 字符串 显式访问地址，必须与目录树中的 key 一致
collection 专栏文章/笔记本笔记 对象 声明归属：profile: topic/notebook + id: xxx
listing.priority 文章/专栏文章/笔记 非负整数 置顶，数字越大越靠前
excerpt 或 <!-- more --> 全部 字符串/注释 控制列表摘要，更推荐用description

4.3 各内容类型的 Front Matter 完整示例

普通博客文章

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: 我学到了一件事
date: 2026-09-08 09:00
description: 今天学到了一个重要的道理
categories:
  - 生活感悟
tags:
  - 成长
  - 反思
cover: /assets/cover.webp
listing:
  priority: 1                     # 置顶（可选）
---

专栏文章

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
title: 系统思考：边界与对象
date: 2026-09-05 09:00
description: 理解系统思考的第一步是界定边界
categories:
  - 方法论
tags:
  - 系统思考
cover: /assets/system-thinking.webp
collection:                       # ★ 关键：声明这是一篇专栏文章
  profile: topic
  id: system-thinking             # 对应 _data/topic/system-thinking.yml
listing:
  priority: 2                     # 置顶（可选）
---

Wiki 文档页

1
2
3
4
5
---
title: 导航结构说明
description: 本站的导航组织方式
permalink: wiki/site-handbook/navigation/   # ★ 必填，与目录树 key 一致
---

注意：Wiki 页面不需要写 date 和 tags（如果写了也不会被使用），归属由目录自动判定。

笔记本笔记

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
title: 如何做读书笔记
date: 2026-08-20 09:00
updated: 2026-09-01 21:00         # 可选，列表按 updated 排序
description: 一个实用的读书笔记方法
tags:                             # ★ 用 / 生成层级标签树
  - 阅读/方法
  - 工具/笔记法
cover: /assets/note-cover.webp    # 可选
collection:                       # ★ 关键：声明属于哪个笔记本
  profile: notebook
  id: reading-notes
listing:
  priority: 1                     # 置顶（可选）
---

4.4 官方文档有但需谨慎使用的字段

以下字段在官方文档（2.0.0-rc.2）中列出，但本站使用的是 alpha 版本，未必全部支持。想用时先写最小样例跑 npm run doctor，报错就按提示去掉或改写法：

字段 用途 风险等级
article.style 文章排版风格（tech/story） 中：部分支持
article.paragraph_indent 段落缩进 低：可能支持
banner.image / headline / tagline 页面横幅 高：alpha 可能不支持
footer.references 页脚参考文献 低：可能支持
footer.license 页脚版权声明 低：可能支持
footer.share 分享按钮 低：可能支持
comments.enabled 评论开关（页级覆盖） 中：可能支持
visibility.listed 是否在列表中显示 高：alpha 可能不支持
visibility.searchable 是否可被搜索 高：alpha 可能不支持
seo.open_graph SEO 元数据 中：可能支持
inject.head_end 代码注入 中：可能支持
article.ai_label AI 生成标注 高：较新概念，alpha 不支持

4.5 旧版字段禁区（写了必报错）

以下字段是 v1 版本的写法，在 v2 中已废弃，写了会导致构建报错：

  • 顶层 widgets:
  • 顶层 wiki:
  • navbar 卡片式写法
  • banner: 作为页面顶层字段（v1 写法）
  • 任何以 v1_ 开头的字段

如果您的文章是从旧站点迁移过来的，请务必删除或替换这些字段。

第五章 四类内容完全指南

5.1 四类内容对比总表

维度 博客文章 专栏 Topic 知识库 Wiki 笔记本 Notebook
文件位置 source/_posts/ source/_posts/ source/wiki/<id>/ source/notebooks/<id>/
需要登记 不需要 需要（_data/topic/<id>.yml） 需要（_data/wiki.yml + _data/wiki/<id>.yml） 需要（_data/notebooks/<id>.yml）
Front Matter 特殊字段 无 collection: {profile: topic, id: xxx} permalink: wiki/xxx/yyy/ collection: {profile: notebook, id: xxx}
展示方式 时间流列表 系列页面，按 date 排序 目录树，有上一篇/下一篇 笔记本列表 + 层级标签树
适合写什么 日常记录、随想、经验 系列教程、连载 产品文档、使用手册、FAQ 读书笔记、学习摘录、灵感

5.2 写一篇博客文章（最简单，从这开始）

场景：您想写一篇日常记录，不需要任何预先配置，写完就能看到。

步骤：

  1. 打开 文章模板/01-博客普通文章模板.md
  2. 全选复制内容
  3. 在 source/_posts/ 文件夹下新建一个文件，命名为 我的第一篇文章.md（文件名用英文或拼音，不要用中文）
  4. 粘贴内容，修改 Front Matter 和正文
  5. 删除所有带 【】 的提示
  6. 保存，运行 npm run build && npm run server 查看

Front Matter 示例：

1
2
3
4
5
6
7
8
9
10
---
title: 我的第一篇文章
date: 2026-09-08 10:00
description: 这是我开始写博客的第一天
categories:
  - 随笔
tags:
  - 开始
  - 博客
---

5.3 写一篇专栏文章（需要预先登记）

场景：您计划写一个系列，比如”系统思考入门”5 篇，希望读者能按顺序阅读，并且系列有一个专门的汇总页面。

步骤一：登记专栏

在 source/_data/topic/ 下创建 system-thinking.yml：

1
2
3
4
5
6
7
name: 系统思考入门
headline: 从零开始理解系统
description: 一个让你重新认识世界的方法论系列
route:
  start: system-01-intro          # 系列第一篇文章的文件名（不含 .md）
article:
  style: tech                     # 可选：tech（技术风格）/ story（故事风格）

步骤二：写文章

在 source/_posts/ 下写文章，Front Matter 中声明 collection：

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 什么是系统思考
date: 2026-09-01 09:00
description: 系统思考的核心概念
categories:
  - 方法论
tags:
  - 系统思考
collection:
  profile: topic
  id: system-thinking             # ← 对应刚才创建的 yml 文件名（不含 .yml）
---

步骤三：控制系列顺序

Stellar 按 date 字段排序。把日期按阅读顺序排列即可：

  • 第一篇：date: 2026-09-01 09:00
  • 第二篇：date: 2026-09-02 09:00
  • 第三篇：date: 2026-09-03 09:00

步骤四：查看效果

访问 /topic/system-thinking/ 可以看到专栏的汇总页，所有文章按顺序排列。访问专栏内的任意文章，底部会有上一篇/下一篇导航。

可选：限定上架文章

如果不想把所有带 collection 的文章都显示在专栏页，可以在 source/_data/topic.yml 中指定白名单：

1
2
3
4
# source/_data/topic.yml（如果有这个文件的话）
publish_list:
  - system-thinking
  - another-topic

不写这个文件 = 所有已登记的专栏全部显示。

5.4 写一个知识库 Wiki（适合做手册/文档）

场景：您想建一个像本手册一样的知识库，有目录树、有上一篇/下一篇导航、侧栏有固定的目录结构。

步骤一：登记知识库书架

在 source/_data/wiki.yml 中添加一行（这是书架，列出所有知识库）：

1
2
- site-handbook
- knowledge-management      # 添加您的知识库 id

步骤二：登记知识库详情

在 source/_data/wiki/ 下创建 knowledge-management.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
name: 知识管理体系
headline: 如何建立个人的知识系统
tagline: 从输入到输出
description: 一套完整的知识管理方法论
tags:
  - 知识管理
  - 方法论
audience: 所有希望建立知识体系的人
route:
  path: /wiki/knowledge-management/
navigation:
  tree:                     # ★ 目录树结构（决定侧栏显示顺序）
    入门篇:                  # 分组名称（侧栏显示为分组标题）
      - index               # 文件名，不含 .md
    方法篇:
      - capture
      - organize
      - review
    工具篇:
      - tools-overview
      - obsidian

步骤三：创建对应的文档文件

在 source/wiki/knowledge-management/ 文件夹下创建对应的 .md 文件：

  • index.md
  • capture.md
  • organize.md
  • review.md
  • tools-overview.md
  • obsidian.md

每个文件的 Front Matter 至少包含：

1
2
3
4
5
---
title: 页面标题
description: 页面描述
permalink: wiki/knowledge-management/index/   # 和目录树 key 对应
---

关于 permalink 的格式：

  • 格式为 wiki/<项目id>/<页面key>/
  • 页面 key 就是文件名（不含 .md），如 index、capture
  • 末尾的 / 不能省略

步骤四：配置项目首页

如果项目首页想使用特殊的 Hero 布局（带标题、副标题、背景图），可以在 _data/wiki/<id>.yml 中添加：

1
2
3
4
5
6
7
8
hero:
  enabled: true
  headline: 知识管理体系
  tagline: 从输入到输出
  description: 一套完整的知识管理方法论
  background:
    image: /assets/hero-bg.webp
    # effect: ferrofluid         # 动效类型（alpha 版本可能不支持）

注意：hero.effect 中的动效类型（ferrofluid/light-rays）属于较新版本的功能，本站 alpha 版本请以 Doctor 检测为准。

5.5 写一条笔记本笔记（适合碎片记录）

场景：您想记录各种零散的读书笔记、学习摘录、灵感碎片，并且按标签层级自动归类。笔记本非常适合”写的时候很快，找的时候很方便”的需求。

步骤一：登记笔记本

在 source/_data/notebooks/ 下创建 reading-notes.yml：

1
2
3
4
5
6
7
8
9
name: 阅读笔记
headline: 摘录、方法与回访
description: 一本书、一篇文章留下一条能被再次使用的笔记。
route:
  path: /notebooks/reading-notes/
listing:
  order: 1                      # 在笔记本列表页的排序（数字越小越靠前）
  per_page: 10                  # 每页显示笔记数（0=不分页，null=继承站点分页）
  sort: { field: updated, direction: desc }  # 按更新时间倒序

步骤二：写笔记

在 source/notebooks/reading-notes/ 下创建 .md 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title: 如何快速阅读一本书
date: 2026-08-20 10:00
updated: 2026-09-01 10:00
description: 快速阅读的核心是带着问题读
tags:                         # ★ 用 / 自动生成层级标签树
  - 阅读/方法
  - 阅读/速读
  - 工具/笔记法
collection:
  profile: notebook
  id: reading-notes
---
正文内容...

步骤三：查看标签树效果

如果有多条笔记使用了 阅读/方法、阅读/速读、阅读/精读 等标签，笔记本页面左侧会自动生成一个标签层级树：

1
2
3
4
5
6
📚 阅读
  ├── 方法 (3)
  ├── 速读 (2)
  └── 精读 (1)
🔧 工具
  └── 笔记法 (2)

点击任意标签，可以筛选出带有该标签的所有笔记。

CLI 快捷创建笔记（只认已登记的笔记本）：

1
2
3
4
5
# 先预览（--dry-run 只预览不实际创建）
npx hexo stellar new note --notebook reading-notes --title "我的新笔记" --tags "阅读/方法,工具" --dry-run

# 确认无误后去掉 --dry-run 真正创建
npx hexo stellar new note --notebook reading-notes --title "我的新笔记" --tags "阅读/方法,工具"

第六章 Collection 登记与导航

6.1 什么是 Collection

Collection 是 Stellar 中”需要登记的内容集合”的统称，包括：

  • 专栏（Topic）
  • 知识库（Wiki）
  • 笔记本（Notebook）

为什么需要登记：告诉系统”有这么一个项目”，以及它的名称、路径、目录结构等信息。不登记的话，写了文章也无法被组织到对应的项目页面中，npm run doctor 会报错。

6.2 各类型登记文件的位置

类型 书架清单 项目详情文件
专栏 不需要书架，直接在_data/topic/ 下创建 _data/topic/<id>.yml
知识库 _data/wiki.yml（列出所有项目 id） _data/wiki/<id>.yml
笔记本 不需要书架，直接在_data/notebooks/ 下创建 _data/notebooks/<id>.yml

6.3 知识库的完整登记示例

第一步：上架到书架（_data/wiki.yml）

1
2
3
- site-handbook          # 已有
- knowledge-management   # 新增，这一行就是把项目列到 /wiki/ 页面
- api-reference          # 再新增一个

第二步：创建项目详情（_data/wiki/knowledge-management.yml）

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
# ====== 基本信息 ======
name: 知识管理体系              # 卡片上显示的项目名
headline: 从零搭建个人知识系统    # 主标题
tagline: 让知识流动起来           # 副标题
description: 一套完整的知识管理方法论，涵盖捕获、整理、输出全流程。
tags:                          # 用于"相关项目"推荐
  - 知识管理
  - 方法论
audience: 所有希望建立知识体系的人  # 目标读者

# ====== 路由 ======
route:
  path: /wiki/knowledge-management/   # 项目访问路径

# ====== 目录树（最重要） ======
navigation:
  tree:
    入门篇:                         # 分组名称（侧栏显示为分组标题）
      - index                       # 文件名，对应 source/wiki/knowledge-management/index.md
    方法篇:
      - capture
      - organize
      - review
    工具篇:
      - tools-overview
      - obsidian
      - notion

第三步：创建对应的文档文件

在 source/wiki/knowledge-management/ 下创建：

  • index.md
  • capture.md
  • organize.md
  • review.md
  • tools-overview.md
  • obsidian.md
  • notion.md

每个文件的 Front Matter 必须包含 permalink 字段：

1
2
3
4
5
---
title: 知识管理概览
description: 这个项目的目标是什么
permalink: wiki/knowledge-management/index/
---

第四步：目录树的排序规则

navigation.tree 中分组的顺序 = 侧栏显示顺序。组内的页面顺序 = 侧栏显示顺序 = 「上一篇/下一篇」顺序。

项目首页通常是 index。如果没写 index，系统会自动把 tree 的第一个页面作为首页。

6.4 专栏的登记示例

source/_data/topic/system-thinking.yml：

1
2
3
4
5
6
7
8
name: 系统思考入门
headline: 从零开始理解系统
description: 一个让你重新认识世界的方法论系列
route:
  start: system-01-intro          # 系列第一篇文章的文件名
article:
  style: tech                     # 可选：tech（技术风格）/ story（故事风格）
# cover: /assets/topic-cover.webp  # 可选：专栏卡片封面

然后写文章放在 source/_posts/，Front Matter 中声明归属：

1
2
3
collection:
  profile: topic
  id: system-thinking

系列文章按 date 排序。如果希望完全自定义顺序，可以把日期按阅读顺序排列。

6.5 笔记本的登记示例

source/_data/notebooks/reading-notes.yml：

1
2
3
4
5
6
7
8
9
name: 阅读笔记
headline: 摘录、方法与回访
description: 一本书、一篇文章留下一条能被再次使用的笔记。
route:
  path: /notebooks/reading-notes/
listing:
  order: 1                       # 在笔记本列表页的排序
  per_page: 10                   # 每页显示笔记数
  sort: { field: updated, direction: desc }  # 按更新时间倒序

然后写笔记放在 source/notebooks/reading-notes/，Front Matter 中声明归属：

1
2
3
collection:
  profile: notebook
  id: reading-notes

6.6 关于 _data/ 文件夹的补充说明

_data/ 中的 YAML 文件会在构建时被加载，用于生成页面。修改后需要重新 npm run build 才能生效。

第七章 三栏布局与 Widget 完全指南

7.1 三栏布局结构

Stellar 的页面分为三个区域：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌─────────────────────────────────────────────────────────────────┐
│  TOPBAR（顶部导航栏，全站固定）                                  │
│  [品牌] [首页] [专栏] [知识库] [笔记本] [归档]  [⚙️]            │
├──────────────┬───────────────────────────┬─────────────────────┤
│              │                           │                     │
│  LEFT BAR    │   主内容区                │   RIGHT BAR         │
│  （左侧栏）   │   （文章/列表/文档）       │  （右侧栏）          │
│              │                           │                     │
│  [品牌]      │                           │  [目录]             │
│  [主菜单]    │                           │  [最近文章]         │
│  [搜索入口]   │                           │  [标签云]           │
│              │                           │                     │
├──────────────┴───────────────────────────┴─────────────────────┤
│  FOOTER（页脚，全站统一）                                       │
│  浏览内容  │  查找资料  │  历史记录                             │
└─────────────────────────────────────────────────────────────────┘

7.2 Widget 是什么

Widget 是填充在左右侧栏里的小组件。您可以在配置中引用它们的 id 来决定在什么页面显示哪些 Widget。

主题内置 Widget 完整列表

Widget id 布局 用途 主要参数
toc toc 当前文章的目录（根据标题自动生成） list_number、min_depth、max_depth、collapse
recent recent 最近更新的文章列表 limit（显示条数）、rss（RSS 链接）
related related 相关内容：专栏中显示系列文章，Wiki 中显示相关项目 无需参数
tree tree Wiki 目录树（高亮当前页面） 无需参数
tagtree tagtree 笔记本层级标签树（按/ 层级自动生成） expand_all、expand_active、show_tagcount
ghrepo ghrepo GitHub 仓库信息卡片（需配置source.repository） 无需参数
ghissues ghissues GitHub Issue 时间线 无需参数
ghuser ghuser GitHub 用户信息卡 无需参数
author author 作者信息卡（需_data/authors.yml） 无需参数
tagcloud tagcloud 标签云 min_font、max_font、amount、color、show_count
timeline timeline 数据时间线 api、type、user、limit
latest_comment timeline 最新评论（需接入评论服务 API） api、limit
menu 系统件 渲染该栏的菜单 无需参数（不要放进 widgets 数组）
settings 系统件 外观设置入口（深浅色切换等） 无需参数（不要放进 widgets 数组）
spacer 系统件 弹性占位，仅顶栏可用 无需参数
markdown markdown 自定义 Markdown 内容块（需在_data/widgets.yml 中定义） title、content
linklist linklist 自定义链接列表（需在_data/widgets.yml 中定义） title、view、items

放置矩阵（约）：

Widget 顶栏 左侧栏（内容区） 右侧栏（内容区）
menu ✅ 固定 ✅ 固定（不要写进 widgets） ❌
settings ✅ 固定 ❌ ❌
spacer ✅ ❌ ❌
toc ❌ ✅ ✅
tree ❌ ✅ ✅
tagtree ❌ ✅ ✅
recent ❌ ❌ ✅
related ❌ ❌ ✅
tagcloud ❌ ✅ ✅
author ❌ ✅ ✅
ghrepo ❌ ✅ ✅
ghissues ❌ ✅ ✅
ghuser ❌ ✅ ✅
timeline ❌ ✅ ✅
latest_comment ❌ ✅ ✅
markdown ❌ ✅ ✅
linklist ❌ ✅ ✅

⚠️ 警告：menu 和 settings 是固定区域组件，不要写在 leftbar.widgets 或 topbar.widgets 里。写了会被跳过并在 Doctor 报告中提示警告。

7.3 如何配置侧栏 Widget

在 _config.stellar.yml 的 profiles 中，为不同页面类型配置左右栏：

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
profiles:
  # 首页
  home:
    rightbar: { widgets: [recent, tagcloud] }   # 右侧显示最近文章 + 标签云
    leftbar: { widgets: [] }                    # 左侧不加额外组件（只保留菜单本身）

  # 文章详情页
  post:
    rightbar: { widgets: [toc, related, recent] }   # 显示目录 + 相关内容 + 最近文章
    # leftbar 未配置 = 继承主题默认

  # 知识库文档页
  wiki:
    rightbar: { widgets: [tree, toc] }           # 显示目录树 + 本文目录
    leftbar: { widgets: [tree] }                 # 左侧也显示目录树（配合隐藏固定菜单）

  # 笔记本页面
  note:
    rightbar: { widgets: [tagtree, recent] }     # 显示标签树 + 最近文章
    leftbar: { widgets: [tagtree] }              # 左侧也显示标签树

  # 知识库首页（/wiki/ 项目墙）
  wiki_index:
    rightbar: { widgets: [tagcloud] }

  # 笔记本总览页（/notebooks/）
  notebook_index:
    rightbar: { widgets: [tagcloud] }

7.4 Widget 详细配置说明

toc（文章目录）

1
2
3
4
5
6
widgets:
  - id: toc                        # 可以省略 id，直接用名称
    list_number: true              # 是否显示编号（1. 2. 3.）
    min_depth: 2                   # 从几级标题开始捕获（1-6）
    max_depth: 4                   # 捕获到几级标题为止
    collapse: false                # 是否默认折叠子目录

recent（最近文章）

1
2
3
4
widgets:
  - id: recent
    limit: 10                      # 显示最近 10 篇
    rss: /atom.xml                 # RSS 链接（如果有的话）

tagcloud（标签云）

1
2
3
4
5
6
7
widgets:
  - id: tagcloud
    min_font: 14                   # 最小字号
    max_font: 28                   # 最大字号
    amount: 50                     # 显示标签数量
    color: true                    # 是否使用彩色
    show_count: true               # 是否显示标签使用次数

tagtree（笔记本标签树）

1
2
3
4
5
widgets:
  - id: tagtree
    expand_all: false              # 是否全部展开
    expand_active: true            # 是否展开当前标签所在的路径
    show_tagcount: true            # 是否显示标签下的笔记数量

7.5 自定义 Widget

如果内置 Widget 不够用，可以在 source/_data/widgets.yml 中自定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# source/_data/widgets.yml

# 自定义 Markdown 卡片
welcome:
  layout: markdown
  title: 欢迎来到本站
  content: |
    **欢迎。** 这里记录了我的学习与思考。
  
    更多入口请见左侧菜单。

# 自定义链接列表
my_links:
  layout: linklist
  title: 常用入口
  view: list                    # list / grid
  items:
    - { title: 官方文档, url: https://xaoxuu.com/wiki/stellar/ }
    - { title: GitHub 仓库, url: https://github.com/ }
    - { title: 关于本站, url: /about/ }

然后在 profiles 的 widgets 中引用：

1
2
3
profiles:
  home:
    rightbar: { widgets: [welcome, recent, my_links] }

自定义 Widget 的布局类型：

layout 用途 必需参数
markdown 渲染 Markdown 内容 title、content
linklist 链接列表 title、items（每个 item 有 title 和 url）

7.6 常见布局调整场景

场景一：首页右侧不想显示任何东西

1
2
3
profiles:
  home:
    rightbar: { widgets: [] }

场景二：所有文章页面右侧只显示目录

1
2
3
profiles:
  post:
    rightbar: { widgets: [toc] }

场景三：知识库页面左侧显示目录树，右侧显示当前页目录

1
2
3
4
profiles:
  wiki:
    leftbar: { widgets: [tree] }
    rightbar: { widgets: [toc] }

场景四：笔记本页面左侧显示标签树，右侧显示最近笔记

1
2
3
4
profiles:
  note:
    leftbar: { widgets: [tagtree] }
    rightbar: { widgets: [recent] }

场景五：顶栏加一个自定义链接

1
2
3
4
5
6
7
8
topbar:
  menu:
    - { id: post, title: 首页, url: / }
    - { id: topic, title: 专栏, url: /topic/ }
    - { id: wiki, title: 知识库, url: /wiki/ }
    - { id: notebook, title: 笔记本, url: /notebooks/ }
    - { id: archives, title: 归档, url: /archives/ }
    - { id: about, title: 关于, url: /about/ }   # 新增

第八章 标签插件速查大全

8.1 什么是标签插件

标签插件是 Stellar 提供的 Markdown 扩展语法，让您能在文章里插入各种样式丰富的内容块，比如提示框、折叠面板、标签、时间线、图库等。

基本语法：

1
{% 插件名 参数1 参数2 键:值 文本内容 %}
  • 参数用空格分隔
  • 键:值 形式的是命名参数
  • 最后的文本参数会吸收剩余所有内容
  • 多行内容用成对标签：{% 插件名 %}…{% end插件名 %}

8.2 全部标签插件速查表

插件名 用途 示例
note 提示框/警告框/信息框 {% note color:cyan 提示 %}内容{% endnote %}
box 带标题的文本框 {% box color:green 标题 %}内容{% endbox %}
folding 折叠面板 {% folding color:cyan open:false 标题 %}内容{% endfolding %}
mark 高亮文字 {% mark 高亮词 color:cyan %}
hashtag 可点击的标签链接 {% hashtag 知识管理 /wiki/ color:blue %}
copy 可复制文本 {% copy 可复制的内容 %}
checkbox 复选框 {% checkbox checked:true color:green 已完成 %}
button 按钮 {% button 文本 url:https://example.com %}
link 带图标的外部链接 {% link 文本 url:https://example.com %}
quote / quot 引用块 {% quot 内容 author:作者 %}
poetry 诗歌格式 {% poetry %}内容{% endpoetry %}
image 图片（带标题/对齐） {% image /assets/img.webp title:图片标题 align:center %}
gallery 图片画廊 {% gallery %}图片列表{% endgallery %}
video 视频嵌入 {% video https://example.com/video.mp4 %}
audio 音频嵌入 {% audio https://example.com/audio.mp3 %}
timeline 时间线 {% timeline %}<!-- node 标题 -->内容{% endtimeline %}
tabs 标签页 {% tabs %}<!-- tab 标题 -->内容{% endtabs %}
grid 网格布局 {% grid bg:card w:220px gap:16px %}<!-- cell -->内容{% endgrid %}
table 增强表格 {% table %}表格内容{% endtable %}
chat 对话气泡 {% chat %}对话内容{% endchat %}
dropdown 下拉选择 {% dropdown 选项1,选项2 %}
swiper 轮播图 {% swiper %}图片列表{% endswiper %}
icon / emoji 图标/表情 {% icon brand:github %} / {% emoji 😄 %}
copy 一键复制 已在上方列出

8.3 最常用标签插件详细示例

提示框（Note）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{% note color:cyan 提示 %}
这是一个提示框的内容。
{% endnote %}

{% note color:red 警告 %}
这是一个警告框。
{% endnote %}

{% note color:green 成功 %}
操作成功完成。
{% endnote %}

{% note color:orange 注意 %}
这是一个需要注意的事项。
{% endnote %}

{% note color:blue 信息 %}
这是一条中性信息。
{% endnote %}

{% note color:purple 引用 %}
这是一段引用内容。
{% endnote %}

支持的颜色：red / orange / yellow / green / cyan / blue / purple

折叠面板（Folding）

1
2
3
4
5
6
7
8
{% folding color:cyan open:false 点击展开查看详情 %}
这里是折叠起来的内容，点击上方标题才会展开。
可以包含多行内容，甚至其他标签插件。
{% endfolding %}

{% folding color:green open:true 默认展开的折叠 %}
这个面板一打开就是展开状态。
{% endfolding %}
  • open:true = 默认展开
  • open:false = 默认折叠（默认值）

文本框（Box）

1
2
3
4
5
6
7
{% box color:green 核心观点 %}
这是带标题的文本框，适合突出核心内容。
{% endbox %}

{% box color:yellow 注意事项 %}
一个引人注意的框。
{% endbox %}

高亮文字（Mark）

1
这篇文章的核心是 {% mark 知识管理 color:cyan %} 这个概念。

可点击标签（Hashtag）

1
{% hashtag 知识管理 /wiki/knowledge-management/ color:blue %}

生成一个样式像标签、点击跳转到指定 URL 的链接。

复制按钮（Copy）

1
{% copy 这是一段可以一键复制的文本 %}

在页面中显示一个带复制按钮的文本框。

复选框（Checkbox）

1
2
3
{% checkbox checked:true color:green 已完成的任务 %}
{% checkbox checked:false color:orange 未完成的任务 %}
{% checkbox checked:true color:blue 默认蓝色复选框 %}

按钮（Button）

1
2
{% button 查看文档 url:https://example.com %}
{% button 下载文件 url:/assets/file.pdf icon:download %}

引用块（Quote）

1
{% quot 知识就是力量 author:培根 %}

图片（Image）

1
{% image /assets/cover.webp title:封面图 align:center %}
  • title：图片标题（显示在下方）
  • align：对齐方式（left / center / right）

画廊（Gallery）

1
2
3
4
5
{% gallery %}
/assets/photo1.webp
/assets/photo2.webp
/assets/photo3.webp
{% endgallery %}

时间线（Timeline）

1
2
3
4
5
6
7
8
{% timeline %}
<!-- node 2026年9月 -->
- 9月8日：完成了第一篇博客
- 9月5日：开始学习 Stellar
<!-- node 2026年8月 -->
- 8月20日：安装了开发环境
- 8月15日：决定开始写博客
{% endtimeline %}

<!-- node 标题 --> 是分组标记，后面的内容属于该分组。

标签页（Tabs）

1
2
3
4
5
6
7
8
{% tabs %}
<!-- tab 方法一 -->
内容一：这是第一种方法的说明。
<!-- tab 方法二 -->
内容二：这是第二种方法的说明。
<!-- tab 方法三 -->
内容三：这是第三种方法的说明。
{% endtabs %}

网格布局（Grid）

1
2
3
4
5
6
7
8
{% grid bg:card w:220px gap:16px %}
<!-- cell -->
第一个卡片内容
<!-- cell -->
第二个卡片内容
<!-- cell -->
第三个卡片内容
{% endgrid %}
  • bg:card：背景样式（card / transparent / color:xxx）
  • w:220px：每个格子的宽度
  • gap:16px：格子间距

视频/音频

1
2
3
{% video https://example.com/video.mp4 %}

{% audio https://example.com/audio.mp3 %}

8.4 分组容器的使用技巧

对于 timeline、tabs、grid 这类有多个子块的分组容器：

  • 用 <!-- tab 标题 --> 或 <!-- node 标题 --> 或 <!-- cell --> 作为分隔
  • 这些注释必须单独占一行
  • 标题是显示在界面上的，不是 HTML 注释

8.5 展示源码的方法

如果想在文章中展示标签插件的源码（而不是执行它），把示例放进 ``` 围栏代码块中：

1
2
3
4
5
```markdown
{% note color:cyan 提示 %}
这是一个提示框的源码示例。
{% endnote %}
```

8.6 标签插件使用原则

  1. 适度使用：标签插件是为了增强内容可读性，不是为了炫技。每篇文章使用 3-5 个不同类型足矣。
  2. 颜色统一：同一种类型的信息尽量使用同一种颜色（比如所有提示都用 cyan，所有警告都用 red）。
  3. 移动端兼容：避免嵌套过深（比如 folding 里再套 tabs），在手机上可能显示不全。
  4. 先测试后铺开：不确定某个标签插件是否可用时，先在本地写一篇测试文章，跑 npm run doctor 确认无报错。

第九章 功能开关速查

9.1 功能开关总表

功能 配置位置 默认状态 开启后的效果
深浅色切换 features.color_scheme_switch.enabled 开启 用户可手动切换深浅色模式
滚动渐入动画 features.reveal.enabled 开启 页面滚动时元素渐入
卡片悬停光效 features.card_hover.enabled 开启 鼠标悬停卡片时有光效
图片懒加载 features.lazy_loading.enabled 关闭 滚动到图片时才加载
图片灯箱 features.lightbox.enabled 关闭 点击图片放大查看
数学公式 features.math.enabled + provider 关闭 支持 KaTeX/MathJax 公式
图表（Mermaid） features.diagrams.enabled + provider 关闭 支持 Mermaid 流程图
中文排版优化 features.heti.enabled 关闭 标题自动加空格等
站内搜索 search.provider local 搜索框可搜索全站内容
评论 comments.provider null（关闭） 文章底部显示评论区域
分享按钮 article.footer.share 空数组（隐藏） 文章底部显示分享按钮
相关文章 article.related_posts_limit 0（关闭） 文章底部显示相关推荐

9.2 各功能详细配置

深浅色切换

1
2
3
4
5
features:
  color_scheme_switch: { enabled: true }

appearance:
  color_scheme: auto              # auto（跟随系统）/ light（强制浅色）/ dark（强制深色）

如果 color_scheme_switch.enabled: true，用户可以通过顶栏的 settings 按钮手动切换。如果设为 false，则使用 appearance.color_scheme 的固定值。

图片懒加载

1
2
3
4
features:
  lazy_loading:
    enabled: true
    transition: fade              # fade / blur / zoom

图片灯箱

1
2
3
features:
  lightbox:
    enabled: true

数学公式

1
2
3
4
features:
  math:
    enabled: true
    provider: katex               # katex / mathjax

开启后，在文章中用 $$ 或 \( \) 包裹的公式会被渲染。

图表（Mermaid）

1
2
3
4
features:
  diagrams:
    enabled: true
    provider: mermaid             # 目前仅支持 mermaid

开启后，在文章中用 ```mermaid 代码块包裹的图表会被渲染。

中文排版优化

1
2
3
features:
  heti:
    enabled: true

开启后，中文标题与英文之间会自动加空格，优化中文排版。

站内搜索

1
2
3
4
5
search:
  provider: local                 # local / algolia / null（null=关闭）
  local:
    scope: all                    # all（全站）/ post（仅文章）/ page（仅页面）
    include_content: true         # 是否索引正文

评论

1
2
3
4
5
6
comments:
  provider: waline                # waline / twikoo / giscus / valine / utterances
  waline:
    server_url: https://your-waline-server.vercel.app
    lang: zh-CN
  # 只用配置您选择的那个服务

分享按钮

1
2
3
4
article:
  footer:
    share: [wechat, link, system]   # wechat（微信）/ link（复制链接）/ system（系统分享）
    # [] = 隐藏所有分享按钮

相关文章

1
2
article:
  related_posts_limit: 5          # 显示 5 篇相关文章

注意：开启此功能需要安装 hexo-related-popular-posts 插件：

1
npm install hexo-related-popular-posts --save

9.3 功能开启后的验证步骤

  1. 修改 _config.stellar.yml
  2. 运行 npm run doctor（检查配置是否正确）
  3. 运行 npm run build（重新生成）
  4. 运行 npm run server（预览测试）
  5. 打开对应页面，验证功能是否生效

如果功能没有生效，检查：

  • 是否安装了必需的依赖（如数学公式需要 katex 或 mathjax 包）
  • 配置的语法是否正确（冒号后有空格，缩进正确）
  • 运行 npm run doctor 看是否有报错

第十章 命令与日常工作流

10.1 命令速查表

1
2
3
4
npm run doctor        # ★ 最重要的命令：检查配置和内容是否有问题
npm run clean         # 清理缓存（遇到奇怪问题时执行）
npm run build         # 生成网站文件到 public/ 目录
npm run server        # 启动本地预览（http://localhost:4000/）

命令详解：

命令 作用 什么时候用
npm run doctor Stellar 环境检查：校验配置、集合登记、页面字段、Widget 位置 每次修改配置或新增内容后
npm run clean 删除db.json 和 public/ 文件夹 遇到奇怪的构建问题，或改了重要配置
npm run build 执行hexo generate，生成完整的网站文件 每次修改内容或配置后，想看到更新
npm run server 启动本地预览服务器 想在浏览器中查看效果

Doctor 的退出码：

  • 有 ✖ 错误（issues）→ 退出码 1（构建会失败）
  • 只有 ⚠ 警告（warnings）→ 退出码 0（构建仍可通过）
  • 全部通过 → 退出码 0

Doctor 也支持结构化输出（用于脚本分析）：

1
2
npx hexo stellar doctor --format json     # 输出 JSON 格式
npx hexo stellar doctor --format json --silent  # 不输出人类可读的日志

10.2 推荐日常工作流

写一篇新内容时的完整流程

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
1. 选模板
   ↓
   打开 文章模板/ 文件夹，选择对应的模板文件
   （01=博客文章，03=专栏文章，04=Wiki文档）
   
2. 复制到正确位置
   ↓
   根据内容类型，复制到 source/_posts/ 或 source/wiki/<id>/ 或 source/notebooks/<id>/
   
3. 修改 Front Matter
   ↓
   按模板里的说明填写 title、date、description 等
   注意：删除所有【】占位符
   
4. 写正文
   ↓
   用 Markdown 和标签插件写内容
   
5. 运行 Doctor
   ↓
   npm run doctor
   如果有错误，根据提示修复
   
6. 构建并预览
   ↓
   npm run build && npm run server
   在浏览器中检查：列表摘要、目录树、上下篇、图片、链接、搜索
   
7. 确认无误
   ↓
   提交代码 / 部署到服务器

日常维护流程

1
2
3
4
5
6
7
8
9
10
# 每次修改配置或内容后的标准流程：
npm run doctor      # 检查
npm run build       # 生成
npm run server      # 预览

# 遇到奇怪问题时：
npm run clean       # 清理缓存
npm run doctor      # 再次检查
npm run build       # 重新生成
npm run server      # 重新预览

10.3 高级 CLI 命令

Stellar 提供了 stellar 子命令，用于快速创建笔记本笔记：

1
2
3
4
5
# 创建笔记本笔记
npx hexo stellar new note --notebook reading-notes --title "我的新笔记" --tags "阅读/方法,工具"

# 先预览（不实际创建）
npx hexo stellar new note --notebook reading-notes --title "我的新笔记" --tags "阅读/方法,工具" --dry-run

注意：--notebook 后面的 id 必须在 _data/notebooks/ 中已经登记。

10.4 命令常见问题

问题 原因 解决方法
doctor 报错但不知道错在哪 报错信息里有path 和行号 定位到具体文件，对照报错提示修改
build 报错 YAMLException Front Matter 的冒号后面没加空格，或用了中文冒号 检查--- 之间的 YAML 语法
server 启动后看不到更新 缓存没清理 npm run clean → npm run build → npm run server
端口 4000 被占用 另一个程序占用了 4000 端口 npm run server -- --port 4001 换端口

第十一章 版本说明与避坑指南

11.1 当前版本

  • 本站安装：Stellar v2.0.0-alpha.1
  • 官方文档当前：2.0.0-rc.2
  • npm 上 latest 标签：1.x（最新为 1.44.0）

版本差异说明：

版本 状态 说明
1.x 稳定版 大量老教程使用此版本，配置与 v2 不通用
2.0.0-alpha.1 本站使用 早期测试版，核心功能稳定，部分新功能未加入
2.0.0-rc.2 官方文档版本 接近正式版，新增了一些字段和功能

11.2 v1 到 v2 的破坏性变更

如果您从 1.x 版本迁移过来，以下写法在 v2 中已经废弃：

v1 写法 v2 正确写法 说明
顶层widgets: 在profiles 中配置 leftbar.widgets / rightbar.widgets Widget 配置位置变了
顶层wiki: 在_data/wiki.yml 和 _data/wiki/<id>.yml 中配置 Wiki 配置移到 _data 文件夹
navbar 卡片式写法 使用profiles 或 appearance 配置 导航配置重组
banner: 作为页面顶层字段 在 Wiki 中使用hero: Banner 改名并功能增强
v1_* 开头的字段 删除或替换 旧字段已移除

11.3 alpha 版本需要注意的字段

以下字段在官方文档（rc.2）中有说明，但在本站 alpha 版本中可能不完全支持：

字段 状态 建议
hero.effect（ferrofluid/light-rays） 可能不支持 写测试页跑 doctor 验证
article.ai_label 不支持 不要使用
visibility.listed / visibility.searchable 可能不支持 测试后再用
article.style 的某些值 部分支持 测试后使用
评论服务的某些参数 部分支持 测试后使用

安全做法：想用任何未在本文档中明确列出的字段时，先写最小测试样例，跑 npm run doctor，确认无报错后再使用。

11.4 老教程陷阱警示

网上的 Hexo + Stellar 教程大量是 1.x 版本的写法。如果您参考了这些教程，请注意以下”雷区”：

  1. widgets: 顶层配置 → v2 中已移到 profiles 下
  2. wiki: 顶层字段 → v2 中已移到 _data/wiki.yml
  3. navbar 相关的卡片配置 → v2 中结构已变
  4. banner: 字段 → v2 中改为 hero:（仅限 Wiki）

如何判断教程是否适合您：

  • 教程中提到 _config.stellar.yml 是主题配置文件 → 适合 v2
  • 教程中使用 npm install hexo-theme-stellar@latest → 可能安装的是 1.x（因为 npm latest 还是 1.x）
  • 教程中提到 _config.yml 中写 stellar_xxx 字段 → 那是 1.x 的写法

11.5 升级主题前的准备

如果要升级主题版本（从 alpha 到 rc，或从 rc 到正式版）：

  1. 备份当前站点（复制整个文件夹）
  2. 阅读官方迁移指南：https://xaoxuu.com/wiki/stellar/migration/v1-to-v2/
  3. 在本地测试：不要在生产环境直接升级
  4. 运行 npm run doctor 确认无问题
  5. 逐个检查新版本新增的配置项，看是否需要调整

11.6 遇到报错的终极排查流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
遇到报错
    ↓
第一步：看报错信息本身
    ↓
红色文字通常会告诉您：哪个文件、第几行、什么错误
    ↓
第二步：运行 npm run doctor
    ↓
Doctor 会给出结构化的错误/警告列表
    ↓
第三步：根据 Doctor 提示修复
    ↓
修复后再次运行 doctor 确认
    ↓
如果仍有问题：查看本手册对应章节
    ↓
如果仍未解决：查看官方文档对应章节
    ↓
如果仍未解决：搜索 GitHub Issues 或社区讨论

附录：与「文章模板」体系的对应关系

您想做的事 用哪个文件
决定内容该放哪、用哪份模板 文章模板/00-使用说明.md
写普通博客文章 文章模板/01-博客普通文章模板.md
写图片/视觉记录 文章模板/02-博客图片记录模板.md
写专栏系列文章 文章模板/03-博客专栏文章模板.md
写 Wiki 文档（含三步登记提醒） 文章模板/04-Wiki知识库文档模板.md
新建/修改集合登记（_data 粘贴片段） 文章模板/05-内容登记片段速查.md
配置为什么这样写、还能怎么改 本手册（当前文件）
标签插件细节与示例 本手册第八章 + 站内/wiki/site-handbook/tag-plugins/
快速复制一份内容开始写 文章模板/ 下的所有模板文件

最小闭环示例：

  • 新加一篇普通博客：模板 01 → 复制为 source/_posts/new-post.md → 改 Front Matter/正文 → doctor → server → 完成
  • 新加一篇 Wiki 文档：模板 04 → 复制到 source/wiki/site-handbook/ → 改 permalink → 在 _data/wiki/site-handbook.yml 的 tree 分组加一行文件名 → doctor → 从左侧目录进入检查

索引

按关键词索引

关键词 相关章节
Front Matter 第四章
博客文章 第五章 5.2
专栏 Topic 第五章 5.3，第六章 6.4
知识库 Wiki 第五章 5.4，第六章 6.3
笔记本 Notebook 第五章 5.5，第六章 6.5
Widget 第七章
标签插件 第八章
评论 第九章 9.2
搜索 第九章 9.2
数学公式 第九章 9.2
深浅色 第九章 9.2
目录结构 第二章
配置 第三章
命令 第十章
版本 第十一章

本手册基于本站 v2.0.0-alpha.1 编写，覆盖官方文档全部配置项与功能点，按场景重新组织。如有冲突，以 npm run doctor 的本地校验为准。

额外遇到的问题

Hexo + Typora 的融合方法

这是_post类文章解决方式

1.在 Hexo 根目录打开配置文件 _config.yml

搜索 post_asset_folder，false 改为 true

2.Typora图片偏好设置中 复制到指定路径，然后默认就行

但是又发现笔记本等其他位置用不了相对路径，因为插件的问题

参考这篇文章

https://cloud.tencent.com/developer/article/1970544?policyId=1003

把这篇文章交给dsh，自动帮我们装了个js插件解决问题，太强了ai

上传完404

去仓库-setting-pages-branch选master即可

GitHub更新不显示（暨网站更新流程）

没删除缓存，以后的逻辑是

npm run clean

npm run build

hexo g

hexo d

总之，根据文档上方方案走

stellar主题建站Github
许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

站内搜索

没有找到内容！