halo-theme-WarmIsland/docs/config/article.md

文章

文章配置控制文章详情页的展示方式，包括封面图、元信息、目录导航、代码高亮等功能。这些设置影响每一篇文章的阅读体验。

配置项一览

配置项	类型	默认值	说明
article_show_cover	开关	true	显示封面图
article_show_date	开关	true	显示发布日期
article_show_category	开关	true	显示分类
article_show_tags	开关	true	显示标签
article_show_nav	开关	true	显示上下篇导航
article_show_toc	开关	true	显示文章目录
article_toc_position	下拉	left	目录位置：left / right
article_show_word_count	开关	true	显示字数统计
article_show_visit_count	开关	true	显示阅读量统计
article_show_read_time	开关	false	显示预计阅读时间
article_code_theme	下拉	warm	代码高亮主题：warm / cold
article_toc_expand	下拉	active	目录展开模式：active / all
article_show_related	开关	false	显示相关文章推荐
article_related_title	文本	相关推荐	相关文章标题
article_show_share	开关	true	显示分享按钮
article_share_title	文本	分享	分享区域标题
article_extra_spacing	开关	true	中英文混排自动加空格；依赖「API 扩展包」，插件未安装时自动跳过
article_extra_highlight	开关	false	服务端代码高亮；依赖「API 扩展包」全量版（含 JS 运行时），开启后替代主题自带配色，环境不支持请勿开启

详细说明

封面图（article_show_cover）

开启后，文章详情页顶部会显示封面图（全宽展示）。封面图来自 Halo 后台编辑文章时设置的「封面图」字段。

::: tip 如果文章未设置封面图，即使开启此选项也不会显示任何内容，页面会自动调整布局。建议为重要文章设置封面图以获得最佳视觉效果。 :::

元信息展示

以下开关控制文章标题下方的元信息区域：

配置项	说明
article_show_date	显示文章发布日期
article_show_category	显示文章所属分类（可点击跳转）
article_show_tags	显示文章标签列表（可点击跳转）
article_show_word_count	显示文章字数统计
article_show_visit_count	显示文章阅读量
article_show_read_time	显示预计阅读时间（默认关闭）

::: tip 预计阅读时间基于中文约 300 字/分钟、英文约 200 词/分钟的阅读速度估算。如需开启，建议同时开启字数统计，两者配合提供完整的阅读参考信息。 :::

上下篇导航（article_show_nav）

开启后，文章底部会显示「上一篇」和「下一篇文章」的导航链接，方便访客连续阅读。

文章目录（article_show_toc）

开启后，文章页面会显示基于标题层级自动生成的目录（Table of Contents），帮助读者快速定位和跳转到文章各章节。

目录位置（article_toc_position）

值	说明
left	目录显示在正文左侧（默认）
right	目录显示在正文右侧

桌面端行为

• 目录以侧边栏形式固定显示
• 滚动时自动高亮当前阅读位置对应的目录项
• 点击目录项平滑滚动到对应章节
• 当文章标题较少（少于 2 个）时，目录区域自动隐藏

移动端行为

• 目录不显示侧边栏，而是在文章标题下方显示一个可展开的目录按钮
• 点击按钮弹出目录面板，选择后自动关闭
• 这种设计避免了移动端屏幕空间不足的问题

::: tip 目录仅提取文章中的 <h2> 和 <h3> 标签生成。建议在撰写长文时合理使用二级和三级标题，以获得结构清晰的目录。 :::

代码高亮主题（article_code_theme）

主题不再加载 Prism.js 运行时与 autoloader，语法高亮由 Halo 应用市场的代码高亮插件或「API 扩展包」服务端高亮输出。本项只切换主题自托管的两套 .token 配色（assets/vendor/prism-warm.css / prism-cold.css），不产生任何远程请求：

值	说明
warm	暖色调代码主题，与暖屿整体风格一致（默认）
cold	冷色调代码主题，类似经典代码编辑器风格，适合技术博客

