新建一篇文章

1
npx hexo new post "文章标题"

文件会生成在 source/_posts/ 下，然后按下面的格式补 front-matter。

front-matter 全字段

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 文章标题
date: 2026-10-06 11:00:00
updated: 2026-10-07 10:00:00
categories:
  - 建站笔记
tags:
  - Hexo
  - 前端
description: 一段 50~120 字的描述，会用在卡片摘要和 SEO。
cover: /images/covers/hexo-theme.svg
---
字段 作用
title 标题，显示在卡片、详情页和浏览器标签
date 发布日期
updated 更新日期，与 date 不同时文章页会显示「更新于」
categories 分类，会出现在左栏分类列表
tags 标签，会出现在卡片底部和左栏标签云
description 简介，用于卡片摘要、详情页导语、SEO 描述
cover 封面图，卡片和详情页共用

关于 cover

1
cover: /images/covers/movie.svg
  • 路径以 / 开头，相对于站点 source 目录。
  • 不写 cover 时，卡片会渲染一个带标题首字的渐变占位块，不会开天窗。
  • 推荐比例 16:9，尺寸 800×450 以上。
  • 也可以用 photos 字段代替，取第一张：
1
2
photos:
  - /images/covers/game.svg

摘要与 <!-- more -->

在正文里插入 <!-- more -->，它之前的内容就是摘要：

1
2
3
4
5
这是一段导语，会出现在首页卡片上。

<!-- more -->

## 正文从这里开始

规则优先级：

1
front-matter 的 description  →  <!-- more --> 之前的内容  →  自动截断正文

代码块

主题的代码块是 macOS 窗口风格：左上角三个圆点、右上角语言角标、右上角复制按钮。

1
2
3
4
5
```javascript
function hello(name) {
  console.log(`hello, ${name}`);
}
```

代码块样式由主题内置，无需额外配置：mac 风格窗口三色圆点、右上角复制按钮、语言角标。

支持的语言角标包含 JavaScript、TypeScript、Python、Go、Rust、Java、C/C++、PHP、
Shell、PowerShell、YAML、JSON、HTML、CSS、SCSS、Vue、SQL、Dockerfile、Nginx 等，
未收录的语言会显示大写名称。

行内代码

用反引号包裹即可，例如 resource.enable，会自动应用等宽字体与浅底色。

文章目录

1
2
3
4
toc:
  enable: true
  title: 目录
  depth: 3
  • depth: 3 表示收录到三级标题（###）。
  • 目录显示在右栏，滚动时会自动高亮当前章节。
  • 窗口窄于 1280px（右栏收起）时，目录会以可折叠形式出现在正文顶部。

如果你不想让某篇文章显示目录：

1
2
3
4
---
title: 一篇不需要目录的文章
toc: false
---

文章页其它开关

1
2
3
4
5
6
7
8
post:
  toc: true              # 全局目录开关
  toc_depth: 3
  copyright: true        # 底部版权声明
  updated: true          # 显示更新日期
  words_per_minute: 300  # 阅读时长计算基准
  prev_next: true        # 上一篇 / 下一篇
  intro: true            # 正文前的简介

阅读时长 = 正文字数 ÷ words_per_minute，向上取整，最小显示 1 分钟。

导航菜单

1
2
3
4
5
6
menu:
  首页: /
  文章: /articles/
  资源库: /resources/
  归档: /archives/
  关于: /about/
  • menu 是全部菜单项，顺序即显示顺序，全部平铺在导航栏顶层。
  • 菜单项自带图标（按名称自动匹配，如 首页→home、文章→file-text），无需额外配置。
  • 资源类型（影视 / 游戏 / MOD / 汉化）不出现在导航栏里——它们入口在资源库页面顶部的类型筛选导航中。

文章分类导航

文章总页（/articles/）和文章分类页顶部有一排分类导航（与资源库顶部的类型筛选同一套视觉）：
「全部」+ 各文章分类（带篇数），点击即可在分类之间切换。

只有属于文章轨（含非资源帖）的分类才会出现；纯资源分类不会混进来。

内容排序

front-matter 里可以用两个字段控制列表排序：

1
2
3
4
5
---
title: 我的一篇文章
order: 1              # 全局排序：决定在 /articles/ 或 /resources/ 总列表里的位置
category_order: 2     # 分类内排序：决定在分类页（或资源类型页）里的位置
---
  • 数值越小越靠前；带排序值的文章置顶于按时间排序的文章之前。
  • order 作用于文章总页与资源总页；category_order 作用于文章分类页与资源类型页。
  • 两个字段都可以省略：省略 category_order 时回退到 order，再回退到按时间倒序。
  • 资源帖同理——order 控制它在 /resources/ 总列表的位置，category_order 控制它在所属类型页的位置。

上一篇 / 下一篇

文章页底部有「上一篇 / 下一篇」导航，文章与资源库分开串：

  • 打开普通文章，只会在文章里找相邻篇，不会跳到资源帖。
  • 打开资源帖，只会在资源里找相邻篇（样式上带资源标识）。
  • 相邻关系按上面说的 order 排序计算（未设 order 时按时间倒序），
    所以给系列文章排了 order，上下篇就会按你的顺序走。

开关：

1
2
post:
  prev_next: true

站点图标

1
2
# 站点 _config.yml
favicon: /favicon.png
  • 浏览器标签栏、收藏夹、桌面快捷方式都用这张图（favicon.png / favicon.ico / favicon.svg 都支持，
    会自动识别正确的 MIME 类型）。
  • 同一个值也会作为导航栏网站名左侧的品牌图标。
  • 想让品牌图标用另一张图，在站点 _config.yml 里单独指定：
1
2
header:
  logo: /images/brand.png
  • 三级回退顺序：header.logo（站点）→ favicon（站点）→ favicon（主题，默认 /images/favicon.svg）→ 主题内置线条标识。
  • 建议尺寸 180×180 以上的正方形图片，主题会自动按 34×34 圆角展示。

独立页面

除了文章，还可以建独立页面（关于、友链、留言板等）：

1
npx hexo new page about

会生成 source/about/index.md：

1
2
3
4
5
6
7
---
title: 关于
date: 2026-10-06 12:00:00
description: 关于本站。
---

正文内容……

独立页面使用 page.ejs 模板，带内页横幅，但不显示阅读时长、目录和上下篇。

站内搜索

主题在构建时会生成 search.json（由 scripts/resource.js 输出），
内容包含标题、链接、日期、分类、标签、是否资源以及一段摘要。

点击导航栏的放大镜或按 / 键可以唤起搜索框，
输入关键词后会实时匹配标题、分类、标签和摘要。

搜索索引在构建时生成，所以新文章需要重新 generate 之后才能被搜到。

下一篇

最后一篇讲侧栏组件、页脚、评论接入和常见问题排查。