文章页配置

本页讲解文章页的配置：头图、标题下方元信息（日期/字数/阅读时长/阅读数）、TOC 目录、评论、打赏、版权、公式与流程图。全部在主题配置的 post 段内。

主题配置以 userConfig/_config.tmp.yml 为权威源（CI 时覆盖主题配置）。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

显示与布局

1. 文章页头图

用途：文章页顶部 Banner（区别于首页头图，可单独设置）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：打开任意文章，页面顶部出现整宽头图，高度占视口的 70%，图上叠一层 30% 黑色蒙版以提升白色标题的对比度。

对应配置（主题配置，post 段）：

post:
  banner_img: /img/default.png   # 文章页头图
  banner_img_height: 70          # 头图高度（屏幕百分比，0-100）
  banner_mask_alpha: 0.3         # 黑色蒙版不透明度（0-1）

1.2 常用选项

① 单篇换头图

效果：只有该篇文章的顶部换成指定图片，其他文章仍用全局头图。

对应配置（文章 front-matter）：

banner_img: /medias_webp/banner/1.webp

② 调头图高度

效果：数值越大头图越高、标题下移越多；70 约占七成视口，40 只留一条横幅。

对应配置：

post:
  banner_img_height: 40

③ 调蒙版深浅

效果：0 完全不压暗（浅色图上白字可能看不清），0.5 明显压暗，1 全黑。

对应配置：

post:
  banner_mask_alpha: 0.5

④ 无 front-matter 图片时自动取图

效果：文章没写 img 时，按标题 hash 从 featureImages 数组中固定取一张，同一标题每次都拿到同一张图。

对应配置（主题配置，顶层 featureImages）：

featureImages:
  - /medias_webp/featureimages/0.webp
  - /medias_webp/featureimages/1.webp

1.3 全部可调项

1.4 边界与冲突

头图来源优先级（_partial/post/post-cover 渲染逻辑）：

1. front-matter img（如 img: /medias_webp/xxx.webp）——显式指定
2. 无 img 时按标题 hash 从 theme.featureImages 数组取一张（/medias_webp/featureimages/0-44.webp，同一标题恒定同一张）
3. 开启随机背景（theme.background.image.random）时不显示文章 banner

注意：featureImages 唯一图源为 medias_webp/featureimages/（webp，编号 0-44，含 dark/ 子目录）；旧版 medias/featureimages/（jpg）已废弃删除，不要引用 .jpg 路径。

1.5 小结

• 最小可用：只写 banner_img 一项，头图即可出现
• 想突出标题：加大 banner_mask_alpha，或降低 banner_img_height
• 单篇特殊化：在 front-matter 写 img / banner_img，不动全局
• 改了不生效：头图路径属于资源变更，需 clean 构建

2. 元信息（meta）

用途：文章标题下方的一行信息：日期、字数、阅读时长、阅读数，可独立启停。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：文章标题正下方出现一行灰色小字，例如「2026-08-07 · 2,345 字 · 8 分钟 · 123 次阅读」。只开日期与字数时，这一行只剩「日期 · 字数」。

对应配置（主题配置，post.meta 段）：

post:
  meta:
    date:
      enable: true
      format: "LL a"
    wordcount:
      enable: true

2.2 常用选项

① 日期与格式

效果：显示文章日期。"LL a" 输出「2026年8月7日 周五」这类本地化格式。

对应配置：

post:
  meta:
    date:
      enable: true
      format: "LL a"

② 字数统计

效果：标题下出现「N 字」，中文按字符计。

对应配置：

post:
  meta:
    wordcount:
      enable: true

③ 阅读时长

效果：出现「N 分钟」估算。wpm 越大估得越短；awl 是每词平均长度系数，中文保持 1。

对应配置：

post:
  meta:
    min2read:
      enable: true
      awl: 1        # 中文 1 字 = 1 字符
      wpm: 300      # 中文技术文章建议 250-350

④ 浏览量

效果：出现「N 次阅读」。数字来源由 source 决定，切换数据源只改这一个值。

对应配置：

post:
  meta:
    views:
      enable: true
      source: "umami"   # busuanzi | leancloud | umami | waline

⑤ 作者

效果：标题下出现作者名。默认关闭；打开后优先取 front-matter author，没有则取站点 author。

对应配置：

post:
  meta:
    author:
      enable: true

2.3 全部可调项

2.4 边界与冲突

• post.meta.views.source 决定浏览量从哪来——本博客用 umami（自建统计），也可换不蒜子（busuanzi，零配置）或 Waline 评论的浏览量。
• 选 leancloud 时还需要 §21 的 leancloud_visitors 配置；选 waline 时需要 waline.pageview: true。
• post.meta 与 §11 postInfo 是两套独立机制，同时开启会在页面上出现两处信息，按需只留一套。

