-
-
Notifications
You must be signed in to change notification settings - Fork 235
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature Request: Support for [[_TOC_]]
#1084
Comments
[[_TOC_]]
[[_TOC_]]
Can you find a me a reference to this in the GitHub docs somewhere? I can't seem to dig anything up on this. That said that should be an easy add - we can use a render extension and inject the TOC using the logic that already exists to generate a TOC (from the Bookmarks sidebar). The main issue I have with this is that it's going to slow down document rendering slightly as the TOC would have to be regenerated all the time. |
Here is the reference to the TOC feature of GitLab Flavored Markdown (GLFM). GitHub does not support |
Ok, I've added this feature: TOC gets rendered into the document on every re-render so it's dynamic and updates with the document changes. The document outline now also has a new button that inserts this tag into the page in addition to the existing behavior of embedding a static TOC. Important to understand though that this only work if you're using MM to preview or render HTML, or if the destination service that renders the Markdown supports this tag. Otherwise the tag ends up getting displayed in the document (ie. on GitHub which doesn't support it) . |
It'll work with anything that generates full HTML output which includes PDF and print output which just 'prints' the html content. |
Thank you for the prompt implementation! It works as I expected except for headings containing inline code with a single ### Directories in `SomeProjectRoot\` MM v3.2.8 generates the following invalid TOC entry for the heading above: [Directories in SomeProjectRoot\](#directories-in-someprojectroot)
Expected TOC entry: [Directories in SomeProjectRoot\\](#directories-in-someprojectroot) The rendering is correct in MM's Document Outline, GitLab, Azure DevOps and Typora. BTW: It would be nice if MM's Document Outline allowed headings to be collapsed and expanded. |
I encountered three other issues with the
EXAMPLES: The following heading structure is not normalized because it starts with a heading of level 2 (instead of 1) The missing heading of level 3 may be considered as mistake that the document author should fix anyway. There is also a rare issue when you would like to write something about the |
I encountered another issue with the TOC tag using MM v3.2.9.3. The tag is not expanded correctly if the heading contains pairs of EXAMPLE:
MM generates the following invalid TOC entry for the heading above:
The rendered TOC entry reads "Features of C17, C20 and C++23", where "17, C" is underlined. Expected TOC entry:
|
Thanks... Fixed. The fix was a bit tricky - reason it didn't work is because I was using HTML document to parse (reusing what's used for the Doc outline). That doesn't work though because we need to make sure we can retrieve the raw Markdown including the So code now uses the Markdown parser to parse the Markdown document to get headers and then explicitly checks each subblock for escape characters which are injected into the generated output. This fixes the |
One thing that I noticed and forgot about: The manual TOC generates a TOC that shows only headings that occur after the injected TOC, while the new |
Does the new implementation also fix the following issue with inline code ? The static TOC is correct while the dynamic TOC loses the inline code formatting and even generates rubbish when the inline code ends with |
Yeah looks like it: I think the inlines were fixed for the document outline (which now uses the same mechanism). The new code uses the Markdown document to find headers and then based on the type of text fixes it up. There may still be edge cases I would think where this doesn't work. Markdown is not a perfect 2-way markup language - things can easily get lost in the back and forth. But I think most of the more common scenarios are addressed. |
Ok I was too quick on that - no that doesn't work if the code inside of the inline is 'escaped' text like a path in your example. The only way this works if the inline code is kept intact. Slashes would be easy to fix, but there are million things that could be inside of the an inline that don't render right as markdown. Like HTML markup, html entities etc. So now I render the inline as an inline into the TOC: I don't really like the way that looks but there's really no reliable way to make that work without the inlines. Slashes are only one thing - it could be many, many other escaped characters, but the parser doesn't know about that because the text is an inline code block that's treated as well an linline code block. The only way to produce reliable output here is to bring in any Markdown from the header text into the TOC or there could be rendering issues (like your C++ or underscores, or HTML entities or slasshes etc.). For the Document outline this is simpler because there's no escaping happening there, so using the plain text in the actual outline works (and that's what it's been doing). |
GitLab, Azure DevOps and Typora support
[[_TOC_]]
to generate a table of contents dynamically. It would be nice if MarkdownMonster joined this league.The text was updated successfully, but these errors were encountered: