Option for Generating a Table of Contents

[makoConstruct]

It looks like it'll require adding another writer to the format_document process (to have entries written each time you encounter an anchor, separate to writing the body of the document).

[kivikakk]

I like the idea! We could also just traverse the document again to find headers, before doing the main HTMLification. PRs happily accepted!

[makoConstruct]

Hm, the closest thing to established standard behaviour for markdown table generation https://python-markdown.github.io/extensions/toc/ uses a [TOC] tag, which will need to be picked up in the parsing stage, yeah? I'm not sure why anyone would want to insert a toc somewhere other than the beginning, but there must be some reason for it.

I'm thinking the easiest way to do this is to change it so that we're writing everything to a string, and then remember where the [TOC] occurs, and then insert the table there after we've formatted the rest of the document and so seen all the anchors, writing all that to output. Would that be alright?

[kivikakk]

I'm inclined against doing it this way, if only because replacing part of a string can be a costly operation — everything after the replace target will need to be moved in memory. Because the [TOC] tag is likely to be toward the start of the output, this means most of the string will need to be moved.

Reflecting more on this issue, I'm not sure I want to include it in the HTML generation at all. It would mean Comrak is prescribing the particular output format of the TOC, but realistically most people will have their own needs re: what HTML structure is required, CSS classes, etc. etc. I think I'd prefer to give a way to easily collect the header IDs so the user can generate their own TOC as needed.

[makoConstruct]

It would be three string copies. Not exactly slow.

I can't see why someone would need to vary from the standard HTML structure? Css is quite flexible. For me though, in the post where I needed a table of contents, I ended up writing it manually along with my own anchor links, less an issue of structure, more of content.

I did end up writing most of the code for TOC generation though https://github.com/makoConstruct/comrak it doesn't seek any [TOC], just inserts the TOC it at the beginning, which I guess is probably not what most people would want. I definitely want it to be after the title and to not count the title as a heading.