目录配置

目录级配置统一在 __everkm/everkm.yaml 的 folders 字段中声明。config 与 default_template 见 站点配置。

子目录配置与祖先目录合并继承，深层配置覆盖或追加浅层同名字段。

v0.17.0 起：旧版各目录 index.yaml 已废弃，不再被读取。请将配置迁移至 everkm.yaml#folders。

基本示例

# __everkm/everkm.yaml
folders:
  "/":
    hide_in_url: true
  "/docs/":
    template: book.html
    query:
      stack: true
    breadcrumbs:
      - title: "@i18n:nav.docs"
        url: /docs/
  "/blog/":
    template: list.html
    url_id_suffix: false

模板中通过全局变量 __qs 读取 query 合并结果；面包屑见 __breadcrumbs 与 nav_path。

字段说明

字段	类型	默认值	说明
url_slug	string	目录名 slugify	自定义该目录在 URL 中的路径段名称
hide_in_url	bool	false	设为 true 时该目录不参与 URL 路径拼接
template	string	—	该目录下页面默认模板路径
query	object	—	渲染时合并进 __qs 的键值对
breadcrumbs	array	—	面包屑条目数组，每项含 title、url；支持 @i18n:<key>
hash_scatter	bool	false	是否将文章 URL 哈希分散到子目录（别名 hash_storage、storage_scatter）
url_id_suffix	bool	true	设为 false 时非 index 页 URL 为 {slug}.html，不追加 -{id}

合并规则

对文章所在目录（如 /blog/2025/01/），沿祖先链（根→叶）逐级合并：

祖先链: / → /blog/ → /blog/2025/ → /blog/2025/01/
merged = 默认值
对链上每级: 若 folders[path] 存在 → merged.extend(folders[path])

• 子层显式配置覆盖父层同名字段
• 子层未配置时继承祖先合并结果
• 合并按祖先链顺序，不是按 key 字符串长度排序

面包屑

合并规则

• 链首不再自动插入「Home」；若需要首页入口，请在 folders["/"].breadcrumbs 中自行声明
• 子目录 breadcrumbs 非空时按目录深度追加到祖先链末尾，不会整段替换祖先配置
• 子目录未写 breadcrumbs 时不会清空祖先已合并的面包屑
• 若各级均未配置，会按当前页 URL 路径自动生成：每一级目录的 index 页会出现在面包屑中

title 支持 @i18n:<key> 引用。仅当条目未配置 url（或 url 为空） 时，title 为 [[wikilink]] 才会按内链解析（先替换 i18n，再判定内链），并采用目标页面的标题与 URL。

folders:
  "/":
    breadcrumbs:
      - title: "@i18n:nav.home"
        url: ~/
  "/blog/":
    breadcrumbs:
      - title: "[[blog]]"
      - title: "@i18n:nav.blog"

URL 生成

目录路径拼接

url_path = join(各级 effective_slug)，跳过 hide_in_url == true 的级
effective_slug = url_slug ?? slugify(该级目录段名)

文件名规则

条件	URL 文件名	示例
目录 index 页	index	/blog/index.html
普通文 + url_id_suffix: true（默认）	{slug}-{id}	/blog/hello-abc123.html
普通文 + url_id_suffix: false	{slug}	/blog/hello.html

组合示例

folders:
  "/blog/":
    url_id_suffix: false
    hash_scatter: true

• 逻辑 URL: /blog/my-post.html
• 导出物理路径: /blog/ab/cd/my-post.html（经 __hs=1 触发）

导航函数与内链

书籍/文档模板中常用 nav_tree、nav_path、nav_indicator。其 from_file 参数若用 [[...]] 包裹，与正文 内链 采用相同解析规则（大小写不敏感、歧义报错）。

{{ nav_tree(from_file="[[./SUMMARY.md]]") | json_encode }}