Feature request: enable [TOC] markers to insert table of contents in notebooks?

[maxalbert]

Many thanks for fixing the table of contents (as of git rev. 3bd9d3b). 👍😃

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?

[maxalbert]

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.

[greenape]

🤔 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..

[greenape]

Ahh, I think it is because of Python-Markdown/markdown#100

And might be resolved by ensuring any markdown cells aren’t wrapped in any tags by the template

[maxalbert]

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?

[greenape]

Hmm. Not sure on that one. Could just publish a slightly better toc markdown extra?

[kemistep]

jupyter can't show toc; but makdown can show toc, can you fix it ;