2.5 小结

• 最小可用：date.enable + wordcount.enable
• 想少请求：浏览量统一用 umami，不要同时开 leancloud_visitors
• 阅读时长不准：调 wpm（中文 250–350）
• 别和 postInfo 重复开：先确认页面信息栏是否已显示

3. 更新时间提示（updated）

用途：在文章开头显示"最后更新于 X"，默认取 md 文件更新时间，可用 front-matter updated 手动指定。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：文章正文开头出现一条提示条「最后更新于 2026年8月7日 周五」。默认关闭，改 enable: true 后出现。

对应配置（主题配置）：

post:
  updated:
    enable: true
    date_format: "LL a"

3.2 常用选项

① 相对时间

效果：relative: true 时提示条显示「3 天前」而不是具体日期，旧文更好读。

对应配置：

post:
  updated:
    relative: true

② 提示条样式

效果：提示条换成对应主题色（info 蓝、success 绿、warning 黄、danger 红等）。

对应配置：

post:
  updated:
    note_class: warning

③ 手动指定更新时间

效果：该篇显示 front-matter 里的日期，而不是文件修改时间；适合内容没改但想标注修订日。

对应配置（文章 front-matter）：

updated: 2026-09-01 10:00:00

3.3 全部可调项

3.4 边界与冲突

• 默认取 md 文件更新时间；写了 front-matter updated 则以它为准。
• note_class 依赖主题的 note 样式，填未知值会回落默认样式（其他值未验证）。

3.5 小结

• 最小可用：只开 enable
• 旧文友好：relative: true
• 想显眼：note_class: warning
• 单篇指定：front-matter updated

4. TOC 目录

用途：文章侧边栏章节导航，滚动时高亮当前章节，可折叠。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

效果：文章页侧边栏出现目录树，滚动正文时对应条目高亮；点击条目跳到该章节。

对应配置（主题配置，顶层 toc 段）：

toc:
  enable: true

4.2 常用选项

① 参与目录的标题级别

效果：默认 h2–h6 都进目录；改成 "h2,h3" 后只显示两级，目录更短。

对应配置：

toc:
  headingSelector: "h2,h3"

② 折叠深度

效果：0 时全部折叠，只看到顶层条目；大于 0 且有下级的条目默认展开。

对应配置：

toc:
  collapseDepth: 2

③ 单篇关闭

效果：该篇文章不显示目录，其他文章不受影响。

对应配置（文章 front-matter）：

toc: false

4.3 全部可调项

4.4 边界与冲突

• collapseDepth 为 0 表示全部折叠；>0 时有下级的条目默认展开。
• 标题必须用 Markdown ##/### 生成，目录才抓得到；HTML 手写标题需要对应 class/选择器。
• 单篇 toc: false 只隐藏目录，不影响正文标题渲染。

4.5 小结

• 最小可用：toc.enable: true
• 目录太长：收窄 headingSelector
• 想要展开态：collapseDepth: 2
• 单篇不要目录：front-matter toc: false

互动与版权

5. 评论（comments）

用途：全站评论系统开关与引擎选择。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：文章正文末尾出现评论区（Waline 的输入框 + 评论列表）；未选引擎或未填服务地址时，评论区为空或报错。

对应配置（主题配置，post.comments 段）：

post:
  comments:
    enable: true
    type: waline    # 引擎：utterances | disqus | gitalk | gitment | valine | waline | changyan | livere | remark42 | twikoo | cusdis | giscus | discuss

还需要所选引擎的必要参数（Waline 见 §5.1.1）。

5.2 常用选项

① 换评论引擎

效果：评论区换成另一种服务（如 GitHub Discussions 的 giscus），外观与登录方式随之改变。

对应配置：

post:
  comments:
    type: giscus

② 页面级开关

效果：该页面不显示评论区（独立页、留言页、友链页同理）。

对应配置（页面 front-matter）：

comments: false

③ Waline 服务地址

效果：评论真正能读写。未填 serverURL 时 Waline 初始化失败、评论区空白。

对应配置：

waline:
  enable: true
  serverURL: 'https://waline.17lai.site'

④ 头像与界面语言

效果：评论者头像样式与界面文案语言变化（avatar: 'hide' 则不显示头像）。

对应配置：

waline:
  avatar: 'mp'
  lang: zh-CN

⑤ 暗色适配

效果：切到暗色模式时 Waline 自动跟随变暗；选择器写错则评论区仍是亮色。

对应配置：

waline:
  dark: 'html[data-user-color-scheme="dark"]'

⑥ 浏览量 / 评论数统计

