文章元数据

Markdown 文件顶部的 YAML 块称为 Front Matter，描述页面标题、标识、时间等元数据。everkm-publish 索引内容时读取这些字段。

最小示例

在站点根目录创建 HOME.md：

---
title: 欢迎
slug: index
created_at: 2026-06-19T10:00:00+08:00
---

这是首页正文。

保存后启动 everkm-publish serve，浏览器打开 http://localhost:9081 即可看到渲染结果。

常用字段

字段	必填	说明
title	推荐	页面标题；未写 slug 时用于自动生成 slug
slug	推荐	URL 路径段；首页常用 index
created_at	推荐	创建时间，RFC3339 格式
updated_at	可选	更新时间，RFC3339 格式
id	可选	稳定唯一 ID；lint 可自动补全
tags	可选	文章标签（字符串数组）；索引时会规范化，见下文
summary	可选	摘要；未写时由索引从正文自动截取

旧字段 date 已废弃，请使用 created_at。lint --auto-fix 可自动迁移。旧字段 categories 不再参与列表筛选，请改用 tags。

时间格式

RFC3339，例如：

created_at: 2026-06-19T10:00:00+08:00
updated_at: 2026-06-19T15:30:00+08:00

slug 与 URL

• 文件 blog/hello.md 且 slug: hello → 通常生成 /blog/hello-{id}.html（取决于 folders.url_id_suffix）
• 目录索引页：slug: index 或文件名 index.md
• 根目录 HOME.md 配合 slug: index 作为站点首页

URL 规则详见 目录配置。

文章标签

tags:
  - Rust
  - hello world
  - tech/rust

写入 Front Matter 后，索引阶段会规范化为站内统一格式，再用于标签页、链接与 posts() 筛选：

• 保留字母、数字与中文等字符，大小写不变；空格与其它符号变为减号（如 hello world → hello-world），连续减号会合并。
• 可用 / 写多层标签：tech/rust 会同时挂上父级与完整路径，便于「tech」标签页也能列出该文。
• 仅由符号组成、无法形成有效标签的项会被丢弃（如 +++）。
• private 等业务排除标签仍按原约定生效（列表默认排除带 private 的文章），见 毓知Markdown格式 与 posts() 文档。

主题展示多层标签时，通常会把内部连接符显示回 /。筛选或拼标签 URL 时，请使用规范化后的值（多层为 tech__rust 这种形式），详见 内置函数。

发布前检查

everkm-publish lint ./my-site

# 自动修复：补全 id、date → created_at、部分 slug 冲突等
everkm-publish lint ./my-site --auto-fix

lint 会检查 Front Matter 完整性与 slug 唯一性，并按行号报告正文 [[...]] 内链歧义。详见 导出与发布。

预览时对单个文件自动修复：

everkm-publish serve --auto-fix-on-update

正文与标题

若正文首个 h1 与 Front Matter title 文字相同，渲染时会自动隐藏该 h1，避免标题重复显示。见 毓知Markdown格式。

下一步

• 毓知 Markdown 扩展（内链、宏、dCard）：链接与内链、毓知Markdown格式
• 文档站章节目录：导航与目录
• 多语言内容目录：多语言