Aurora Star 极光主题 — 使用文档

• 主题版本：2.2.1
• 作者：chinachat
• 项目地址：https://github.com/chinachat/aurora-star
• 适用 WordPress：6.0+ / PHP 7.4+
• 语言：简体中文（内置语言包）

立即下载 Github下载

目录

1. 安装与启用
2. 后台一级设置菜单
3. 主题设置（自定义器）
   3.9. 列表布局
4. 暗黑 / 明亮模式
5. 导航菜单与菜单图标
   5.5. 页脚结构与备案信息（ICP / 公安备案）
   5.6. 友情链接
6. 文章特色图
7. 文章浮动目录
8. 代码高亮
9. 图片灯箱（点击放大）
   9.5. 全局浮动导航按钮
   9.8. 评论增强（头像 / 归属地 / 系统与浏览器）
   9.9. Markdown 写作
10. 短代码完整示范
11. 常见问题

1. 安装与启用

方法一：后台上传（推荐）

1. 在 WordPress 后台进入「外观 → 主题 → 添加新主题 → 上传主题」。
2. 选择 aurora-star.zip，点击「现在安装」。
3. 安装完成后点击「启用」。

方法二：手动上传

将 aurora-star 文件夹上传到服务器 wp-content/themes/ 目录下，然后在后台「外观 → 主题」中启用。

提示：主题所有资源（图标库、代码高亮、JS/CSS）均已自托管，不依赖任何外部 CDN，可离线运行。

2. 后台一级设置菜单

启用主题后，后台侧边栏会出现一级菜单 「Aurora Star 主题」，点击进入可看到：

• 「打开主题自定义器」按钮：直达主题设置面板
• 各功能配置位置的说明速查表

所有可视化设置均在 WordPress 自定义器 中完成。

3. 主题设置（自定义器）

进入方式：外观 → 自定义 → Aurora Star 主题设置（或通过一级菜单一键直达）。

设置项分为以下几组：

3.1 颜色

3.2 暗黑模式

3.3 文章目录

3.4 代码高亮

3.5 图片灯箱

3.6 文章

默认特色图怎么用

1. 到 外观 → 自定义 → Aurora Star 主题 → 文章 → 默认特色图，点「选择图像」上传或挑选一张。
2. 之后没有设置特色图的文章会自动用这张图，不用逐篇去补。

几点说明：

• 存的是媒体库里的附件（不是图片 URL），所以会自动生成 srcset 响应式图片，
  并按主题注册的尺寸（列表 640×360、大图 1600×800）裁剪。
• 文章自己的特色图永远优先，默认图只在缺失时兜底。
• 两个位置可以分别关闭：只想让列表有图、不想让每篇文章顶部都顶一张通用大图，就把
  「默认图用于文章页顶部大图」取消勾选。
• 图片的替代文字（alt）取自媒体库该附件的「替代文本」，建议填上，利于读屏与 SEO。
• 附件被删除、或换成非图片后，默认图会自动失效并回退到原来的占位图标。
• 想彻底恢复原样：清空「默认特色图」即可。

3.7 背景

3.8 页脚

3.9 列表布局

首页、归档、搜索页的文章列表样式。三种布局共用同一份模板，只换观感。

三种布局长什么样：

关于列数：

• 手机（< 640px）始终 1 栏，平板（≥ 640px）2 栏，桌面端才用你选的列数。
• 选「列表」时该选项不生效——列表按定义就是单栏。
• 列数覆盖走 wp_head 的动态 CSS，排在所有样式表之后，优先级最高。

4. 暗黑 / 明亮模式

• 页头右侧的 月亮/太阳按钮 可随时切换，选择会被保存在浏览器中，下次访问自动生效。
• 若在设置中选择「跟随系统」，当系统切换到暗色主题时站点自动跟随。
• 开启「按时间段自动切换」后，夜间访问自动呈现暗黑模式。
• 极光背景：浅色主题显示浅色极光背景图，暗色主题自动切换为暗色极光背景图（可在 自定义器 → Aurora Star 主题设置 → 背景 关闭）。

5. 导航菜单与菜单图标

创建菜单

1. 后台进入「外观 → 菜单」，新建或编辑菜单。
2. 在「显示位置」勾选「主导航」或「页脚导航」。
3. 将页面/文章/分类加入菜单并保存。

设置菜单图标（需启用 Font Awesome 7 图标库）

每个菜单项下方会出现「图标（Font Awesome 类名）」输入框，填入图标类名即可，例如：

图标会显示在菜单文字左侧，实心/描边/品牌图标均可。

类名可在 Font Awesome 官方图标库（fontawesome.com/search）查询，取 fa-solid fa-xxx 形式。

支持多级下拉菜单：在菜单中拖拽形成层级，桌面端鼠标悬停展开，移动端点击展开。

5.5 页脚结构与备案信息（ICP / 公安备案）

页脚自上而下分为若干行，不再挤在一行：

友情链接   友站 A   友站 B          ← 分配了「友情链接」菜单时显示
关于   联系   隐私政策               ← 页脚导航菜单

© 2026 站点名                        ← 版权
京ICP备00000000号 · 🛡 京公网安备…    ← 备案（单独一行）
由 Aurora Star 极光主题 驱动 · IP Geolocation by DB-IP   ← 署名

备案信息

在 自定义器 → Aurora Star 主题设置 → 页脚 中填写：

• ICP 备案号：填入后显示备案文字链接（如「京ICP备00000000号」），指向工信部备案查询系统。留空则不显示。
• 公安备案号：填入后显示公安备案（带官方盾牌徽章，图标已本地化自托管），可填写公安备案查询链接。留空则不显示。

两者单独占一行，与版权文案分开；都留空则整行不输出。
两个链接都以新标签页打开，并带 rel="noopener noreferrer nofollow"。

主题署名

页脚「由 Aurora Star 极光主题 驱动」中的主题名是指向
GitHub 仓库 的链接，新标签页打开。
可用过滤器改成自己的地址：

add_filter( 'aurora_star_theme_url', function () {
    return 'https://your-site.com/';
} );

页脚链接都以新标签页打开

页脚导航与友情链接位置下的所有菜单链接都会自动加上
target="_blank" 与 rel="noopener noreferrer"；主导航不受影响。
如需关闭：

add_filter( 'aurora_star_footer_links_new_tab', '__return_false' );

5.6 友情链接

主题预留了独立的「友情链接」菜单位置，不占用页脚导航：

1. 进入 外观 → 菜单，新建一个菜单（例如「友情链接」）
2. 添加自定义链接（友站名称 + 网址）
3. 在「显示位置」中勾选 友情链接，保存

菜单会显示在页脚顶部。支持主题的菜单图标功能——在菜单项的「图标」字段填
Font Awesome 类名（如 fa-solid fa-link）即可。

未分配菜单时该区域完全不输出，不会留下空白。

6. 文章特色图

• 在文章/页面编辑页右侧「特色图片」面板上传图片。
• 列表页（首页/归档/搜索）：显示 640×360 缩略图。
• 文章详情页：顶部显示 1600×800 大图。
• 可在 自定义器 → Aurora Star 主题设置 → 文章 中关闭文章内特色大图显示（列表缩略图不受影响）。
• 未设置特色图的文章，列表会显示占位图标。

7. 文章浮动目录

文章正文中的 h2、h3、h4 标题会自动生成目录，在桌面端右侧浮动显示：

• 滚动高亮：随阅读位置高亮当前章节。
• 阅读进度条：目录顶部显示文章阅读进度。
• 大类折叠：含子标题的大类默认折叠，读到该章节位置时自动展开其子类；也可点击章节右侧箭头手动展开/折叠。
• 折叠/展开：点击目录标题右侧箭头可收起。

控制目录显示

• 全局开关：自定义器 → Aurora Star 主题设置 → 文章目录。
• 单篇隐藏：编辑文章时，右侧「Aurora Star 文章选项」勾选「隐藏本文浮动目录」。
• 字数控制：文章字数少于设定值（默认 300）时不显示目录。

