greenape
Feature request: enable [TOC] markers to insert table of contents in notebooks?
Many thanks for fixing the table of contents (as of git rev. 3bd9d3b1f7b1). 👍😃
One small additional feature request: in pure-markdown pages it is possible to insert a [TOC] marker somewhere in the page, which will be automatically expanded into a table of contents. [1]
Currently this doesn't seem to work for notebooks converted by mknotebooks, but it would be a useful feature, in order to be able to give an at-a-glance overview at the top of longer notebooks. Is there an easy way to enable this based on your recent changes @greenape?
I have a proof of concept implementation which adds a preprocessor to the HTML exporter that simply looks for headings at various levels and inserts links at the top of the page. I'm happy to submit this as a PR but I feel like there is a chance I'm reinventing the wheel and there is probably a way to simply re-use the existing toc extension somehow? Thought I'd ask in any case, but let me know if you'd like me to submit a PR based on my current approach.
Many thanks!
[1] I think this is provided by the toc markdown extension, but the [TOC] marker works even if I don't explicitly enable markdown.extensions.toc in mkdocs.yml, so maybe this is actually something directly built into MkDocs?
P.S.: If there is a chance to enable [TableOfContents] in addition to [TOC] (as an alias) that would be fantastic, because then notebooks remain readable to non-technical users, e.g. when opened interactively in Binder.
🤔 interesting. I think mkdocs uses the toc extension by default, so that’d be why it works when not explicitly enabled. Possibly the plugin is interfering with the processing of the [TOC] marker though. I recall seeing a few relevant issues in the mkdocs/pymarkdown repos, I’ll have a dig..
Ahh, I think it is because of https://github.com/Python-Markdown/markdown/issues/100
And might be resolved by ensuring any markdown cells aren’t wrapped in any tags by the template
Ah, nice find. Thanks!
Turns out it does already work in mknotebooks if I surround the [TOC] marker with blank lines. This kinda makes sense based on the issue you linked, but is not very intuitive if [TOC] is the only content of the cell. 🤔
Do you think it's worth adding a preprocessor which adds blank lines around the [TOC] marker if the cell doesn't contain anything else?
Hmm. Not sure on that one. Could just publish a slightly better toc markdown extra?