效果：评论区顶部或文章信息处出现阅读数与评论数。需与 post.meta.views.source: waline、postInfo.commentCount 配合。

对应配置：

waline:
  pageview: true
  comment: true

⑦ 自定义表情回应

效果：文章底部出现一排表情按钮，读者可点选回应。

对应配置：

waline:
  reaction: |
    [
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_agree.png'
    ]

⑧ 图片上传

效果：false 时评论框没有上传按钮；开启后图片以 Base64 嵌入。

对应配置：

waline:
  imageUploader: false

5.2.1 各评论引擎配置

Waline（本博客主用，详细）：

waline:
  enable: true
  serverURL: 'https://waline.17lai.site'   # Waline 服务地址（自建，必填）
  avatar: 'mp'          # 头像样式：''/mp/identicon/monsterid/wavatar/retro/hide
  lang: zh-CN           # 界面语言
  dark: 'html[data-user-color-scheme="dark"]'  # 暗色模式适配选择器
  login: enable         # 登录模式：enable | force
  wordLimit: 1000       # 评论字数限制（0 不限制）
  pageSize: 10          # 每页评论数
  pageview: false       # 文章浏览量统计 v2（配合 post.meta.views.source: waline）
  comment: true         # 评论数统计 v2（配合 postInfo.commentCount）
  reaction: |           # 文章表情回应（自定义表情 URL 数组，与 _config.tmp.yml 一致）
    [
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_agree.png',
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_look_down.png',
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_sunglasses.png',
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_pick_nose.png',
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_awkward.png',
      'https://testingcf.jsdelivr.net/npm/@waline/emojis/tieba/tieba_sleep.png'
    ]
  search: false         # 表情包搜索（默认 giphy 提供）
  imageUploader: false  # 图片上传（false 禁用，默认行为是 Base64 嵌入）
  meta: "['nick', 'mail', 'link']"   # 评论者可填字段
  requiredMeta: "['nick', 'mail']"   # 评论者必填字段
  recaptchaV3Key: ''    # reCAPTCHA v3 密钥（防垃圾，可选）
  highlight:
    enable: false            # 禁用 Waline 内置高亮
    custom_highlighter: |    # 自定义高亮函数（waline.ejs 读取 highlight.custom_highlighter）
      (code, lang) => { /* 用 Prism 高亮 */ }

以上为 waline.ejs 实际读取的键（serverURL/avatar/lang/dark/login/wordLimit/pageSize/pageview/comment/reaction/search/imageUploader/meta/requiredMeta/recaptchaV3Key/highlight.custom_highlighter）。Valine 专有键（enableQQ/recordIP/requiredFields/guest_info/count/visitor）waline.ejs 不读取，配置无效。

其他引擎（精简配置）：

切换引擎三步：① post.comments.type 改为目标引擎；② 填好上表对应配置键的必要参数；③ hexo clean && hexo generate 重新构建。GitHub 系引擎（Gitalk/Gitment）注意 OAuth 权限风险，建议优先 utterances/giscus 这类仅限单仓库的方案。

5.3 全部可调项

5.4 边界与冲突

• type 指向哪个引擎，就需要同时配置该插件的必要参数（如本博客的 waline.serverURL）。页面级开关用 front-matter comments: true/false（独立页/留言页/友链页同理）。
• Valine 专有键在 Waline 下不生效（waline.ejs 不读取）。
• §16 minWalineCommentCount 默认关闭，因为它与 waline.comment 重复请求评论数。
• Gitalk/Gitment 的 OAuth 权限过大，仅建议 utterances/giscus。

5.5 小结

• 最小可用：comments.enable + type: waline + waline.serverURL
• 想换 GitHub 评论：giscus，填 4 个 id
• 暗色不对：检查 waline.dark 选择器
• 单页不要评论：front-matter comments: false

6. 打赏（reward）

用途：文章末尾的打赏卡片，展示微信/支付宝收款码。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

6.1 如何启用

效果：文章正文结束后出现打赏卡片：一句标题，下方并排两张收款码（微信、支付宝），点击可放大查看。

对应配置（主题配置）：

post:
  reward:
    enable: true
    title: 码字辛苦，打赏作者！
    wechat: /medias_webp/reward/wechat.webp
    alipay: /medias_webp/reward/alipay.webp

6.2 常用选项

① 改文案

效果：卡片标题文字变化，收款码不变。

对应配置：

post:
  reward:
    title: 请我喝杯咖啡

② 换收款码

效果：对应渠道的二维码图片换成你自己的；支持填完整 URL 用网络图。

对应配置：

post:
  reward:
    wechat: https://example.com/wechat.png
    alipay: /medias_webp/reward/alipay.webp

③ 关闭打赏

效果：文末不再出现打赏卡片。

