Hexo Keep主题Front-matter 详解

Front-Matter 是指位于 Markdown 文件（通常在 source/_posts/ 目录下）最上方，并由 --- 分隔的 YAML 或 JSON 配置区域。它用于为你的文章设置各种元数据和特定行为。

在 Hexo 中，Front-Matter 是一个非常重要的部分，它允许你为每篇文章或页面设置标题、日期、标签、分类等信息，以及控制文章的显示方式和功能。

---
title: 文章标题示例
date: 2024-05-29 10:00:00
updated: 2024-05-30 14:30:00 # 可选，文章更新时间
tags:
  - Hexo
  - Keep主题
  - 教程
categories:
  - 技术分享 # 一级分类
  - 前端开发 # 二级分类，表示文章属于“技术分享”下的“前端开发”
author: Roo # 可选，文章作者，若不填则使用全局配置
excerpt: "这是一段文章的简短摘要，会显示在列表页..." # 可选，手动设置摘要
sticky: 1 # 数字越大，置顶越靠前
katex: true # 是否启用 KaTeX 数学公式渲染
toc: true # 是否显示文章目录 (Keep 主题通常默认 true)
comment: true # 是否开启评论功能 (Keep 主题通常默认 true)
copyright_info: true # 是否显示版权信息 (Keep 主题通常默认 true)
share: true # 是否开启分享功能 (Keep 主题通常默认 true)
reward: true # 是否开启打赏功能 (Keep 主题通常默认 true)
aging: false # 是否开启文章时效提示 (Keep 主题特定)
aging_days: 365 # 时效提示天数 (与 aging: true 配合使用)
home_cover: /images/covers/home-example.jpg # 首页封面图片 (Keep 主题特定)
home_cover_height: 200 # 首页封面高度 (Keep 主题特定)
post_cover: /images/covers/post-example.jpg # 文章页封面图片 (Keep 主题特定)
post_cover_height: 300 # 文章页封面高度 (Keep 主题特定)
password: "" # 文章访问密码 (需配合 hexo-blog-encrypt 等插件)
code_block_shrink: false # 代码块是否默认折叠 (Keep 主题特定)
# 你可以根据需要添加或移除这些配置项
---

通过配置 Front-Matter，你可以实现诸如设置文章封面、文章置顶、开启文章时效提示、控制版权信息显示、管理目录 (TOC) 和评论功能等多种自定义效果。

Front-matter 配置项详解

以下是常用的 Front-Matter 配置项及其在 Hexo 和 Keep 主题中的说明和用法：

• title: (字符串)

  • 含义: 文章的标题。这是最重要的字段之一，会显示在文章页面、列表页以及浏览器的标题栏中。
  • 示例: title: 我的第一篇博客文章

• date: (日期时间字符串)

  • 含义: 文章的发布日期和时间。Hexo 会根据这个日期对文章进行排序，并可能用于生成文章的永久链接（取决于 permalink 配置）。
  • 格式: YYYY-MM-DD HH:mm:ss
  • 示例: date: 2024-05-29 10:00:00

• updated: (日期时间字符串, 可选)

  • 含义: 文章的更新日期和时间。如果未提供，通常会使用 date 的值或文件的最后修改时间（取决于主题和配置）。
  • 格式: YYYY-MM-DD HH:mm:ss
  • 示例: updated: 2024-05-30 14:30:00

• tags: (数组)

  • 含义: 文章的标签。用于对文章进行标记和归类，方便读者查找相关内容。
  • 格式推荐:

    tags:
      - 标签A
      - 标签B

  • 示例:

    tags:
      - Hexo
      - Keep主题
      - Web开发

• categories: (数组)

  • 含义: 文章的分类。支持层级结构，用于系统地组织文章。Hexo 中，分类是有序的，而标签是无序的。
  • 格式推荐 (支持层级):

    categories:
      - 主分类
      - 子分类 # 表示文章属于“主分类”下的“子分类”

  • 示例:

    categories:
      - 技术教程
      - 前端开发

• sticky: (数字)

  • 含义: 设置文章在首页（Home）的置顶顺序。sticky 值越大，文章在置顶列表中的位置越靠前。
  • 示例:

    ---
    title: 重要公告
    sticky: 999 # 一个较大的数字使其更靠前
    ---

  • 提示: 如果多篇文章设置了 sticky，它们会按照 sticky 值的降序排列在普通文章之前。

• copyright_info: (布尔值)

  • 含义: 控制是否在文章底部显示版权信息。可以为转载的文章单独关闭版权声明。
  • 默认行为 (Keep 主题): 通常默认开启 (true)。设置为 false 时会关闭该篇文章的版权信息。
  • 示例:

    ---
    copyright_info: false # 关闭本篇文章的版权信息
    ---

• toc: (布尔值)

  • 含义: 控制是否为当前文章生成并显示内容目录 (Table of Contents)。
  • 默认行为 (Keep 主题): 通常默认开启 (true)。设置为 false 时会关闭该篇文章的 TOC。
  • 示例:

    ---
    toc: false # 不显示本篇文章的目录
    ---

• comment: (布尔值)

  • 含义: 控制是否为当前文章开启评论功能。
  • 默认行为 (Keep 主题): 通常默认开启 (true)，前提是已正确配置全局评论系统。设置为 false 时会关闭该篇文章的评论区。
  • 示例:

    ---
    comment: false # 禁止本篇文章评论
    ---

