官方文档：https://xaoxuu.com/wiki/stellar/
主题版本：Stellar 1.33.1

一、Front-matter 字段

1.1 Hexo 内置字段

字段 描述 默认值
layout 布局 post
title 标题 文件名
date 建立日期 文件建立日期
updated 更新日期 文件更新日期
sticky 置顶（数字越大越靠前） -
comments 开启评论功能 true
tags 标签 -
categories 分类 -
permalink 覆盖永久链接 null
excerpt 纯文本摘要 -
lang 设置语言 继承自 _config.yml

1.2 Stellar 特有字段

字段 描述 可用版本
type 页面类型：tech（技术文）或 story（图文） -
poster 封面信息：topic/headline/caption/color -
banner 顶部横幅背景 -
banner_info 横幅信息：avatar/title/subtitle -
indent 段落缩进 false
topic 所属话题/专栏 1.25+
author 文章作者 1.23+
menu_id 高亮的菜单按钮 id -
leftbar 左侧边栏配置 1.27+
rightbar 右侧边栏配置 1.27+
indexing 页面是否可被搜索 true
references 参考资料列表 -
h1 页内标题 1.26+
comment_title 评论区标题 -
wiki 该页面所属的 wiki 项目 -

1.3 封面与摘要

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 文章封面（Stellar v1.14+ 推荐使用 poster）
poster:
  topic: 标题上方小字
  headline: 大标题
  caption: 标题下方小字
  color: 标题颜色

# 手动摘要（<!-- more --> 之前为摘要）
正文内容...

<!-- more -->

正文（主页不显示）...

# 自动摘要（在 _config.stellar.yml 中设置）
article:
  auto_excerpt: 200

二、表达类标签组件（33+ 个）

2.1 emoji 表情包

1
{% emoji [source] name [height:1.75em] %}

表情速查表：https://weekdaycare.cn/posts/emoji-blob/

配置示例（_config.stellar.yml）：

1
2
3
4
5
6
tag_plugins:
  emoji:
    default: https://gcore.jsdelivr.net/gh/cdn-x/emoticons/qq/{name}.gif
    twemoji: https://gcore.jsdelivr.net/gh/twitter/twemoji/assets/svg/{name}.svg
    qq: https://gcore.jsdelivr.net/gh/cdn-x/emoticons/qq/{name}.gif
    tieba: https://gcore.jsdelivr.net/gh/cdn-x/emoticons/tieba/{name}.png

2.2 icon 图标

