目录结构与内容管理

1. 博客目录结构

一个 Hexo + matery 站点的典型布局（本博客为参考）：

blog/
├── _config.yml              # 站点配置（Hexo 核心 + 全部插件配置）
├── package.json             # 依赖与 npm 脚本
├── source/                  # ★ 内容与独立页面
│   ├── _posts/              #   文章（Markdown）
│   ├── _drafts/             #   草稿（render_drafts: false，默认不渲染）
│   ├── _data/               #   数据文件（友链/相册/侧栏等，单点维护）
│   ├── _template/           #   可复用的 Markdown 片段
│   ├── about/               #   独立页面（每个一个目录 + index.md）
│   ├── tags/
│   ├── categories/
│   ├── friends/
│   ├── galleries/
│   └── ...                  #   其他独立页面（msg、nav、docs 等）
├── scaffolds/               # hexo new 使用的模板（post/page/draft/gallery）
├── themes/
│   └── matery/              # 主题（layout 模板 + source 静态资源 + scripts）
├── tools/                   # CI/CD 脚本与工具链（本博客定制）
├── userConfig/              # 用户配置与构建模板（本博客定制）
└── public/                  # 构建输出（hexo generate 生成，勿手改）

关键约定：

source/ 下的 Markdown 都会渲染为 HTML；独立页面需要 front-matter 指定 layout（如 layout: about），否则按默认 post 布局渲染
public/ 是构建产物，hexo clean 会删除，不要手动编辑
本博客部分路径（nav/、docs/、js/、libs/ 等）通过 skip_render 跳过渲染直接拷贝

2. 文章管理

新建文章

hexo new post "文章标题"          # 创建到 source/_posts/文章标题.md
hexo new post --path 2026/xxx 标题 # 自定义路径

标题含空格必须加引号；文件名自动转为小写（filename_case: 1）。新建后编辑该 Markdown 文件即可。

草稿

hexo new draft "未完成的想法"     # 创建到 source/_drafts/
hexo publish "未完成的想法"       # 发布：移到 _posts/ 并设置日期

_config.yml 中 render_drafts: false，草稿默认不参与生成。本地预览想查看草稿时用 hexo server --draft 或 hexo generate --draft。

修改配置/数据后的缓存注意

