文章页配置

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

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

1. 文章页头图

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

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

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

单篇文章可在 front-matter 用 banner_img 覆盖全局设置。

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

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

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

2. 元信息（meta）

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

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

post:
  meta:
    author:                 # 作者（优先 front-matter author，其次站点 author）
      enable: false
    date:                   # 文章日期（优先 front-matter date，其次 md 文件日期）
      enable: true
      format: "LL a"        # ISO-8601 日期格式
    wordcount:              # 字数统计
      enable: true
    min2read:               # 阅读时长估算
      enable: true
      awl: 2                # 每字词平均长度：中文≈2，英文≈5
      wpm: 60               # 每分钟阅读字数（技术文章可调低）
    views:                  # 浏览量计数
      enable: true
      source: "umami"       # 数据源：busuanzi | leancloud | umami | waline

说明：post.meta.views.source 决定浏览量从哪来——本博客用 umami（自建统计），也可换不蒜子（busuanzi，零配置）或 Waline 评论的浏览量。

3. 更新时间提示（updated）

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

配置（主题配置）：

post:
  updated:
    enable: false             # 默认关闭
    date_format: "LL a"       # ISO-8601 格式
    relative: false           # true 时显示相对时间（"3 天前"）
    note_class: info          # 提示样式：default | primary | info | success | warning | danger | light

4. TOC 目录

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

配置（主题配置，post.toc 段）：

post:
  toc:
    enable: true                        # 全局开关
    placement: right                    # 目录位置：left | right
    headingSelector: "h1,h2,h3,h4,h5,h6" # 参与目录的标题级别
    collapseDepth: 0                    # 折叠深度（0 全部折叠，>0 有下级则默认展开）
    showToggleBtn: true                 # 显示展开/收缩按钮

单篇文章关闭：front-matter 加 toc: false。

5. 评论（comments）

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

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

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

说明：type 指向哪个引擎，就需要同时配置该插件的必要参数（如本博客的 waline.serverURL，见「布局与页面」篇）。页面级开关用 front-matter comments: true/false（独立页/留言页/友链页同理）。

5.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 不读取，配置无效。

其他引擎（精简配置）：

引擎	配置键	必要参数	说明
Valine	`valine`	`appId`/`appKey`/`serverURLs`（专有键 `enableQQ`/`recordIP`/`requiredFields`/`guest_info`/`count`/`visitor`）	旧版评论（Waline 前身），参数与 Waline 同源，需 LeanCloud 凭据；推荐用 Waline
Gitalk	`gitalk`	`owner`/`repo`/`oauth.clientId`/`oauth.clientSecret`/`admin`	基于 GitHub Issues；OAuth App 权限过高，官方不推荐
Gitment	`gitment`	`owner`/`repo`/`oauth.clientId`/`oauth.clientSecret`	基于 GitHub Issues；同 Gitalk 的安全问题（见 §13）
Disqus	`disqus`	`shortname`	国外主流评论服务，国内访问不稳定
Livere	`livere`	`uid`	来必力（韩国），国内可用
Changyan	`changyan`	`appId`/`conf`	畅言（搜狐），需网站备案
Twikoo	`twikoo`	`envId`（可选 `region`/`path`）	腾讯云开发部署，教程见 twikoo.js.org
Cusdis	`cusdis`	`host`/`app_id`/`lang`	第三方或自托管，见 cusdis.com
Giscus	`giscus`	`repo`/`repo-id`/`category`/`category-id`（可选 `mapping`/`theme-light`/`theme-dark`/`lang`）	基于 GitHub Discussions，见 giscus.app
Remark42	`remark42`	`host`/`site_id`（可选 `max_shown_comments`/`locale`/`components`）	需自托管服务端，见 remark42.com
Discuss	`discuss`	`serverURLs`/`path`	自托管、多平台多数据库，见 discuss.js.org
Utterances	`utterances`	`repo`/`label`（可选 `issue_term`/`theme`/`theme_dark`）	基于 GitHub Issues 的轻量评论，需 GitHub 仓库，见 utteranc.es

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

6. 打赏（reward）

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

配置（主题配置）：