• aging: (布尔值) (Keep 主题 v3.6.0+)

  • 含义: 是否为当前文章开启时效性提示。如果开启，当文章的最后更新日期超过 aging_days 指定的天数时，会在文章开头显示一条提示信息。
  • 配合使用: 必须与 aging_days 一同配置。
  • 示例:

    ---
    aging: true
    aging_days: 180 # 超过180天未更新则提示
    ---

• aging_days: (数字) (Keep 主题 v3.6.0+)

  • 含义: 设置文章时效性提示的天数阈值。仅当 aging: true 时生效。
  • 示例: (见上方 aging 示例)

• home_cover: (字符串 - 图片路径/URL) (Keep 主题 v3.8.0+)

  • 含义: 设置文章在首页（Home）列表中的封面图片。可以是本地图片路径（相对于 source 目录）或完整的图片 URL。
  • 配合使用: 可选地与 home_cover_height 配合使用来指定封面高度。
  • 注意 (Keep 主题): 如果只填写了 home_cover 而未填写 post_cover，那么文章详情页（Post）的封面也会使用 home_cover 的图片。
  • 示例:

    ---
    home_cover: /images/covers/my-awesome-post.jpg
    # home_cover_height: 200 # 可选，指定高度
    ---

• home_cover_height: (数字 或 字符串) (Keep 主题 v3.8.0+)

  • 含义: 设置首页文章封面的高度。可以是数字（代表像素）或带单位的字符串。如果不填，Keep 主题会使用内置的默认高度。
  • 示例: home_cover_height: 150 或 home_cover_height: '30vh'

• post_cover: (字符串 - 图片路径/URL) (Keep 主题 v3.8.0+)

  • 含义: 设置文章详情页（Post）顶部的封面图片。
  • 配合使用: 可选地与 post_cover_height 配合使用。
  • 示例:

    ---
    post_cover: /images/banners/post-specific-banner.png
    # post_cover_height: 300 # 可选
    ---

• post_cover_height: (数字 或 字符串) (Keep 主题 v3.8.0+)

  • 含义: 设置文章详情页封面的高度。如果不填，Keep 主题会使用内置的默认高度。
  • 示例: post_cover_height: 250

• share: (布尔值) (Keep 主题 v3.8.0+)

  • 含义: 控制是否为当前文章启用分享功能。
  • 默认行为 (Keep 主题): 通常默认开启 (true)。设置为 false 时会关闭该篇文章的分享按钮。
  • 示例:

    ---
    share: false # 关闭本篇文章的分享功能
    ---

• reward: (布尔值) (Keep 主题 v3.8.0+)

  • 含义: 控制是否为当前文章启用打赏作者功能。
  • 默认行为 (Keep 主题): 通常默认开启 (true)，前提是已正确配置全局打赏信息。设置为 false 时会关闭该篇文章的打赏入口。
  • 示例:

    ---
    reward: false # 关闭本篇文章的打赏功能
    ---

• password: (字符串)

  • 含义: 为当前文章设置访问密码。这通常需要配合 Hexo 加密插件使用，如 hexo-blog-encrypt。设置后，读者需要输入正确的密码才能查看文章内容。
  • 使用 hexo-blog-encrypt 插件:
    1. 安装插件:

       cd your-hexo-site # 进入你的 Hexo 博客根目录
       npm install hexo-blog-encrypt --save
       # 或者使用 yarn: yarn add hexo-blog-encrypt

    2. 在文章 Front-Matter 中配置:

       ---
       title: 这是一篇加密文章
       password: YourSecurePasswordHere
       # ... 其他配置
       ---

  • 示例: password: P@$$wOrd123!

• katex: (布尔值)

  • 含义: 是否为当前文章启用 KaTeX 数学公式渲染。如果设置为 true，你就可以在文章中使用 LaTeX 语法来书写和显示数学公式。Keep 主题通常会内置或推荐 KaTeX/MathJax 支持。
  • 示例: katex: true

• author: (字符串, 可选)

  • 含义: 指定当前文章的作者。如果未在此处指定，Hexo 通常会使用站点配置文件 _config.yml 中定义的全局 author。
  • 示例: author: Guest Writer

• code_block_shrink: (布尔值 或 字符串, Keep 主题特定)

  • 含义: Keep 主题提供的用于控制代码块是否默认折叠或有特定显示样式的配置。具体可选值（如 true, false, auto）及其行为请查阅 Keep 主题的官方文档。
  • 示例: code_block_shrink: true (可能表示默认折叠长代码块)

• excerpt: (字符串, 可选)

  • 含义: 为文章手动设置摘要。如果设置了此字段，其内容将优先作为文章摘要显示。另一种方式是在文章正文中使用 <!-- more --> 标记，该标记之前的内容会自动成为摘要（除非 excerpt 字段已定义）。
  • 示例: excerpt: 这是对文章核心内容的简短总结，会显示在列表页。

重要提示:

• YAML 语法: Front-Matter 主要使用 YAML 语法，对缩进非常敏感。请确保键值对之间的冒号后有空格，并且数组等格式正确。
• 主题依赖性: 很多 Front-Matter 配置项的行为（尤其是外观和特定功能）高度依赖于你所使用的 Hexo 主题（如 Keep 主题）。不同主题支持的配置项和默认行为可能有所不同。
• 查阅文档: 建议始终查阅 Hexo 的官方文档以及你所使用主题（例如 Keep 主题）的最新文档，以获取最准确、最全面的配置项说明和用法示例。
• 空值行为: 对于那些在 Front-Matter 中留空（例如 sticky: 后面没有值）的配置项，其行为通常由 Hexo 或主题的默认设置决定。

希望这份详解能帮助你更好地使用 Hexo 和 Keep 主题的 Front-Matter 功能！😊