对应配置：

post:
  reward:
    enable: false

6.3 全部可调项

6.4 边界与冲突

• 收款码图片替换成自己的即可；支持网络图片（填完整 URL）。
• 两个渠道图片都缺失时卡片会出现空位，建议至少保留一张。

6.5 小结

• 最小可用：enable + 两张图
• 换自己的码：只改 wechat / alipay
• 不想露码：enable: false

7. 版权声明（copyright）

用途：文章底部版权卡片：作者、原文链接与转载许可协议。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

7.1 如何启用

效果：文章底部出现版权卡片，列出作者、原文链接与「署名-非商业性使用-相同方式共享」等协议名称。

对应配置（主题配置）：

post:
  copyright:
    enable: true
    license: 'cc_by_nc_sa'

7.2 常用选项

① 换全站默认协议

效果：所有文章的版权卡片显示新协议名称与链接。

对应配置：

post:
  copyright:
    license: 'cc_by_nc'

② 单篇覆盖协议

效果：只有该篇显示 cc_by_nc，其余文章仍用全局协议。

对应配置（文章 front-matter）：

reprintPolicy: cc_by_nc

③ 关闭版权卡片

效果：文末版权卡片消失。

对应配置：

post:
  copyright:
    enable: false

7.3 全部可调项

可用规则：cc_by、cc_by_nd、cc_by_sa、cc_by_nc、cc_by_nc_nd、cc_by_nc_sa（含义见 Creative Commons）。

7.4 边界与冲突

• front-matter reprintPolicy 优先级高于全局 license。
• 协议值拼写错误时卡片会显示原始字符串或回落默认（其他值未验证）。

7.5 小结

• 最小可用：enable: true
• 统一协议：改 license
• 单篇例外：front-matter reprintPolicy

内容渲染

8. 数学公式（math）

用途：文章内 $...$ / $$...$$ 公式渲染。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

8.1 如何启用

效果：正文里的 $E=mc^2$ 渲染成排版公式，$$...$$ 独立成行居中。

对应配置（主题配置）：

post:
  math:
    enable: true
    specific: true

配置项来源：post.mermaid.options 的内容原样传给 mermaid.initialize()（即 mermaidAPI 配置），因此 theme / startOnLoad / securityLevel / flowchart 等写法遵循 Mermaid 官方 mermaidAPI 文档。

8.2 常用选项

① 按需加载

效果：specific: true 时只有 front-matter 写了 mathjax: true 的文章才加载公式引擎，其他文章省掉这份 JS。

对应配置：

post:
  math:
    specific: true

② 单篇启用

效果：该篇公式正常渲染；没写这一行的文章即使全局 enable: true 也不加载。

对应配置（文章 front-matter）：

mathjax: true

③ 换渲染引擎

效果：公式排版细节换成 KaTeX 风格（加载更快、字体不同）。

对应配置：

post:
  math:
    engine: katex

8.3 全部可调项

8.4 边界与冲突

• specific: true 是本博客的推荐用法——文章不需要公式时不加载引擎，需要时 front-matter 加 mathjax: true（markdown-plugins.ejs 检查 page.mathjax）。
• 自定义页面（非文章）用公式同样要 front-matter 指定 mathjax: true。
• 改 engine 后必须 clean 构建，旧产物不会自动切换。

8.5 小结

• 最小可用：enable: true + specific: true
• 每篇要公式：front-matter mathjax: true
• 嫌 MathJax 慢：换 engine: katex

9. 流程图（mermaid）

用途：文章内 mermaid 流程图/时序图/甘特图渲染（```mermaid 代码块或 tag 插件）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

9.1 如何启用

效果：```mermaid 代码块被渲染成图（矩形节点 + 箭头），而不是显示源码。

对应配置（主题配置）：

post:
  mermaid:
    enable: true
    specific: true

9.2 常用选项

① 按需加载

效果：只有 front-matter 写 mermaid: true 的文章加载 mermaid 库，其余文章不付这份体积。

对应配置：

post:
  mermaid:
    specific: true

② 单篇启用

效果：该篇的 mermaid 块渲染成图。

对应配置（文章 front-matter）：

mermaid: true

③ 流程图不撑满容器

效果：图按自身宽度渲染、左侧对齐；改成 true 则横向撑满容器。

对应配置：

post:
  mermaid:
    options:
      flowchart:
        useMaxWidth: false

④ 甘特图尺寸

效果：甘特图行高与行间距变化，barHeight: 20 / barGap: 4 更紧凑。

对应配置：

post:
  mermaid:
    options:
      gantt:
        useMaxWidth: true
        barHeight: 20
        barGap: 4

9.3 全部可调项

9.4 边界与冲突

• mermaid 库加载较耗时，specific: true 时在文章 front-matter 写 mermaid: true 才启用（与 math 相同的按需加载模式）。
• theme 会被明暗模式动态覆盖，但可作为默认值。
• securityLevel: 'loose' 允许 HTML 标签，仅在信任内容来源时使用。

9.5 小结

• 最小可用：enable: true + specific: true
• 每篇要图：front-matter mermaid: true
• 图太宽：flowchart.useMaxWidth: false
• 暗色下图看不清：交给明暗模式覆盖，不要硬编码 theme

10. 其他文章页功能

用途：上下篇导航、时效提示、分类栏、浏览器推送、侧边栏广告。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

10.1 如何启用

效果：文章底部出现上一页/下一页卡片；侧边栏出现当前分类文章列表；满足条件的文章顶部出现时效提示条。

对应配置（主题配置）：

post:
  prev_next:
    enable: true
  category_bar:
    enable: true

10.2 常用选项

① 上下篇导航

效果：文章末尾出现「上一篇 / 下一篇」两张卡片，按发布时间相邻取文。

对应配置：

post:
  prev_next:
    enable: true

② 文章时效提示

效果：文章超过 warning_day 天显示黄色提醒，超过 error_day 天显示红色提醒。默认关闭。

对应配置：

post:
  outdate:
    enable: true
    warning_day: 365
    error_day: 3650

③ 侧边栏分类栏

效果：侧边栏列出当前文章所属分类下的其他文章。specific: true 时仅 front-matter 写了 category_bar: true 的文章才显示。

对应配置：

post:
  category_bar:
    enable: true
    specific: true
    post_order_by: '-date'
    post_limit: 0

④ 浏览器推送订阅

效果：文章详情页底部出现 webpushr 订阅按钮，读者授权后新文发布可收到浏览器通知。

对应配置：

post:
  webpush:
    enable: true

⑤ 侧边栏广告卡片

效果：侧边栏出现广告卡片（enable: false 的单条不显示）。

对应配置：

post:
  advertisements:
    - id: "ad-1"
      text: "广告文案"
      enable: true

10.3 全部可调项

10.4 边界与冲突

• post.webpush.enable: true 时，文章详情页底部（_partial/common/webpush）显示 webpushr 订阅按钮，读者点击授权后可在新文章发布时收到浏览器推送通知。需先在 app.webpushr.com 注册站点并注入订阅脚本（webpushr 站点 ID 配置在主题 head 模板中）。
• category_bar.specific: true 时，front-matter 必须写 category_bar: true，否则栏位不出现。
• post_order_by 的合法值与 Hexo 排序字段一致（-date、date、title 等），其他值未验证。

10.5 小结

• 最小可用：prev_next.enable: true
• 旧文提醒：开 outdate，按内容时效调两个阈值
• 侧边栏太挤：先关 category_bar 或 advertisements
• 推送要运维：webpush 依赖 webpushr 站点脚本

信息展示

11. 文章信息（postInfo）

用途：文章页信息栏的独立开关组——作者、日期、字数、总字数、阅读时长、阅读模式、阅读次数、评论数。与 §2 post.meta 是两套机制，postInfo 控制的是另一处信息展示。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

11.1 如何启用

效果：文章页信息栏出现多项元数据（作者、日期、更新日期、字数、全站总字数、时长、阅读模式按钮、阅读次数、评论数）。

对应配置（主题配置）：

postInfo:
  author: true
  date: true
  update: true
  wordCount: true
  totalCount: true
  min2read: true
  readMode: true
  readCount: true
  commentCount: true

11.2 常用选项

① 阅读模式按钮

效果：信息栏出现「阅读模式」入口，点击后隐藏侧边栏与干扰元素，只留正文。

对应配置：

postInfo:
  readMode: true

② 评论数

效果：信息栏显示该篇评论数量（目前仅 Waline 支持）。

对应配置：

postInfo:
  commentCount: true

③ 全站总字数

效果：显示 totalcount(site) 的结果（文章 + wiki 页，去重、加密文按明文计）。

对应配置：

postInfo:
  totalCount: true

④ 只留必要项

效果：信息栏只剩作者、日期、字数，界面更干净。

对应配置：

postInfo:
  author: true
  date: true
  wordCount: true
  update: false
  totalCount: false
  min2read: false
  readMode: false
  readCount: false
  commentCount: false

11.3 全部可调项

totalCount（totalcount(site)）统计范围为文章 + wiki 页：多语言版本去重（同一内容只计一次）、加密文章按明文计数。

11.4 边界与冲突