# 技术博客推荐
article_code_theme: cold

# 生活博客推荐
article_code_theme: warm

::: tip 支持的语言范围取决于所安装的高亮插件（常见的 JavaScript、Python、Java、Go、Rust、YAML、JSON、Bash 等均可覆盖）。语言识别基于代码块的语言标记，建议始终显式标注。 :::

目录展开模式（article_toc_expand）

控制文章目录的展开方式：

值	说明
active	仅展开当前阅读位置所在的分组，其余分组折叠（默认）
all	全部展开，显示所有层级的目录项

::: tip 对于标题层级较多的长文，推荐使用 active 模式，可以让读者更聚焦于当前章节。对于短文或标题层级较少的文章，all 模式可以一次性展示完整目录结构。 :::

相关文章推荐（article_show_related）

开启后，文章底部会显示相关文章推荐列表，帮助读者发现更多感兴趣的内容。相关文章基于 Halo 的随机推荐算法选取。

相关文章标题（article_related_title）

自定义相关文章推荐区域的标题文字，默认为「相关推荐」。仅在 article_show_related 开启时显示此配置项。

article_show_related: true
article_related_title: "猜你喜欢"

分享功能（article_show_share）

开启后，文章底部会显示分享按钮，支持以下社交平台：

平台	说明
QQ	点击后弹出 QQ 分享窗口，自动携带文章标题和链接
微信	弹出文章链接并提供「复制链接」按钮，由访客在微信内分享（不加载二维码库）
微博	分享到新浪微博
X (Twitter)	分享到 X
Facebook	分享到 Facebook
Telegram	分享到 Telegram
复制链接	复制文章链接到剪贴板（始终显示）

分享渠道（article_share_channels）

选择要显示的分享按钮，可多选。默认选中 QQ、微信、微博。复制链接按钮始终显示，不可关闭。

渠道	默认选中
QQ	✅
微信	✅
微博	✅
X (Twitter)	❌
Facebook	❌
Telegram	❌

::: info 图标来源 分享按钮图标来自 Font Awesome（Free v7.2.0，CC BY 4.0 / SIL OFL 1.1 协议）和 Simple Icons（CC0 协议）。微信图标点击后会弹出「复制链接」弹层，用户复制后可在微信内分享；二维码由远程库生成的旧实现已移除，主题不再加载任何第三方脚本。 :::

分享区域标题（article_share_title）

自定义分享区域的标题文字，默认为「分享」。仅在 article_show_share 开启时显示此配置项。

article_show_share: true
article_share_title: "分享这篇文章"
article_share_channels:
  - qq
  - wechat
  - weibo

::: tip 分享功能会自动携带文章标题和完整链接，无需手动配置分享内容。微信分享通过「复制链接」实现：弹层显示文章完整 URL（含域名），点击按钮写入剪贴板，全程在浏览器本地完成、不发送外部请求。QQ 分享通过弹窗方式打开 QQ 分享页面。除访客主动点击外，页面加载时不会访问任何第三方平台。 :::

阅读增强功能

除了可配置的项目外，文章详情页还包含以下内置功能：

阅读进度条

页面顶部显示一条阅读进度条，随滚动位置实时更新，让读者直观了解当前阅读进度。进度条颜色跟随强调色。

点赞按钮

文章底部提供点赞按钮，访客可以点击表达对文章的喜爱。点赞数据由 Halo 核心功能提供。

LightGallery 图片灯箱

文章中的图片支持点击放大查看，基于 LightGallery 实现：

• 点击图片弹出灯箱查看大图
• 支持左右切换浏览多张图片
• 支持缩放、旋转等操作
• 按 Esc 或点击背景关闭灯箱

::: tip LightGallery 会自动识别文章正文中的所有 <img> 标签并应用灯箱效果，无需手动配置。 :::

相关页面

• 首页 — 首页文章列表配置
• 评论 — 文章评论样式配置
• 样式设置 — 强调色与圆角配置
• 文章详情页 — 文章模板与结构说明