加载中...

文章页配置

本页讲解文章页的配置：头图、标题下方元信息（日期/字数/阅读时长/阅读数）、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 覆盖全局设置。

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（独立页/留言页/友链页同理）。

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 同级，post 直接子键）

单篇文章 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 写 math: true 的文章启用（省加载）
    engine: mathjax         # 引擎：mathjax | katex

说明：specific: true 是本博客的推荐用法——文章不需要公式时不加载引擎，需要时 front-matter 加 math: true。自定义页面（非文章）用公式同样要 front-matter 指定 math: 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 才展示
    placement: left
  advertisements:       # 侧边栏广告卡片（数组，可多条启停）
    - id: "ad-1"
      text: "广告文案"
      enable: true

附：文章页配置速查表

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