改主题配置、scripts 脚本后：hexo clean && hexo generate（rm -rf public 不够，会命中 hexo 内部缓存）
改 source/_data/*.yml 数据文件后：删除 db.json 再生成，否则可能读到旧数据

3. 永久链接（abbrlink）

默认永久链接格式：

# _config.yml
permalink: posts/:abbrlink/

hexo-abbrlink 插件按 crc32 + hex 为每篇文章生成短码（如 posts/40300608/）。writeback: false（2026-09-22 起关闭回写，防常驻 server 覆盖源文件）表示插件不回写源文件 —— abbrlink 在首次生成时写入 front-matter，此后固定：

---
title: 我的文章
abbrlink: a1b2c3d4   # 首次生成时写入后固定，勿手改
---

abbrlink 生成后即固定，改文件名、改标题都不会影响 URL，有利于外链稳定。配置项：

abbrlink:
  alg: crc32    # 算法：crc16 / crc32
  rep: hex      # 表示：dec（十进制）/ hex（十六进制）
  drafts: false # 草稿是否生成
  force: false  # 强制重新计算（会改变已有 URL，慎用）

4. Front-matter 速查表

Front-matter 是文章开头的 YAML 块（--- 包裹），定义文章元数据。以下为 matery 主题常用字段：

字段	说明	默认
`title`	文章标题	文件名
`date`	建立日期	文件创建时间
`updated`	更新日期	文件更新时间
`layout`	布局：`post` / `page` / `about` / `tags` 等	`post`
`categories`	分类（数组，支持层级 `[父, 子]`）	-
`tags`	标签（数组）	-
`keywords`	SEO 关键词	-
`excerpt`	首页摘要（纯文本）	-
`img`	文章封面图（首页卡片展示）	-
`top`	首页置顶推荐	`false`
`hide`	完全隐藏：不进首页列表、不进轮播	`false`
`cover`	是否进入首页轮播（`hide: true` 时无效）	`false`
`coverImg`	轮播自定义图（优先于默认图）	-
`toc`	是否显示目录	`true`
`tochide`	默认是否隐藏目录栏	`false`
`mathjax`	是否加载 MathJax 数学公式	`false`
`mermaid`	是否加载 Mermaid 图表	`false`
`echarts`	是否加载 ECharts 图表	`false`
`comments`	是否开启评论	`true`
`comment`	评论引擎（如 `waline`；`false` 关闭）	主题默认
`password`	文章加密密码（单独加密时使用）	-
`reprintPolicy`	版权声明策略（如 `cc_by_nc_sa`）	-
`abbrlink`	永久链接短码	首次生成时写入（不回写）

示例：

---
title: 示例文章
date: 2026-08-16 12:00:00
categories: [教程]
tags:
  - hexo
  - matery
img: /medias_webp/cover/write.webp
top: false
hide: false
toc: true
mathjax: false
mermaid: true
comments: true
comment: waline
---

新建文章时 scaffolds/post.md 会带入上述模板字段，按需删改即可。

5. 数据文件（_data）

source/_data/ 下是主题读取的数据单点，避免把重复数据散落各页。Hexo 自动加载该目录下的 yml/yaml/json 文件，文件名（去扩展名）即键名，模板中通过 site.data.<文件名> 访问。

5.1 文件清单

文件	用途	消费方
`friends.yml`	友链数据——每条含 `name` / `avatar` / `introduction` / `url` / `title`（可选）五个字段	`friends.ejs` 模板，`site.data.friends`
`galleries.yml`	相册数据——顶层 `galleries:` 数组，每个相册含 `name` / `cover` / `description` / `photos`（支持单图对象、路径字符串、目录扫描三种形式）	`galleries.ejs` 模板，`site.data.galleries`
`tutorial-sidebar.yml`	Tutorial wiki 侧栏导航	`wiki.js` helper 的 `wiki_sidebar()`
`api-sidebar.yml`	API wiki 侧栏导航	同上
`dev-sidebar.yml`	Dev wiki 侧栏导航（顶部还有 `encrypt_password` 等加密元数据，不参与导航）	同上
`docs-sidebar.yml`	Docs wiki 侧栏导航	同上

5.2 侧栏文件结构

四个 *-sidebar.yml 文件共享统一结构：

# 语言无关的页面树（section → page → html 路径）
structure:
  getting_started:
    overview: index.html
    features: features.html
  guides:
    layout: guide/layout.html
# 各语言译文（key = preference.lang_meta 口径）
i18n:
  zh-cn:
    getting_started: 开始使用
    overview: 概述
  en:
    getting_started: Getting Started
    overview: Overview

structure：定义导航层级和页面路径，不包含任何语言文本
i18n：按语言分组的显示文本，key 对应 languages/*.yml 中的 preference.lang_meta
encrypt_*（仅 dev-sidebar.yml）：顶层元数据，控制 wiki 加密行为（encrypt_password 必填，encrypt_message / encrypt_placeholder 可选），不参与导航渲染

消费方是 themes/matery/scripts/helpers/wiki.js 的 wiki_sidebar() 函数，它读取 site.data[wiki + '-sidebar'] 并合并 i18n 文本。

5.3 如何新增

操作	步骤
加一条友链	在 `friends.yml` 数组末尾追加一个 `- name: xxx` 块，补齐 5 个字段
加一个相册	在 `galleries.yml` 的 `galleries:` 数组中追加一项；同时创建 `source/galleries/<name>/index.md`（`layout: gallery`）
加一个 wiki 侧栏条目	在对应 `{wiki}-sidebar.yml` 的 `structure` 中加 key + html 路径，并在 `i18n` 各语言下加译文

5.4 缓存注意

修改 _data/*.yml 后必须删除 db.json 再构建（rm -f db.json && hexo generate），否则 Hexo 增量缓存可能读到旧数据导致页面空白。用 tools/cicd.sh -d 构建时已内置此处理。

下一步

功能指南：了解各页面布局、Tag 插件与交互视觉