目录基于标题层级自动嵌套，标题顺序错乱时会按层级自动归类。

8. 代码高亮

基于自托管 Prism.js 1.30，支持 37 种常用语言，并带行号（可开关）、复制按钮、语言标签。

主题设置

在 自定义器 → Aurora Star 主题设置 → 代码高亮 中可配置：

方式一：短代码（推荐）

[code lang="php"]echo "hello";[/code]

在后台编辑器（经典或区块编辑器）中直接输入上述短代码即可。参数说明：

示例：

[code lang="php" line="true"]<?php echo "hi"; ?>[/code]

[code lang="python" line="false"]def hello():
    print("hi")[/code]

注意：区块编辑器（Gutenberg）会默认把内容中的换行和空格处理掉，建议代码内容用 HTML 实体写，或用经典编辑器，或直接在文本模式编辑。

与 Markdown 发布器共存：在 wp-markdown-publisher 的

[code lang="php"]
a = 1
b = 2

[/code]

```html
<p>foo</p>
<p>bar</p>
```

<pre class="language-python"><code>def hello():
    print("hello world")</code></pre>

[头像] 张三  [🇨🇳 中国 · 广东 · 深圳]  [🪟 Windows 10/11]  [🌐 Chrome 120.0.0.0]
       2026-09-12 12:00

add_filter( 'aurora_star_geoip_db_path', function () {
    return WP_CONTENT_DIR . '/uploads/geoip/ip-database.mmdb';
} );

---
title: 我的文章
categories: [使用教程, WordPress]
tags: [Markdown, 插件]
---

[markdown]
## 小标题
正文 加粗、行内代码。



列 A
列 B


1
2

支持的语法

标题（ATX / Setext）、围栏与缩进代码块、引用、有序/无序/嵌套列表、任务列表、
表格、分隔线、链接与图片（行内 / 引用式）、脚注、行内 HTML、自动链接、
强调 / 加粗 / 删除线、代码段、目录（TOC）。

与短代码、代码高亮的关系

• [markdown] 区块里可以正常使用主题短码（[tabs] [notice] [code] 等），
  主题的短码保护在 Markdown 渲染之后运行，顺序是确定的。

• 代码围栏里的短码不会被当成短码执行（主题会把 <pre> 内的 [ ] 转义）。

• 在 [markdown] 区块里写 [code] 时，正文含空行也没问题；
  但代码内容是 HTML 标签时，更稳妥的写法是用围栏代码块：

  ```html
  <p>foo</p>
  ```

从独立插件迁移

如果你是先在插件里写的内容，直接停用插件即可，不需要做任何数据迁移：

• 主题读取的是同一份数据（选项 mdp_settings，文章元数据 _mdp_markdown 等），
  已有的 Markdown 原文、渲染状态与全部设置原样继承。
• 插件仍在启用时，主题内置模块会自动让路并在后台给出提示；
  想回退到插件，重新启用插件即可——两边可以随时互换。
• 文章正文保存的始终是渲染后的 HTML，所以即使哪天不用本主题，文章内容也不会丢。

数据清理

主题没有”卸载”，对应的开关是 Markdown 发布 → 设置 → 数据清理 →
「切换主题时同时删除设置项」。勾选后，切走本主题时会删除 mdp_settings
与 mdp_version 两个选项；文章里的 Markdown 原文与已渲染的 HTML 不会被删除。

升级后建议重新渲染

标题锚点的生成规则在 v2.0.1 对齐了 GitHub（不再折叠连续的 -）。
v2.0.1 之前渲染过的文章，正文里已经写死的标题 id 还是旧格式，
手写的目录锚点可能点不动。

另外 v2.2.1 之前，Markdown 文章里的短码会把属性中的网址自动转成链接，
导致 [button href="…"] 的链接失效——这些坏掉的 HTML 已经存进文章正文，
同样需要重新渲染才能恢复。

升级后到 Markdown 发布 → 批量重新渲染 跑一次即可；
编辑页也会提示「解析器已更新」，逐篇保存同样有效。

