文章补丁

更新于 2026年11月12日

有时一个 Markdown 文件既是站点内容，又会在别处被读取：例如由 GitHub 渲染的 README.md，或者另一个项目中共享的规范。往里添加仅供 Livemark 使用的前置元数据 frontmatter，会污染另一处的展示。

patches 让你可以在 livemark.config.ts 中为特定文件注入 frontmatter 字段，而不必编辑磁盘上的文件。

基本用法

livemark.config.ts

import { defineConfig } from "livemark"

export default defineConfig({
  include: ["README.md", "docs/**/*.md"],
  patches: [
    {
      file: "README.md",
      article: {
        title: "Overview",
        icon: "sparkles",
        order: 0,
      },
    },
  ],
})

磁盘上的文件保持干净，但 Livemark 渲染它时，就好像上面的 YAML 写在文件开头一样。

字段

字段	类型	用途
`file`	`string`	相对于集合的路径，例如 `"README.md"`、`"docs/a.md"`。
`article`	`Partial<Article>`	除 `content` 外的任意 frontmatter 字段。

像 format 这样的文章字段也同样适用。无论扩展名是什么，都将文件固定为纯 Markdown：

{ file: "CHANGELOG.md", article: { format: "md" } }

匹配方式是与 Livemark 收集到的文件路径做精确的字符串比较。如果路径没有匹配到任何文章，补丁会静默地不起作用。当你防御性地为一个可能存在也可能不存在的文件打补丁时，这一点很方便。

合并语义

补丁的 article 字段会合并到文件自身的 frontmatter 之上。补丁中未指定的内容保留其正常值（来自文件，或来自 Livemark 的自动默认值）。

因此，一个没有 frontmatter 的 README 加上：

{ file: "README.md", article: { title: "Overview" } }

会渲染为一篇标题为 “Overview” 的文章。其他所有字段（描述、图标、路径等）都回退到默认值。

不能打补丁的内容

content 键会在加载配置时被拒绝：

// Throws at startup:
{ file: "README.md", article: { content: "replaced" } }

补丁用于元数据；文件的内容永远是文件本身的内容。

另请参阅

Frontmatter：所有可设置的字段，无论是写在文件中还是通过补丁设置。
配置：决定补丁可以匹配哪些文件的 include glob。