1
2
3
4
{% icon solar:planet-bold-duotone %}                    <!-- 图标集 -->
{% icon https://api.iconify.design/solar:link.svg %}    <!-- 外链 -->
{% icon ph:seal-question-fill color:red %}              <!-- 指定颜色 -->
{% icon https://xxx.svg style:transform:scale(1.2) %}  <!-- 自定义样式 -->

图标库：https://icon-sets.iconify.design/
推荐图标集：solar、ph、mdi、bi

配置默认颜色：

1
2
3
tag_plugins:
  icon:
    default_color: accent

2.3 vote 投票

需要自部署 star-vote（1.33.0+）

1
2
{% vote id:default 你的问题？ %}
{% vote id:default yes:solar:round-double-alt-arrow-up-bold no:solar:round-double-alt-arrow-down-bold 自定义图标 %}

2.4 rating 评分

需要自部署 star-vote（1.33.0+）

1
2
{% rating id:default 给这篇文章打分吧～ %}
{% rating id:default icon:https://api.iconify.design/twemoji:star-struck.svg 自定义图标 %}

2.5 mark 标记（12 色）

1
2
3
4
5
6
7
8
9
10
11
12
{% mark 默认 %}
{% mark 红 color:red %}
{% mark 橙 color:orange %}
{% mark 黄 color:yellow %}
{% mark 绿 color:green %}
{% mark 青 color:cyan %}
{% mark 蓝 color:blue %}
{% mark 紫 color:purple %}
{% mark 亮 color:light %}
{% mark 暗 color:dark %}
{% mark 警告 color:warning %}
{% mark 错误 color:error %}

2.6 hashtag 标签

1
2
{% hashtag Stellar https://xaoxuu.com/wiki/stellar/ %}
{% hashtag GitHub https://github.com/ color:green %}

2.7 image 图片

1
{% image src [描述] [download:bool|string] [width:px] [padding:px] [bg:hex] [fancybox:bool|string] [ratio:w/h] %}

横向铺满（加下载按钮）：

1
{% image https://xxx.jpg 图片描述 download:true %}

竖图（小图）布局优化：

1
{% image https://xxx.jpg width:200px padding:16px bg:'#ffffff' %}

Fancybox 点击放大（自动加载）：

1
2
{% image https://xxx.jpg fancybox:true %}
{% image https://小图.jpg fancybox:大图链接 %}  <!-- 缩略图+高清 -->

全站开启 Fancybox（_config.stellar.yml）：

1
2
3
tag_plugins:
  image:
    fancybox: false  # 默认关闭，按需开启

2.8 blockquote 段落引用

1
2
3
{% blockquote %}
这是使用 blockquote 标签的例子
{% endblockquote %}

> 引用 写法在技术文章中样式不同；blockquote 标签始终为非技术文章样式。

2.9 quot 强调引用

1
2
3
4
5
6
7
8
9
10
{% quot Stellar 是迄今为止最好用的主题 %}
{% quot 热门话题 icon:hashtag %}
{% quot 特别引用 icon:default %}

<!-- 自定义图标 -->
{% quot icons.yml示例 prefix:solar:planet-bold-duotone %}
{% quot URL示例 prefix:https://... suffix:https://... %}

<!-- 作为标题使用 -->
{% quot 标题 el:h3 %}

配置默认引号（_config.stellar.yml）：

1
2
3
4
5
tag_plugins:
  quot:
    default:
      prefix: bxs:quote-left
      suffix: bxs:quote-right

2.10 poetry 诗词

1
2
3
{% poetry 标题 author:作者 footer:注 %}
正文
{% endpoetry %}

2.11 paper 纸张

1
2
3
4
5
6
7
8
{% paper style:underline title:文言文 author:诸葛亮 date:三国 footer:节选 %}
<!-- line left -->
标题
<!-- paragraph -->
正文段落（首行缩进）
<!-- line right -->
右对齐段落
{% endpaper %}

可选参数：style: underline/无、title、author、date、footer

2.12 reel 卷轴

1
2
3
{% reel 标题 author:作者 date:日期 footer:注 %}
正文
{% endreel %}

2.13 note 备注块（12 色）

1
2
{% note 这是标题 这是正文。 %}
{% note color:green 正文内容 %}

颜色支持：red、orange、amber、yellow、green、cyan、blue、purple、light、dark、warning、error

1
2
3
{% link https://example.com %}
{% link https://example.com desc:true %}
{% link https://example.com 自定义标题 icon:https://xxx.png desc:true %}

自部署 siteinfo API 并在 _config.stellar.yml 中配置：

1
2
3
data_services:
  siteinfo:
    api: https://你的api地址

2.15 button 按钮

1
2
{% button 探索 https://github.com/ icon:solar:planet-bold-duotone %}
{% button 按钮名 https://url color:orange size:xs %}

2.16 okr 目标管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{% okr o1 %}
2077年目标：完成 Volantis 6.0 并发布上线

<!-- okr kr1 percent:100 -->
重构 tag-plugins

<!-- okr kr2 percent:90 status:off_track -->
完成主要页面设计稿

<!-- okr kr3 percent:-12 status:unfinished -->
完成前置准备工作

<!-- okr kr-4 status:at_risk -->
开发、测试和发布

{% endokr %}

OKR 状态：completed（100%）、off_track（延期）、unfinished（未完成）、at_risk（风险）、正常（默认）

2.17 copy 复制行

1
2
3
4
5
{% copy curl -s https://sh.xaox.cc/install | sh %}
{% copy curl -s https://... prefix:$ %}  <!-- 带 $ 提示符 -->
{% copy git:https xaoxuu.com/hexo-theme-stellar %}
{% copy git:ssh xaoxuu.com/hexo-theme-stellar %}
{% copy git:gh xaoxuu.com/hexo-theme-stellar %}

2.18 radio 单选

1
2
3
{% radio 没有勾选的单选框 %}
{% radio checked:true 已勾选的单选框 %}
{% radio checked:true color:green 绿色选中 %}

可选参数：checked:true/false、color:red/orange/yellow/green/cyan/blue/purple

2.19 checkbox 复选

1
2
3
4
5
{% checkbox 普通的没有勾选的复选框 %}
{% checkbox checked:true 普通的已勾选 %}
{% checkbox symbol:plus color:green checked:true 显示为加号的绿色勾选 %}
{% checkbox symbol:minus color:yellow checked:true 显示为减号的黄色勾选 %}
{% checkbox symbol:times color:red checked:true 显示为乘号的红色勾选 %}

可选参数：checked:true/false、color:...、symbol:plus/minus/times

2.20 audio 音频

1
2
3
4
{% audio https://example.com/audio.mp3 %}
{% audio netease:1856385686 %}              <!-- 网易云 -->
{% audio type:2 netease:1856385686 %}        <!-- type:2 歌单 / 0 单曲 -->
{% audio netease:1856385686 autoplay:1 %}    <!-- autoplay 自动播放 -->

2.21 video 视频

1
2
3
4
{% video bilibili:BV1GP4y1d729 %}
{% video youtube:LB8KwiiUGy0 %}
{% video https://example.com/video.mp4 %}
{% video bilibili:BV1GP4y1d729 width:100% autoplay:0 %}

可选参数：width、autoplay:1/0；bilibili 和 youtube 可设置 width 和 autoplay

2.22 chat 聊天

需要配置 chat_users.yaml，支持 QQ 和微信风格。
示例和文档：https://github.com/xaoxuu/hexo-theme-stellar/pull/560

1
2
{% chat 用户名 消息内容 %}
{% chat 用户名 %}

2.23 navbar 导航栏

1
{% navbar active:/wiki/ [文章](/) [项目](/wiki/) [留言](#comments) [GitHub](https://github.com/) %}

active 传入要高亮的按钮 URL。

2.24 frame 设备框架

1
{% frame iphone11 img:https://xxx.png video:https://xxx.mp4 focus:top %}

可选参数：focus:top/bottom，支持 iPhone 等设备框架。

2.25 文本修饰标签集

1
2
3
4
5
6
7
8
9
{% blur 高斯模糊 %}
{% password 密码效果 %}
<u>下划线</u>                      <!-- HTML 原生 -->
<em>着重号</em>                    <!-- HTML 原生 -->
{% wave 波浪线 %}
<s>删除线</s>                      <!-- HTML 原生 -->
{% sup 上角标 %}
{% sub 下角标 %}
{% kbd ⌘ %} + {% kbd D %}

着重号、下划线、删除线等也可以直接使用 HTML 原生标签。

三、数据类标签组件（8 个）

3.1 timeline 时间线

静态写法：

1
2
3
4
5
6
{% timeline %}
<!-- node 2021年2月16日 -->
内容
<!-- node 2021年2月11日 -->
内容
{% endtimeline %}

动态写法（GitHub Issues）：

1
2
3
4
5
6
7
8
9
10
11
12
13
{% timeline api:https://api.github.com/repos/your-name/repo/issues %}{% endtimeline %}

<!-- 升序，限3条 -->
{% timeline api:.../issues?direction=asc&per_page=3 %}{% endtimeline %}

<!-- 按评论数排序 -->
{% timeline api:.../issues?sort=comments %}{% endtimeline %}

<!-- 只显示某人 -->
{% timeline user:username api:... %}{% endtimeline %}

<!-- GitHub Releases -->
{% timeline api:https://api.github.com/repos/owner/repo/releases %}{% endtimeline %}

微博动态：

1
{% timeline limit:20 type:weibo api:你的json文件地址 %}{% endtimeline %}

静态+动态混合：

1
2
3
4
{% timeline reversed:true api:https://...data.json %}
<!-- node 静态内容 -->
静态内容
{% endtimeline %}

3.2 friends 友链

静态数据（source/_data/links/xxx.yml）：

1
2
3
4
5
6
7
8
- title: 某某某
  url: https://example.com
  cover: https://cover.jpg
  icon: https://icon.png
  description: 简介
categories:
  - 知识库

1
{% friends xxx %}

动态友链（GitHub Issues）：

1
2
{% friends api:https://raw.github.com/xxx/friends/output/v2/data.json %}
{% friends posts:true api:... %}  <!-- 带文章聚合 -->

3.3 sites 网站卡片

静态数据（source/_data/links/分组名.yml）：

1
2
3
4
5
6
7
- title: 标题
  url: https://example.com
  cover: https://cover.jpg
  description: 简介
categories:
  - 知识库

1
{% sites 分组名 %}

3.4 albums 专辑

1
{% albums 分组名 %}

数据文件写法同 friends/sites。

3.5 posters 海报

1
{% posters 分组名 %}

3.6 md 渲染外部 Markdown

1
2
3
{% folding %}
{% md https://gcore.jsdelivr.net/gh/xaoxuu/hexo-theme-stellar/README.md %}
{% endfolding %}

3.7 ghcard GitHub 卡片

1
2
{% ghcard xaoxuu %}
{% ghcard xaoxuu/hexo-theme-stellar theme:dark %}

可选参数：theme:dark/light、var_color、hide_border、theme:...

3.8 toc 文档目录树

1
{% toc wiki:xxx [open:true] [display:mobile] [title] %}

四、容器类标签组件（8 个）

4.1 box 盒子容器

1
2
3
{% box [标题] [color:color] [child:codeblock/tabs] %}
内容
{% endbox %}

彩色代码块（10 种颜色）：

1
2
3
{% box 推荐写法 color:green child:codeblock %}
func test() {}
{% endbox %}

嵌套多段代码块：

1
2
3
4
5
6
7
{% box %}
发送端
(void)test { ... }
<!-- sn -->
订阅端
func setup() { ... }
{% endbox %}

嵌套 tabs：

1
2
3
4
5
6
{% box 标题 color:blue child:tabs %}
<!-- tab 标签1 -->
内容1
<!-- tab 标签2 -->
内容2
{% endbox %}

4.2 folding 折叠容器

1
2
3
{% folding [标题] [codeblock:bool] [open:bool] [color:color] %}
内容
{% endfolding %}
1
2
3
4
5
6
7
{% folding open:true color:yellow 默认打开的代码折叠框 %}
代码
{% endfolding %}

{% folding 危险 color:error %}
警告内容
{% endfolding %}

颜色：red、orange、yellow、green、cyan、blue、purple、light、dark

4.3 folders 折叠聚合

适用于题目列表等多平铺折叠场景：

1
2
3
4
5
6
7
8
{% folders %}
<!-- folder 题目1 -->
答案1
<!-- folder 题目2 -->
答案2
<!-- folder 题目3 -->
答案3
{% endfolders %}

4.4 tabs 分栏容器

1
2
3
4
5
6
{% tabs 唯一ID, [active:1] %}
<!-- tab 标签1 -->
内容1
<!-- tab 标签2 -->
内容2
{% endtabs %}

可选参数：align:center

4.5 grid 网格分区

动态列数（最小宽度240px）：

1
2
3
4
5
6
7
8
{% grid %}
<!-- cell -->
cell 1
<!-- cell -->
cell 2
<!-- cell -->
cell 3
{% endgrid %}

固定列数：

1
{% grid c:2 %}...{% endgrid %}

设置最小宽度：

1
{% grid w:350px %}...{% endgrid %}

背景样式：

1
2
3
4
{% grid bg:box w:150px %}   普通 Box 样式
{% grid bg:card w:150px %}  可浮起的卡片样式
{% grid bg:card gap:32px %}  设置间距
{% grid bg:card br:4px %}    设置圆角

4.6 banner 横幅容器

独立页面顶部：

1
2
3
{% banner 随记 bg:https://xxx.jpg %}
{% navbar active:/notes/ [随记](/notes/) [收藏](/bookmark/) %}
{% endbanner %}

个人资料页：

1
2
{% banner 某某 这是简介 avatar:https://xxx.jpg bg:https://xxx.jpg %}
{% endbanner %}

文章摘要卡片（可点击跳转）：

1
2
{% banner 标题 描述 bg:https://xxx.jpg link:/blog/20221126/ %}
{% endbanner %}
1
2
3
4
5
{% gallery %}
![](https://xxx1.jpg)
![](https://xxx2.jpg)
![](https://xxx3.jpg)
{% endgallery %}

4.8 swiper 轮播容器

1
2
3
4
5
6
7
8
9
10
{% swiper %}
![](https://xxx1.jpg)
![](https://xxx2.jpg)
![](https://xxx3.jpg)
{% endswiper %}

{% swiper width:min %}...{% endswiper %}   <!-- 25% 宽度 -->
{% swiper width:max %}...{% endswiper %}   <!-- 100% 宽度 -->
{% swiper effect:cards %}...{% endswiper %}
{% swiper effect:coverflow %}...{% endswiper %}

注意：一个页面只能设置一次 swiper，效果全局生效。

五、常用 front-matter 模板

技术文章模板

1
2
3
4
5
6
7
8
9
10
---
title: 文章标题
date: 2026-04-12
tags: [标签1, 标签2]
description: 文章描述（SEO和摘要）
categories:
  - 知识库

type: tech
---

图文类文章模板

1
2
3
4
5
6
7
8
9
---
title: 标题
date: 2026-04-12
tags: [标签]
type: story
poster:
  headline: 大标题
  caption: 描述文字
---

独立页面模板

1
2
3
4
5
6
---
title: 页面标题
date: 2026-04-12
type: page
menu_id: about
---

六、参考链接

链接 说明
https://xaoxuu.com/wiki/stellar/ 官方文档首页
https://xaoxuu.com/wiki/stellar/pages/ 文章与页面编写
https://xaoxuu.com/wiki/stellar/tag-plugins/ 标签组件索引
https://xaoxuu.com/wiki/stellar/tag-plugins/express/ 表达类组件（33+）
https://xaoxuu.com/wiki/stellar/tag-plugins/data/ 数据类组件（8）
https://xaoxuu.com/wiki/stellar/tag-plugins/container/ 容器类组件（8）
https://xaoxuu.com/wiki/stellar/front-matter/ front-matter 字段索引
https://weekdaycare.cn/posts/emoji-blob/ 表情速查表
https://icon-sets.iconify.design/ Iconify 图标库
https://github.com/xaoxuu/star-vote vote/rating 部署项目

快来参与讨论吧~