10. 短代码完整示范

以下是主题内置的全部短代码，可直接复制使用。

10.1 按钮 [button]

[button href="https://example.com" color="primary" size="lg" target="_blank"]立即查看[/button]

[button href="/about" color="secondary" size="md" icon="fa-solid fa-info-circle"]了解更多[/button]

[button href="#" color="ghost" size="sm"]次要按钮[/button]

[button href="#" color="danger" size="md"]危险操作[/button]

[button href="#" color="success" size="md"]成功按钮[/button]

10.2 提示框 [alert]

[alert type="info" title="提示"]这里是普通提示内容。[/alert]

[alert type="success" title="操作成功"]数据已保存。[/alert]

[alert type="warning" title="注意"]内容可能有变化，请留意。[/alert]

[alert type="error" title="错误"]发生了一个错误。[/alert]

10.3 注释块 [note]

[note title="补充说明"]这是一段注释内容，常用于补充信息。[/note]

[note]无标题的注释块。[/note]

10.4 标签页 [tabs]

[tabs]
[tab title="介绍"]这是第一个标签的内容。[/tab]
[tab title="用法"]这是第二个标签的内容。[/tab]
[tab title="示例"]这是第三个标签的内容。[/tab]
[/tabs]

10.5 手风琴 [accordion]

[accordion]
[accordion-item title="问题一" open="true"]第一个问题的答案。[/accordion-item]
[accordion-item title="问题二"]第二个问题的答案。[/accordion-item]
[accordion-item title="问题三"]第三个问题的答案。[/accordion-item]
[/accordion]

10.6 代码 [code]

[code lang="php"]<?php echo "Hello World"; ?>[/code]

[code lang="python" line="true"]def add(a, b):
    return a + b[/code]

参数见 第 8 节。

多行代码：直接把代码写在短码标签之间即可，换行与空行都会原样保留：

[code lang="php"]
function foo() {
    $a = 1;

    return $a;
}
[/code]

主题在 wpautop 之前对 [code] 内容做了保护，因此多行代码不会被 WordPress
自动插入 <br /> 或 <p> —— 这类标记以前会被转义成字面量、显示在代码块里。

10.7 视频 [youtube]

[youtube id="VIDEO_ID"]

10.8 图标 [icon]

[icon name="fa-solid fa-star" size="2x" color="#f59e0b"]

10.9 免责声明 [notice]

[notice]本文内容仅供学习参考，不构成任何建议。[/notice]

11. 常见问题

Q：上传主题提示「主题缺少 style.css」？

请确认下载的是最新版 aurora-star.zip（打包时已修正路径分隔符问题），并重新上传。

Q：代码高亮没有生效？

1. 确认在 自定义器 → 代码高亮 中已开启。
2. 确认代码块带语言标识：短代码 [code lang="xxx"] 或 <pre class="language-xxx">。
3. 刷新浏览器缓存（Ctrl+F5）。

Q：文章目录没有显示？

1. 确认文章字数达到「最少字数显示目录」阈值。
2. 确认文章包含 h2/h3 标题（正文标题，非文章标题）。
3. 检查文章编辑页右侧「隐藏本文浮动目录」未勾选。

Q：菜单图标不显示？

确认菜单项「图标」字段填写了完整的 Font Awesome 类名（如 fa-solid fa-home），且网站可访问主题内的 fontawesome.min.css。

Q：暗黑模式按钮不工作？

检查 自定义器 → 暗黑模式 → 显示切换按钮 是否开启；浏览器隐私模式下 localStorage 可能受限，但不影响切换。

Q：如何更换代码高亮主题？

目前内置 Okaidia（暗色）。如需其他 Prism 主题，可在主题目录 assets/vendor/prism/themes/ 中加入对应 CSS 文件，并在 inc/customizer.php 的 aurora_star_highlight_theme 选项中添加。

© Aurora Star 极光主题 · by chinachat · 使用中遇到问题，欢迎反馈到 https://github.com/chinachat/aurora-star