• 字数统计与阅读时长由主题内置 helper 提供（scripts/helpers/wordcount.js），无需额外安装插件。
• wordcount / min2read / totalcount 三个 helper 由主题自研，其中 totalcount 用于 footer 全站总字数（已包含 wiki 页面与加密文章的明文计数）。
• 与 §2 post.meta 同时开启会出现两处重复信息；建议只留一套。

11.5 小结

• 最小可用：author + date + wordCount
• 想沉浸阅读：开 readMode
• 评论数不显示：确认 postInfo.commentCount 与 waline.comment 都开
• 别和 post.meta 重复：二选一

12. 美化 hr 分割线（hr）

用途：文章内 --- 水平分割线的美化样式。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

12.1 如何启用

效果：Markdown 的 --- 从默认细线变成带装饰的美化分割线（居中装饰图形或渐变线）。

对应配置（主题配置）：

hr:
  enable: true

12.2 常用选项

① 关闭美化

效果：--- 恢复浏览器默认的细横线。

对应配置：

hr:
  enable: false

12.3 全部可调项

12.4 边界与冲突

• 开启后 Markdown 的 --- 渲染为带装饰的美化分割线，而非默认细线。
• 只影响正文 <hr>，不影响 front-matter 分隔符。

12.5 小结

• 最小可用：hr.enable: true
• 觉得花哨：保持默认 false

统计与验证

13. Gitment 评论（gitment）

用途：基于 GitHub Issues 的评论系统（Gitment）。默认关闭，本博客主用 Waline。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

13.1 如何启用

效果：文章底部出现 GitHub Issues 风格的评论区，读者用 GitHub 账号登录后评论。

对应配置（主题配置）：

gitment:
  enable: true
  owner: your-github-name
  repo: your-comments-repo
  oauth:
    clientId: your-client-id
    clientSecret: your-client-secret

13.2 常用选项

① 指定仓库

效果：评论写进 owner/repo 对应的 GitHub Issues，每篇文章一个 issue。

对应配置：

gitment:
  owner: your-github-name
  repo: your-comments-repo

② OAuth 凭据

效果：读者能登录并发表评论；填错时评论区只显示登录失败。

对应配置：

gitment:
  oauth:
    clientId: your-client-id
    clientSecret: your-client-secret

13.3 全部可调项

13.4 边界与冲突

• 启用需在 GitHub 创建 OAuth App 并填 owner/repo/clientId/clientSecret。
• 安全警告：Gitment/Gitalk 这类 OAuth App 权限过高（可读写授权者所有公共仓库），拿到 Token 的攻击者可清空你的公共仓库，官方不推荐使用——建议用 utterances 这类仅限单仓库的 GitHub App（见配置注释）。
• 与 post.comments.type 是两套入口：只有 type: gitment 时此段才真正接管评论区。

13.5 小结

• 最小可用：enable + owner + repo + OAuth 两值
• 安全优先：改用 utterances/giscus
• 不确定就别开：保持默认 false

14. 腾讯人机验证（tcaptcha）

用途：评论提交前的腾讯验证码（滑块/点选），防垃圾评论。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

14.1 如何启用

效果：点击评论提交后弹出滑块或点选验证，通过后才写入评论。

对应配置（主题配置）：

tcaptcha:
  enable: true
  appid: 2057160203

14.2 常用选项

① 填自己的 appid

效果：验证码使用你腾讯云账号下的验证码配置；appid 不属于你的站点时验证直接失败。

对应配置：

tcaptcha:
  appid: 你的 appid

14.3 全部可调项

14.4 边界与冲突

• 目前只适配和测试了 Valine，其他评论系统未调试验证。
• 需先在腾讯云验证码控制台创建验证码获取 appid，介绍见官方文档。

14.5 小结

• 最小可用：enable + appid
• 用 Waline：此项不适用（仅 Valine 验证过）
• 没备案/没控制台：保持关闭

15. Waline 全站计数器（minWalineCount）

用途：页脚全站 PV（浏览量）统计，由 Waline 服务提供。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

15.1 如何启用

效果：页脚出现「全站访问 N 次」的数字，随访问增长。

对应配置（主题配置）：

minWalineCount:
  enable: true
  serverURL: 'https://waline.17lai.site'
  pageview: true

15.2 常用选项

① 换服务地址

效果：计数从你的 Waline 实例读取；地址错误则数字不显示或一直为 0。

对应配置：

minWalineCount:
  serverURL: 'https://your-waline.example.com'

② 关闭页脚计数

效果：页脚不再显示全站 PV。

对应配置：

minWalineCount:
  enable: false

15.3 全部可调项

15.4 边界与冲突

• 页脚"全站 PV"由 walineCount.ejs 从 Waline 服务拉取并更新。
• 需要 pageview: true 才会累计；只开 enable 不产生数据。
• 与 §16 是两个独立计数器，可只开其一。

