如何用Pandoc生成适配GitHub的Markdown目录？

问题 #

我尝试用命令pandoc -f gfm -s --template template.md --toc questions.md -o README.md为Markdown文件生成适配GitHub仓库的目录（TOC）。生成的README.md中目录和标题出现多余的{#toc-xxx}、{#xxx}标记，且目录链接无法正常工作。我使用Makefile构建输出，请问如何修改才能生成无冗余标记、链接正常的目录？

解决方案 #

• 指定GFM输出格式：Pandoc默认输出标准Markdown会生成显式锚点标记，添加-t gfm参数强制输出GitHub适配的格式，自动生成正确的隐式锚点：

  pandoc -f gfm -t gfm -s --template template.md --toc questions.md -o README.md
  

  此方法会让Pandoc生成符合GFM规范的目录链接，不会出现{#xxx}类冗余标记，且跳转正常。

• 强制使用ATX标题格式：添加--markdown-headings=atx参数，确保生成GitHub默认支持的ATX格式标题，避免因Setext格式标题导致的锚点异常：

  pandoc -f gfm -t gfm --markdown-headings=atx -s --template template.md --toc questions.md -o README.md
  

• 排查自定义模板：确认template.md中没有硬编码{#xxx}锚点标记，且目录部分使用Pandoc内置的$toc$变量生成，不要手动编写带锚点的目录结构。

• 更新Makefile构建命令：将修改后的Pandoc命令写入Makefile，确保每次构建都自动生成正确文件：

  README.md: questions.md template.md
      pandoc -f gfm -t gfm -s --template template.md --toc questions.md -o README.md
  

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