Welcome Dave! And thanks for your encouragement.
Your use case is precisely the kind of customization we set out to make possible with Asciidoctor. There are numerous ways to tap into the processor to get the output that you need, several of which you mentioned.
What's important about the Asciidoctor architecture is that you are never far from being able to plug in code using a regular programming language (primarily Ruby at this point).
One way to enhance the toc output is a post processor. Another way is to provide a custom "view" template (either document, block_preamble or block_toc depending on where you are inserting the toc). You can enhance the listing output in a similar way by providing a custom block_listing template.
You can see examples of custom templates in the https://github.com/asciidoctor/asciidoctor-backends repo.
Keep in mind that you can use Ruby code inside a template, so there is no limit to the complexity of the logic. That's such a core principle of Asciidoctor.
To extract information about what to add to the toc, you might think about using a tree processor in which you can walk the nodes in the parsed tree to extract information. There isn't yet a storage bin in the document object to stash extracted information (expect maybe the @references field), but you could use a (dare I say) global variable in the interim.
I think you it's a good idea to leverage CodeRay or Rouge in both the tree processor and the custom template to handle parsing of the code.
I recommend trying to work within Asciidoctor rather than using an extra step in the doc processing pipeline. The reason is because Asciidoctor provides proper context & comprehension of the document structure and because it was designed for this sort of thing.
If you find that Asciidoctor is not able to give you the control you need at some point, file an issue and we'll work together to improve Asciidoctor so it does.
I hope that helps! If you need help making your customizations, stick them in a GitHub repository and we can review them, time permitting.
Happy hacking!
-Dan
| Free forum by Nabble | Edit this page |