KLucenの启示录

导入整份文件#

效果

这篇文章里的示例假定本地已经准备好：

• Node.js 22.12 或更高版本
• pnpm 包管理器

常用命令#

1
pnpm content:sync   # 把内容仓同步到主题仓
2
pnpm dev            # 本地预览
3
pnpm build          # 生产构建

以上三条命令覆盖了 90% 的日常操作。

源码

导入指定行区间#

效果（只取第 2–5 行）

这篇文章里的示例假定本地已经准备好：

• Node.js 22.12 或更高版本
• pnpm 包管理器

源码

1
<!-- @include: src/content/snippets/npm-commands.md{2-5} -->

行区间的写法：{起始-结束}；也支持只写一头，如 {3-}（第 3 行到结尾）、{-5}（开头到第 5 行）。

导入命名区块（region）#

效果（只取 #region prerequisites 标记的那一段）

这篇文章里的示例假定本地已经准备好：

• Node.js 22.12 或更高版本
• pnpm 包管理器

源码——先在目标文件里用注释标记出区块：

1
// #region auth-config
2
export const authConfig = {
3
  enabled: true,
4
  provider: 'github',
5
};
6
// #endregion

再在正文里引用这个区块名：

1
<!-- @include: src/content/snippets/npm-commands.md#prerequisites -->

路径怎么写#

官方文档给的是「相对当前 Markdown 文件的相对路径」。在本站这套主题与构建流程下实测的结果是：路径相对构建时的工作目录（也就是站点仓根目录）解析。

也就是说：写成本站仓根目录起算的路径最稳。构建时内容仓会被物化到站点仓的 src/content/ 下，所以 src/content/snippets/... 这个写法在本地预览与线上构建里都成立。

边界行为#

• 只处理独立成行、且位于代码围栏之外的注释指令；
• 目标文件缺失、越界、未闭合或递归包含时，指令会原样保留（不报错、页面上不显示）；
• 文件读取被限制在仓库根目录内，相对路径也不能越出仓库；
• 展开结果会继续经过同一套 Markdown 处理链，因此被导入的代码块同样带高亮与行号。