15.5 小结

• 最小可用：enable + serverURL + pageview
• 数字为 0：检查服务端是否可访问
• 不想暴露 PV：enable: false

16. Waline 评论计数器（minWalineCommentCount）

用途：全站评论总数统计。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

16.1 如何启用

效果：页脚或统计区出现全站评论总数。

对应配置（主题配置）：

minWalineCommentCount:
  enable: true
  serverURL: 'https://waline.17lai.site'
  comment: true

16.2 常用选项

① 保持关闭（推荐）

效果：评论计数仍由 waline.ejs（theme.waline.comment）提供，不产生重复请求。

对应配置：

minWalineCommentCount:
  enable: false

16.3 全部可调项

16.4 边界与冲突

• 默认关闭——评论计数已由 waline.ejs（theme.waline.comment）承担，开启会重复请求。
• 若要全站汇总数（而非单篇），再打开此项。

16.5 小结

• 默认就好：保持 enable: false
• 要全站汇总：enable + comment + serverURL
• 别和 waline.comment 同时开：重复请求

17. 文章密码验证（verifyPassword）

用途：为指定文章设置访问密码，输入正确密码才能阅读。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

17.1 如何启用

效果：打开加密文章时正文被遮罩，弹出密码输入框；输错提示「密码错误，将返回主页！」。

对应配置（主题配置）：

verifyPassword:
  enable: true
  promptMessage: 请输入访问本文章的密码
  errorMessage: 密码错误，将返回主页！

17.2 常用选项

① 给文章设密码

效果：该篇文章打开即要求输入密码，输入正确后解密显示正文。

对应配置（文章 front-matter）：

password: "你的密码"

② 改提示文案

效果：密码框上方与错误弹窗的文字变化。

对应配置：

verifyPassword:
  promptMessage: 请输入密码
  errorMessage: 密码错误

③ 内容片段加密

效果：只遮住文章中的一段内容，其余正文正常显示；适合隐藏配置片段。

对应配置（正文中）：

{% encrypt 密码 "标题" "简介" %}...{% endencrypt %}

④ Wiki 整体加密

效果：整个 wiki 栏目需要密码才能进入。

对应配置（source/_data/{wiki}-sidebar.yml）：

encrypt_password: "你的密码"

17.3 全部可调项

文章 front-matter（2026-08-09 起自研 HBE v4，密码直接明文，不再要求 SHA256 密文）：

password: "你的密码"      # 直接写明文密码

17.4 边界与冲突

• 自研 HBE v4 体系（2026-08-09 替代 hexo-blog-encrypt 插件）——服务端 AES-256-GCM 加密，密文存 HTML（无明文泄漏），前端 WebCrypto 解密。front-matter password 直接写明文即可（不再需要 SHA256 预加密）。
• 其他加密方式：
  • 内容片段加密：{% encrypt 密码 "标题" "简介" %}...{% endencrypt %}（段落级，支持内部 tag，详见「tag 插件」篇 §15）
  • Wiki 整体加密：{wiki}-sidebar.yml 加 encrypt_password（详见「布局与页面」篇 §8）
  • 密码存储：autoSave 存派生 dk（非密码/明文），1 天 TTL
• 解密后刷新（2026-09-09）：解密完成后正文中的组件统一重新初始化（post/wiki/相册共用，hbe-bundle onSuccess 触发）——代码块 toolbar（codeWidget）、图片灯箱（articleInit）、mermaid/进度条（events.refresh）、布局（boot.refresh）。无需手动刷新页面，各组件幂等（data-processed 防重复）。

17.5 小结

• 最小可用：verifyPassword.enable + front-matter password
• 只藏一段：用 encrypt tag，不加密整篇
• 整栏加密：{wiki}-sidebar.yml 的 encrypt_password
• 密码写明文：HBE v4 不再需要 SHA256

分享与推荐

18. 文章分享（sharejs）

用途：文章底部分享按钮，支持多平台。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

18.1 如何启用

效果：文章底部出现一排分享图标（Twitter、Facebook、QQ、微博等），点击把当前文章分享到对应平台。

对应配置（主题配置）：

sharejs:
  enable: true
  sites: twitter,facebook,qq,qzone,wechat,weibo,douban

18.2 常用选项

① 选择平台

效果：只显示 sites 里列出的平台图标；删掉某个平台，对应图标消失。

对应配置：

sharejs:
  sites: qq,wechat,weibo,douban

② 关闭分享

效果：文末不再出现分享图标。

对应配置：

sharejs:
  enable: false

18.3 全部可调项

18.4 边界与冲突

