如何在Asciidoctor中使用Tocify实现动态目录？

Question

默认情况下，Asciidoctor 会创建一个静态的目录。这很酷，但对于长篇文档来说，如果目录可以更加紧凑，并且突出显示读者当前所在的位置，那就更好了。

此时，Tocify 就派上用场了。Tocify 是一个不错的 JavaScript 解决方案，正好可以解决这个问题。

现在的问题是：如何将 Tocify 与 Asciidoctor 结合使用？

这里需要关注 Asciidoctor 的issue 699。

- rec

Answer 1

启用在你的asciidoc文件中文档信息处理，例如通过将以下选项传递给asciidoctor：

-a toc=left -a docinfo=shared

在您的asciidoc文件旁边添加一个名为docinfo.html的文件，并使用以下内容：

<!-- Generate a nice TOC -->
<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
<!-- We do not need the tocify CSS because the asciidoc CSS already provides most of what we neeed -->

<style>
.tocify-header {
    font-style: italic;
}

.tocify-subheader {
    font-style: normal;
    font-size: 90%;
}

.tocify ul {
    margin: 0;
 }

.tocify-focus {
    color: #7a2518; 
    background-color: rgba(0, 0, 0, 0.1);
}

.tocify-focus > a {
    color: #7a2518; 
}
</style>

<script type="text/javascript">
    $(function () {
        // Add a new container for the tocify toc into the existing toc so we can re-use its
        // styling
        $("#toc").append("<div id='generated-toc'></div>");
        $("#generated-toc").tocify({
            extendPage: true,
            context: "#content",
            highlightOnScroll: true,
            hideEffect: "slideUp",
            // Use the IDs that asciidoc already provides so that TOC links and intra-document
            // links are the same. Anything else might confuse users when they create bookmarks.
            hashGenerator: function(text, element) {
                return $(element).attr("id");
            },
            // Smooth scrolling doesn't work properly if we use the asciidoc IDs
            smoothScroll: false,
            // Set to 'none' to use the tocify classes
            theme: "none",
            // Handle book (may contain h1) and article (only h2 deeper)
            selectors: $( "#content" ).has( "h1" ).size() > 0 ? "h1,h2,h3,h4,h5" : "h2,h3,h4,h5",
            ignoreSelector: ".discrete"
        });

        // Switch between static asciidoc toc and dynamic tocify toc based on browser size
        // This is set to match the media selectors in the asciidoc CSS
        // Without this, we keep the dynamic toc even if it is moved from the side to preamble
        // position which will cause odd scrolling behavior
        var handleTocOnResize = function() {
            if ($(document).width() < 768) {
                $("#generated-toc").hide();
                $(".sectlevel0").show();
                $(".sectlevel1").show();
            }
            else {
                $("#generated-toc").show();
                $(".sectlevel0").hide();
                $(".sectlevel1").hide();
            }
        }

        $(window).resize(handleTocOnResize);
        handleTocOnResize();
    });
</script>

- rec