目录结构与内容管理

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: true 会写回文章 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/ 下是主题读取的数据单点，避免把重复数据散落各页：

文件	内容
`friends.yml`	友链数据（name/url/avatar/introduction/title）
`galleries.yml`	相册数据（photos/cover/description）
`tutorial-sidebar.yml`	教程 wiki 侧栏章节（本文档所在系统的导航）

修改数据文件后必须删 db.json 再构建，否则页面可能空白或读到旧数据。

下一步

功能指南（即将推出）：了解各页面布局、Tag 插件与交互视觉