• sites 为逗号分隔的平台列表，可选：twitter, facebook, google, qq, qzone, wechat, weibo, douban, linkedin。
• 与 §19 AddThis 是替代关系，同时开启会显示两套分享入口。

18.5 小结

• 最小可用：enable: true + sites
• 国内读者为主：留 qq,wechat,weibo,douban
• 和 AddThis 二选一

19. AddThis 分享（addthis）

用途：基于 AddThis 的分享模块（sharejs 的替代方案）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

19.1 如何启用

效果：文章底部出现 AddThis 的分享条（侧边悬浮或横排，取决于 AddThis 配置）。

对应配置（主题配置）：

addthis:
  enable: true
  pubid: 613a04428f842fe1

19.2 常用选项

① 填自己的 pubid

效果：分享数据统计进你的 AddThis 账号；pubid 无效时分享条不加载。

对应配置：

addthis:
  pubid: 你的 pubid

19.3 全部可调项

19.4 边界与冲突

• 与 sharejs 二选一，enable: true 时用 AddThis 分享；pubid 在 AddThis 官网注册后获取。
• 两者同时开启会出现两套分享入口。

19.5 小结

• 最小可用：enable + pubid
• 已用 sharejs：保持 false
• 要统计：先注册 AddThis

20. 相关文章推荐（related_posts）

用途：文章底部展示相关文章推荐列表。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

20.1 如何启用

效果：文章末尾出现「相关文章推荐」区块，按标签/分类相似度列出若干篇文章卡片。

对应配置（主题配置）：

related_posts:
  enable: true
  title: 相关文章推荐

20.2 常用选项

① 推荐数量

效果：底部最多列出 5 篇；改小则列表更短，改大则更长。

对应配置：

related_posts:
  params:
    maxCount: 5

② 显示日期/图片/摘要

效果：卡片上多出日期、封面图或摘要文字；全 false 时只有标题。

对应配置：

related_posts:
  params:
    isDate: true
    isImage: true
    isExcerpt: true

③ 首页也显示

效果：首页文章卡片下方也出现相关推荐。

对应配置：

related_posts:
  display_in_home: true

20.3 全部可调项

20.4 边界与冲突

• 基于标签/分类相似度推荐；display_in_home: true 时首页文章卡片也显示相关推荐。
• PPMixingRate 控制热门与相似的混合比例，改动效果需按内容实测（其他值未验证）。

20.5 小结

• 最小可用：enable: true
• 卡片太素：开 isImage / isExcerpt
• 首页太挤：display_in_home: false

21. LeanCloud 阅读数（leancloud_visitors）

用途：基于 LeanCloud 的文章阅读数统计（post.meta.views.source: leancloud 时的数据源）。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

21.1 如何启用

效果：文章元信息里的「N 次阅读」由 LeanCloud 计数，刷新页面数字递增。

对应配置（主题配置）：

leancloud_visitors:
  enable: true
  app_id: your-app-id
  app_key: your-app-key

并确认：

post:
  meta:
    views:
      source: leancloud

21.2 常用选项

① 换应用凭据

效果：计数写入你自己的 LeanCloud 应用；凭据错误时阅读数不显示。

对应配置：

leancloud_visitors:
  app_id: your-app-id
  app_key: your-app-key

21.3 全部可调项

21.4 边界与冲突

• 启用后需在 §2 post.meta.views.source 设为 leancloud 才生效；本博客默认用 umami，此配置保留备用。
• app_key 会出现在前端产物中，LeanCloud 应用应设置为只读/受限权限。

21.5 小结

• 最小可用：enable + 两个凭据 + source: leancloud
• 主用 umami：本段可保持关闭
• 注意权限：前端可见 app_key

22. Google AdSense（googleAd）

用途：文章页 Google AdSense 广告位。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

22.1 如何启用

效果：文章页出现 AdSense 广告位（未审核通过时显示空白）。

对应配置（主题配置）：

googleAd:
  enable: true
  adClient: "ca-pub-2899930387274309"

22.2 常用选项

① 换发布商 ID

效果：广告归入你的 AdSense 账号结算；ID 错误时广告不加载。

对应配置：

googleAd:
  adClient: "ca-pub-你的ID"

22.3 全部可调项

22.4 边界与冲突

• adClient 为 AdSense 发布商 ID（ca-pub- 开头），在 Google AdSense 注册后获取。
• 配置注释标注"还未完善"。

22.5 小结

• 最小可用：enable + adClient
• 未注册：保持 false
• 功能未完善：上线前先小范围验证

附：文章页配置速查表

阅读顺序建议：先按 §1–§12 把页面主体配出来（头图、元信息、目录、评论、版权、公式），再按 §13–§22 逐个接统计与分享。每节只改一个 enable 就能看到效果，出问题先回滚该节的配置。