如何在Org Mode文档中生成可在GitHub显示的带链接目录

排查org-make-toc报错问题 #

你遇到的user-error: Before first headline at position 213 in buffer SUNRA.org错误，核心原因是执行命令时光标位置在文档第一个标题之前。org-make-toc需要基于文档的标题层级生成目录，光标必须落在任意标题所在行或标题范围内，且文档本身要有合法的Org标题结构（以*开头的层级标题）才能正常工作。

快速修复步骤 #

• 打开SUNRA.org文档，将光标定位到任意一个一级（*开头）或二级（**开头）标题的行上
• 重新执行M-x org-make-toc命令
• 如果仍无反应，检查文档标题格式：标题必须以*开头，且*与标题文本之间有空格（比如* 我的配置是合法格式，*我的配置则不被识别）

生成GitHub可识别的TOC #

官方Org Mode内置的#+TOC:指令确实主要用于导出场景，无法直接生成GitHub能解析的带链接目录。要实现这个需求，可尝试以下两种方法：

方法1：用org-make-toc生成标准Markdown TOC #

确保插件配置和使用流程正确：

1. 确认org-make-toc已正确安装加载（Doom Emacs中需在packages.el添加(package! org-make-toc)，并执行doom sync）
2. 执行M-x org-make-toc-generate-markdown-toc，根据提示选择要包含的标题层级（比如1-3级）
3. 生成的内容是标准Markdown格式的TOC，GitHub会自动识别其中的锚点链接

方法2：手动编写兼容TOC #

如果插件仍不稳定，可手动编写符合GitHub规范的TOC：

• 列表项格式为- [标题文本](#标题锚点)
• 标题锚点规则：将标题转为小写，空格替换为-，去掉特殊符号（例如标题* 主题配置对应的锚点是#主题配置）
• 可使用Org Mode的C-c C-l快捷键快速获取标题链接：在标题行执行该命令，复制生成的链接中的锚点部分即可

插件失效的排查方向 #

• 查看Emacs日志：执行M-x view-echo-area-messages，检查插件执行时的具体报错信息
• 更新插件：确保org-make-toc和toc-org为最新版本，Doom Emacs中可执行doom upgrade更新所有插件
• 冲突排查：暂时禁用其他Org相关插件（如org-roam），测试是否因插件冲突导致功能失效

内容的提问来源于stack exchange，提问作者Nutritioustim