post:
  reward:
    enable: true
    title: 码字辛苦，打赏作者！
    wechat: /medias_webp/reward/wechat.webp   # 微信收款码图片
    alipay: /medias_webp/reward/alipay.webp   # 支付宝收款码图片

说明：收款码图片替换成自己的即可；支持网络图片（填完整 URL）。

7. 版权声明（copyright）

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

配置（主题配置）：

post:
  copyright:
    enable: true           # 显示版权声明
    license: 'cc_by_nc_sa' # 默认转载规则（copyright 子键，全站生效）

单篇文章 front-matter 覆盖：

reprintPolicy: cc_by_nc   # 本篇改为"署名-非商业性使用"

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

8. 数学公式（math）

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

配置（主题配置）：

post:
  math:
    enable: false           # 开启后文章默认可用
    specific: true          # true 时仅 front-matter 写 mathjax: true 的文章启用（省加载）
    engine: mathjax         # 引擎：mathjax | katex

说明：specific: true 是本博客的推荐用法——文章不需要公式时不加载引擎，需要时 front-matter 加 mathjax: true（markdown-plugins.ejs 检查 page.mathjax）。自定义页面（非文章）用公式同样要 front-matter 指定 mathjax: true。

9. 流程图（mermaid）

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

配置（主题配置）：

post:
  mermaid:
    enable: true            # 开启后文章默认可用
    specific: true          # true 时仅 front-matter 写 mermaid: true 的文章启用
    options:                # mermaidAPI 配置
      theme: 'default'      # 主题（会被明暗模式动态覆盖）
      startOnLoad: true
      securityLevel: 'loose'
      flowchart:
        useMaxWidth: false  # 流程图中不撑满容器
      gantt:
        useMaxWidth: true
        barHeight: 20
        barGap: 4

说明：mermaid 库加载较耗时，specific: true 时在文章 front-matter 写 mermaid: true 才启用（与 math 相同的按需加载模式）。theme 会被明暗模式动态覆盖，但可作为默认值。

10. 其他文章页功能

post 段还包含（详见「布局与页面」篇）：

post:
  prev_next:
    enable: true        # 上下篇导航卡片
  outdate:              # 文章时效提示（默认关闭）
    enable: false
    warning_day: 365
    error_day: 3650
  category_bar:         # 侧边栏展示当前分类下的文章
    enable: true
    specific: true      # true 时仅 front-matter 写 category_bar: true 才展示
    post_order_by: '-date'  # 示例：按日期倒序（主题默认配置为 title 排序）
    post_limit: 0       # 显示条数上限（0 不限制）
  webpush:              # 浏览器推送订阅按钮（webpushr）
    enable: true
  advertisements:       # 侧边栏广告卡片（数组，可多条启停）
    - id: "ad-1"
      text: "广告文案"
      enable: true

浏览器推送订阅（webpush）：post.webpush.enable: true 时，文章详情页底部（_partial/webpush）显示 webpushr 订阅按钮，读者点击授权后可在新文章发布时收到浏览器推送通知。需先在 app.webpushr.com 注册站点并注入订阅脚本（webpushr 站点 ID 配置在主题 head 模板中）。

11. 文章信息（postInfo）

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

配置（主题配置）：

postInfo:
  author: true        # 作者
  date: true          # 发布日期
  update: true        # 更新日期
  wordCount: true     # 文章字数统计
  totalCount: true    # 站点总文章字数
  min2read: true      # 文章阅读时长
  readMode: true      # 是否开启文章阅读模式
  readCount: true     # 文章阅读次数
  commentCount: true  # 评论个数（目前支持 waline）

说明：启用前需安装 hexo-wordcount 插件（npm i --save hexo-wordcount），否则字数统计相关项不生效。

12. 美化 hr 分割线（hr）

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

配置（主题配置）：

hr:
  enable: false   # false | true

说明：开启后 Markdown 的 --- 渲染为带装饰的美化分割线，而非默认细线。

13. Gitment 评论（gitment）

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

配置（主题配置）：

gitment:
  enable: false
  owner:            # GitHub 用户名
  repo:             # 存放评论的仓库名
  oauth:
    clientId:       # GitHub OAuth App Client ID
    clientSecret:   # GitHub OAuth App Client Secret

