asciidoc - 为 ASCII 文档创建索引页面

Question

我在不同的位置有很多 ASCII 文档，我想创建一个索引页面来呈现这些文档。但这里的条件是我想在索引页面上列出所有文档链接，如果用户点击任何链接，那么应该只显示文档。我不想在目录下方显示文档。我只想在索引页面上显示目录。

有没有办法做到这一点？

Answer 1

如果我对您的理解正确，您希望生成一个多文档网站，但您想要一个仅显示 TOC 的索引页面，而其他文档则在其他地方提供。我相信获得这种效果的最好方法是使用 DocBook 工具链生成分块的 XHTML 输出。我相信Asciidoctor 工具应该可以做到这一点，但我只使用原始（基于 Python）AsciiDoc 渲染工具实现了这个特定的后渲染工具链，如此处所述。此设置可配置为生成链接到分块输出的 TOC 索引页面（您可以配置分块级别）。

正如您已经发现的那样，AsciiDoc 的自动 TOC 生成仅适用于当前文档，这需要包含从属文档以获取 TOC 的标题。我可以想办法解决这个问题，比如只包含包含文档的标题（include::path/to/document.adoc[lines=1]），然后用 CSS 或其他东西隐藏这些标题。问题是，目录中的链接将指向内部，因此您需要以某种方式处理它。

另一种方法是使用任何支持或可以轻松扩展以支持 AsciiDoc的静态站点生成器。您所说的不是我所知道的开箱即用功能，但它们至少都可以生成有组织的 TOC 类型的导航。