132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
# 文章
|
||
|
||
文章配置控制文章详情页的展示方式，包括封面图、元信息、目录导航、代码高亮等功能。这些设置影响每一篇文章的阅读体验。
|
||
|
||
## 配置项一览
|
||
|
||
| 配置项 | 类型 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `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_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）
|
||
|
||
WarmIsland 使用 Prism.js 实现代码语法高亮，提供两种主题风格：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `warm` | 暖色调代码主题，与暖屿整体风格一致（默认） |
|
||
| `cold` | 冷色调代码主题，类似经典代码编辑器风格，适合技术博客 |
|
||
|
||
```yaml
|
||
# 技术博客推荐
|
||
article_code_theme: cold
|
||
|
||
# 生活博客推荐
|
||
article_code_theme: warm
|
||
```
|
||
|
||
::: tip
|
||
代码高亮支持多种编程语言，包括 JavaScript、Python、Java、Go、Rust、YAML、JSON、Bash 等。语言检测基于代码块的语言标记自动完成。
|
||
:::
|
||
|
||
## 阅读增强功能
|
||
|
||
除了可配置的项目外，文章详情页还包含以下内置功能：
|
||
|
||
### 阅读进度条
|
||
|
||
页面顶部显示一条阅读进度条，随滚动位置实时更新，让读者直观了解当前阅读进度。进度条颜色跟随强调色。
|
||
|
||
### 点赞按钮
|
||
|
||
文章底部提供点赞按钮，访客可以点击表达对文章的喜爱。点赞数据由 Halo 核心功能提供。
|
||
|
||
### LightGallery 图片灯箱
|
||
|
||
文章中的图片支持点击放大查看，基于 LightGallery 实现：
|
||
|
||
- 点击图片弹出灯箱查看大图
|
||
- 支持左右切换浏览多张图片
|
||
- 支持缩放、旋转等操作
|
||
- 按 `Esc` 或点击背景关闭灯箱
|
||
|
||
::: tip
|
||
LightGallery 会自动识别文章正文中的所有 `<img>` 标签并应用灯箱效果，无需手动配置。
|
||
:::
|
||
|
||
## 相关页面
|
||
|
||
- [首页](/config/home) — 首页文章列表配置
|
||
- [评论](/config/comment) — 文章评论样式配置
|
||
- [样式设置](/config/style) — 强调色与圆角配置
|
||
- [文章详情页](/pages/post) — 文章模板与结构说明
|