说明：启用需在 GitHub 创建 OAuth App 并填 owner/repo/clientId/clientSecret。安全警告：Gitment/Gitalk 这类 OAuth App 权限过高（可读写授权者所有公共仓库），拿到 Token 的攻击者可清空你的公共仓库，官方不推荐使用——建议用 utterances 这类仅限单仓库的 GitHub App（见配置注释）。

14. 腾讯人机验证（tcaptcha）

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

配置（主题配置）：

tcaptcha:
  enable: false
  appid: 2057160203   # 你的 appid

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

15. Waline 全站计数器（minWalineCount）

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

配置（主题配置）：

minWalineCount:
  enable: true
  serverURL: 'https://waline.17lai.site'
  pageview: true   # 浏览量统计 v2

说明：页脚"全站 PV"由 walineCount.ejs 从 Waline 服务拉取并更新。

16. Waline 评论计数器（minWalineCommentCount）

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

配置（主题配置）：

minWalineCommentCount:
  enable: false
  serverURL: 'https://waline.17lai.site'
  comment: true   # 评论量统计 v2

说明：默认关闭——评论计数已由 waline.ejs（theme.waline.comment）承担，开启会重复请求。

17. 文章密码验证（verifyPassword）

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

配置（主题配置）：

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

文章 front-matter（密码必须是 SHA256 加密后的密文）：

password: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8

说明：为保证密码原文不泄露到网页，front-matter 的 password 必须是 SHA256 密文（可用 echo -n "明文" | sha256sum 生成）。与「布局与页面」篇的 hexo-blog-encrypt 加密是两套独立机制。

18. 文章分享（sharejs）

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

配置（主题配置）：

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

说明：sites 为逗号分隔的平台列表，可选：twitter, facebook, google, qq, qzone, wechat, weibo, douban, linkedin。

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

配置（主题配置）：

addthis:
  enable: false
  pubid: 613a04428f842fe1   # 前往 https://www.addthis.com/ 获取

说明：与 sharejs 二选一，enable: true 时用 AddThis 分享；pubid 在 AddThis 官网注册后获取。

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

配置（主题配置）：

related_posts:
  enable: false
  title: 相关文章推荐   # 自定义标题，留空用默认
  display_in_home: false  # 是否在首页显示
  params:
    maxCount: 5       # 最大推荐数
    PPMixingRate: 0.25 # 混合比例
    isDate: false     # 是否显示日期
    isImage: false    # 是否显示图片
    isExcerpt: false  # 是否显示摘要

说明：基于标签/分类相似度推荐；display_in_home: true 时首页文章卡片也显示相关推荐。

21. LeanCloud 阅读数（leancloud_visitors）

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

配置（主题配置）：

leancloud_visitors:
  enable: true
  app_id: v2hJTCLDHLnGF4iSJkBJ8mga-MdYXbMMI
  app_key: Hu4UNHLVERHkhfH6G5xqdqN3

说明：启用后需在 §2 post.meta.views.source 设为 leancloud 才生效；本博客默认用 umami，此配置保留备用。

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

配置（主题配置）：

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

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

附：文章页配置速查表

配置项	位置	说明
文章头图	`post.banner_img` 等	front-matter `banner_img` 单篇覆盖
作者/日期	`post.meta.author` / `post.meta.date`	日期格式 `"LL a"`
字数/时长	`post.meta.wordcount` / `post.meta.min2read`	awl 2 / wpm 60
阅读数	`post.meta.views`	数据源 umami/busuanzi/leancloud/waline
更新时间	`post.updated`	默认关闭，front-matter `updated` 指定
TOC	`post.toc`	front-matter `toc: false` 单篇关闭
评论	`post.comments`	`type: waline`，front-matter `comments` 控制
打赏	`post.reward`	微信/支付宝收款码
版权	`post.copyright`（含 `license` 子键）	front-matter `reprintPolicy` 单篇覆盖
公式	`post.math`	`specific: true` + front-matter `mathjax: true`
流程图	`post.mermaid`	`specific: true` + front-matter `mermaid: true`
上下篇/时效/分类栏/广告	`post.prev_next` / `outdate` / `category_bar` / `advertisements`	见「布局与页面」篇