站点里的页面跳转，推荐优先用内链 [[...]]——在预览与导出时由发布系统解析为最终 URL，而不是手写相对路径。内链用于正文互引、章节目录（如 导航与目录 中的 _nav.md）、面包屑标题，以及模板里 nav_tree 等函数的 from_file 参数、post_detail 等函数的 path 参数。
标准 Markdown 链接
对外部站点或固定 URL，使用常见写法即可：
[毓知官网](https://everkm.cn)
<https://everkm.cn>
[引用式链接][ref]
[ref]: https://everkm.cn
导出静态站时，正文中的相对路径链接（如 [下一页](./next.html)）会被校验拦截。站点内跳转应改用内链，见下文。
内链语法
内链写作 [[目标]]，在 Markdown 渲染阶段即解析为发布 URL。
- 导出 / CI：无法解析或存在歧义时会立即报错，整页失败。
- 本地预览（
serve）：同样标出坏链，但不中断整页；坏链以虚线下划线显示，鼠标悬停可查看错误原因（class：ekm-inner-link-broken）。
[[quick-start]] # 按 slug 或标题匹配
[[./faq/]] # 相对当前文件目录
[[/docs/guide/quick-start.md]] # 站点根逻辑路径
[[./page#章节标题]] # 锚点
[[./faq/|常见问题]] # 自定义显示文本（| 前为目标，后为文案）
本指南目录 _nav.md 即以内链组织章节：
* [[navigation]]
* [[inner-link]]
* [[everkm-markdown]]
匹配规则
解析按以下顺序尝试（均基于当前语言的内容索引）：
| 顺序 | 写法 | 说明 |
|---|---|---|
| 1 | 外链、~/ 前缀 | 原样输出或替换为站点 base_prefix |
| 2 | slug | 忽略大小写；多篇命中 → 报错 |
| 3 | 标题 | 忽略大小写；多篇命中 → 报错 |
| 4 | 路径 | 见下表「路径前缀」 |
| 5 | 非 .md 媒体 | 复制到静态资源并输出 URL |
路径前缀（slug / 标题均未唯一命中后）：
| 写法 | 行为 |
|---|---|
以 / 开头 | 站点根下的逻辑路径，如 [[/docs/faq.md]] |
以 ./ 或 ../ 开头 | 相对当前 Markdown 文件所在目录 |
| 无前缀 | 先按路径后缀全库匹配（如 use-cases → 查找以 /use-cases.md 结尾的路径）；唯一则命中，多个则歧义；仍未命中则回退为相对当前目录 |
[[FAQ]] 通常先按 slug / 页面标题解析，而不是直接当作「当前目录下的文件名」。标题或 slug 可能在不同目录重复，目录默认页、章节目录等场景请优先用 [[./子目录/]] 或 [[/绝对/逻辑/路径]] 消歧。
带末尾 / 的路径按目录默认页解析（如该目录下的 index.md 或 slug: index 的页面）。
内链也可指向非 Markdown 媒体（如 PDF、图片），导出时自动复制到静态资源目录并输出 URL。
常见场景
正文互引
配置细节见 [[dir-config]]；Markdown 扩展见 [[everkm-markdown]]。
章节目录 _nav.md
列表项写内链即可，主题读取 nav_file 后渲染侧栏树与上下篇。见 导航与目录。
面包屑
everkm.yaml 的 folders.breadcrumbs 中，仅当条目未配置 url（或 url 为空） 时，title 为 [[...]] 才会按内链解析，并采用目标页面的标题与 URL；若同时写了 url，则直接使用配置的 title 与 url，不再解析内链。
folders:
"/blog/":
breadcrumbs:
- title: "[[blog]]" # 无 url：解析内链 → 目标页 title + URL
- title: "@i18n:nav.blog"
url: /blog/ # 有 url：原样使用，title 不作内链解析
合并规则与更多示例见 目录配置。
模板内置函数
以下参数的 [[...]] 写法与正文内链采用相同匹配规则（slug → 标题 → 路径；歧义报错）。plain 字符串仍按 strict logical path 查找，不会自动 fallback 到 inner link。
| 函数 | 参数 |
|---|---|
nav_tree / nav_path / nav_indicator | from_file |
post_detail / post_meta / has_post / post_resources | path（与 id 二选一） |
{{ nav_tree(from_file="[[./_nav.md]]") | json_encode }}
{% set intro = post_detail(path="[[home]]") %}
{% set sibling = post_detail(path="[[./next]]") %}
相对路径的参照文档与正文不同：
| 场景 | [[./x]] / [[../x]] 相对谁 |
|---|---|
| 正文 Markdown | 当前 Markdown 文件所在目录 |
| 模板函数（上表） | 当前渲染页对应文章的 logical path（须页面上下文中有 post） |
因此 slug、标题、[[/绝对/逻辑/路径.md]] 可在任意页面模板中使用；[[./x]] / [[../x]] 须在文章页（或 JsRender 传入含 post 的 requestId）中调用，否则报错。首页、列表页等无 post 上下文时，请改用 slug 或绝对路径。
可选参数 allow_missing: true（post_detail / post_meta / has_post）时，[[...]] 无法解析或目标不存在将返回空值，适合主题配置中的可选 Hero 来源（如 config.home: '[[home]]'）。
发布前检查
everkm-publish lint ./my-site
按行号列出无法解析或存在歧义的 [[...]]，适合 CI 与发布前自检。歧义时输出候选页面列表，便于改用更具体的路径。
常见修复方式：
[[quick-start]]命中多篇 → 改为[[/docs/guide/quick-start]]或[[./guide/quick-start]]- 标题重复 → 改用显式路径，勿依赖标题匹配
更多排错见 常见问题。
与相对链接的区别
内链 [[...]] | 标准链接 [text](./page.md) | |
|---|---|---|
| 解析时机 | Markdown → HTML 阶段 | 导出后校验相对 href |
| 目标 | 索引中的页面 / 媒体 | 手写路径，易随 URL 规则失效 |
| 失败行为 | 渲染立即失败 | 导出时报 RelativeLinkNotAllowed |
完整 Markdown 链接、页内锚点 {id=...}、链接扩展属性等语法见 毓知Markdown格式 与 毓知Markdown格式。