asciidoc no longer rendering Table of Contents

[johnnyutahh]

github markup used to consistently, as recently as 2015-07-18, render asciidoc README's with a Table of Contents (TOC) in the HTML output--presumably per the ':toc: 1' asciidoc directive.

But now it's no longer doing this. For example: https://github.com/johnnyutahh/search-based-email

asciidoctor 1.5.2 still renders the same (above) README.adoc file with a TOC. Why does github no longer do so?

[mojavelinux]

Please see the relevant section in the migration guide.

http://asciidoctor.org/docs/migration/#toc-table-of-contents-positioning

Specifically, you'll want toc: macro.

[gjtorikian]

Thanks @mojavelinux!

[johnnyutahh]

Thanks, helpful. Really appreciate the super-fast reply.

I didn't know that asciidoctor "migrated." Also, can someone confirm that github does not want to honor or enable ':toc: left' directive (even though it works with a native asciidoctor rendering)? It didn't seem to work for me, so I went with an inline-based, ':toc: macro' directive, which does work: https://github.com/johnnyutahh/search-based-email

[mojavelinux]

@johnnyutahh That's correct. It's not that GitHub doesn't want to, it's that GitHub renders the AsciiDoc to "embeddable" HTML. In this mode, the sidebar toc is not used. You can emulate this by adding the -s flag to the asciidoctor command if you're using the CLI or the header_footer: false option if you are using the API.

The only valid options for the toc in embedded mode are macro or preamble. We're discussing making this more intuitive in the future. See asciidoctor/asciidoctor#1443.

[johnnyutahh]

Thanks, all quite helpful. The diligence and attention to detail all greatly appreciated - thanks again.

[mojavelinux]

👍