Last updated: Monday 07 September 2026 @ 20:44:27

mdbook-frontmatter-render 操作手册

mdbook-frontmatter-render 用于把 Markdown 文件开头的 YAML Frontmatter 渲染成结构化元数据组件。

它会保留原始可见文本，同时根据字段内容识别日期、布尔值、进度、颜色、邮箱、URL、GitHub/Hugging Face 标识、DOI、ORCID、标签、状态、评分和 WikiLink 等类型。

本地源码：/Users/ruoyangdong/project/rust/mdbook-frontmatter-render

最基础的写法

Frontmatter 必须位于 Markdown 文件最开头：

---
title: Example
created: 2026-07-11
tags: [Rust, mdBook]
---

# Example

插件会在构建时把 YAML 转换成元数据卡片。

一个较完整的样例

---
title: FlowANN
created: 2026-08-31
updated: 2026-09-04
draft: false
aigc: false
progress: 80%
rating: 4.5
color: "#7c3aed"
email: docs@example.com
github: OpenAI/codex
doi: 10.1145/1234567.8901234
tags: [ANNS, GPU, VectorSearch]
related: "[[HELMESMAN]]"
---

# FlowANN

不同字段会根据语义使用不同的显示形式。

布尔值

draft: false
aigc: true

插件默认把 draft、aigc、ai_generated 等字段按 Boolean 语义处理。

接受：

true / false
yes / no
on / off
1 / 0

推荐直接使用 YAML 原生 Boolean。

日期与时间

created: 2026-09-04
updated: 2026/09/04
reviewed: 2026-09-04T18:30:00+08:00

歧义日期的顺序由：

date-order = "auto"

控制，可选：

auto
ymd
dmy
mdy

时区处理：

timezone = "preserve"

可选 preserve、utc、local。使用 local 时还要指定：

local-timezone = "Asia/Shanghai"

百分比与进度

progress: 75%

如果字段被识别为 percentage-progress，会显示进度语义。

显式指定：

[preprocessor.frontmatter-render.fields.progress]
type = "percentage-progress"

颜色

color: "#7c3aed"

有效 CSS 颜色会显示 color swatch，同时保留原字符串。

邮箱与 URL

email: docs@example.com
homepage: https://pages.quaternijkon.online

邮箱会生成 mailto: 链接；安全 HTTP/HTTPS URL 会变为可点击链接。

GitHub / GitLab / Hugging Face

github: OpenAI/codex
gitlab: group/project
model: Qwen/Qwen3-Embedding-4B

例如把 model 明确设为 Hugging Face model：

[preprocessor.frontmatter-render.fields.model]
type = "hf-model"

还支持 huggingface、hf-dataset、hf-space。

DOI / ORCID

doi: 10.1145/1234567.8901234
orcid: 0000-0002-1825-0097

识别后会链接到各自的规范地址。

Status / Rating

status: reading
rating: 4.5

可以显式指定：

[preprocessor.frontmatter-render.fields.status]
type = "status"

[preprocessor.frontmatter-render.fields.rating]
type = "rating"

Rating 按 /5 语义处理。

Aliases

aliases:
  - Flow ANN
  - 流式向量检索

Aliases 也可以参与 WikiLink 目标解析。

Frontmatter 中的 WikiLink

普通链接

related: "[[HELMESMAN]]"

指定显示文字

related: "[[HELMESMAN|相关论文]]"

指向标题

related: "[[FlowANN#实验|FlowANN 实验]]"

当前页面标题

related: "[[#系统设计]]"

相对路径

related: "[[../Paper/ANNS/FlowANN]]"

从书籍根目录解析

related: "[[/Homepage]]"

插件只解析到当前 mdBook 已存在的章节，不会越过 source root。

WikiLink 模式

生成链接：

wikilinks = "resolve"

只显示文字：

wikilinks = "display"

完全保留原文：

wikilinks = "off"

未解析 WikiLink

unresolved-wikilinks = "warn"

值	行为
`ignore`	保留文字，不输出诊断
`warn`	输出警告，继续构建
`error`	中止构建

三种布局

Card：

layout = "card"

Badges：

layout = "badges"

Table：

layout = "table"

当前书库使用 card。

放置位置

标题后：

placement = "after-title"

页面最前：

placement = "before-title"

折叠

collapsible = true
default-open = true

collapsible = true：允许折叠；
default-open = true：默认展开；
default-open = false：默认收起；
collapsible = false：完全不可折叠。

隐藏字段和空值

hidden = ["cssclasses", "private", "internal_notes"]
show-null = false
show-empty = false

false 和数字 0 不会被当成空值。

标题去重

deduplicate-title = true

当 Frontmatter title 与页面可见 H1 完全一致时，不重复显示 title。

单字段自定义

[preprocessor.frontmatter-render.fields.aigc]
label = "AIGC"
type = "boolean"
icon = "sparkles"
order = -10
hidden = false
full-width = false

配置	作用
`label`	修改显示名
`type`	强制字段类型
`icon`	指定图标
`order`	越小越靠前
`hidden`	隐藏/显示
`full-width`	Card 模式是否跨整行

可用类型

auto, text, boolean, integer, float,
date, time, datetime, duration,
email, url, wikilink,
percentage, percentage-progress, color, version,
github, gitlab, huggingface,
hf-model, hf-dataset, hf-space,
doi, orcid, license, language, status, rating,
tags, aliases

可用图标

calendar, clock, mail, link, git-branch, repository, box,
sparkles, percent, palette, tag, hash, toggle, none

批量规则

[[preprocessor.frontmatter-render.rules]]
keys = ["release.*", "metadata.version"]
type = "version"

[[preprocessor.frontmatter-render.rules]]
keys = ["contact.email", "authors.*.email"]
type = "email"

规则按书写顺序匹配，第一个命中生效。* 只匹配一个 dotted path 段。

嵌套对象

authors:
  - name: Alice
    email: alice@example.com
  - name: Bob
    email: bob@example.com

最大递归深度：

max-depth = 4

过深结构会安全退化为 YAML code block。

类型推断强度

inference = "aggressive"

可选：

值	行为
`aggressive`	积极根据 key、YAML 类型和值格式推断
`conservative`	只识别高置信度格式
`keys-only`	主要依赖 key 和显式配置

显式 fields.<key>.type 优先级最高。

严格模式

本地写作：

strict = false

CI / 正式发布：

strict = true
unresolved-wikilinks = "error"

当前书库配置

[preprocessor.frontmatter-render]
command = "cargo run --quiet --manifest-path /Users/ruoyangdong/project/rust/mdbook-frontmatter-render/Cargo.toml --"
layout = "card"
placement = "after-title"
style = "embedded"
collapsible = true
default-open = true

与 obsidian-format 的职责划分

当前顺序：

frontmatter-render → obsidian-format → renderer

Frontmatter WikiLink：frontmatter-render；
正文 WikiLink / Embed：obsidian-format。

Pages