本文介绍通过配置 html-preamble 和 html-preamble-format，在 org mode 导出 html 时自动插入包含“首页”和“上级索引页”链接的导航栏，适用于扁平或浅层目录结构，无需外部静态站点生成器或复杂 emacs lisp 编程。
本文介绍通过配置 html-preamble 和 html-preamble-format，在 org mode 导出 html 时自动插入包含“首页”和“上级索引页”链接的导航栏，适用于扁平或浅层目录结构，无需外部静态站点生成器或复杂 emacs lisp 编程。
Org Mode 原生导出 HTML 时默认不包含跨页面导航功能，但借助其灵活的导出钩子与预设变量，可轻量实现类似静态站点生成器的层级导航体验。核心思路是：为每个非根页面注入统一的 HTML 导航栏，并动态区分根索引页与子页面的链接行为。
配置导航栏内容
在 Emacs 配置中（如 init.el 或 Org 文件本地属性中），设置 html-preamble 为一个函数，使其根据当前导出文件路径智能生成导航 HTML：
(setq org-html-preamble
(lambda (info)
(let* ((file-path (org-export-get-relative-file-name info))
(dir (file-name-directory file-path))
(is-root-index (string= file-path "index.html"))
(root-index-link "<a href="%5C%22/index.html%5C%22">? Home</a>")
(parent-index-link
(if (string= dir "./")
""
(format "<a href="%5C%22%sindex.html%5C%22">⬆️ Local Index</a>"
(replace-regexp-in-string "/[^/]*\'" "" dir)))))
(unless is-root-index
(format "<nav class='"org-navbar"'>%s | %s</nav>"
root-index-link parent-index-link)))))
✅ 说明：该函数自动提取当前导出文件的相对路径，判断是否为根目录下的 index.html；若否，则生成指向 /index.html（站点首页）和同级目录 index.html（上级索引页）的链接。file-name-directory 与正则替换共同实现路径层级推导。
禁用根索引页的导航栏（可选）
为避免根 index.html 出现冗余导航，可在对应 Org 文件中添加局部属性：
#+HTML_PREAMBLE: nil
或在导出前临时覆盖：
(org-export-with-preamble nil)
注意事项与局限性
- ✅ 适用场景：适用于目录深度 ≤2 的结构（如 ./index.html、./blog/index.html、./blog/post.org），逻辑清晰、维护成本低；
- ⚠️ 递归结构限制：若存在多层嵌套（如 ./a/b/c/index.html），需解析完整路径层级并逐级回溯——此时建议结合 directory-files-recursively 或使用 org-export-before-processing-hook 预处理元数据；
- ? 安全提示：html-preamble 返回字符串需确保 HTML 转义（本例中链接内容可控，无用户输入，故无需额外转义）；
- ? 样式增强：可配合自定义 CSS 提升导航栏美观度，例如添加 display: flex; gap: 1rem; padding: 0.5rem; background: #f8f9fa; 等。
此方案以最小侵入性达成“零依赖导航”，充分发挥 Org Mode 内置导出系统的可编程性，是轻量静态文档站的理想实践。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
