Other TOC syntax pattern

[jjarava]

Hi!

I've just discovered Typora, and I'm liking it quite a lot; it certainly is covering most if not all of what I'm looking for in a MarkDown writing environment!

Quick suggestion: Use <!-- TOC --> as the "magic string" for the TOC placement, like Marked 2 does (check http://marked2app.com/help/Special_Syntax.html). The reasoning is, when viewed with viewers that "understand" the syntax, the TOC should appear, but if the processor doesn't know what to do with it, it'll just strip it out so there's not an unwieldy [TOC] tag

I understand that removing [TOC] would likely cause a bit of "noise", but I'd be nice to have the other syntax as an alternate

Thanks!

[abnerlee]

I have seen users use like this

<!-- TOC -->
- [H1](#h1)
- [H2](#h2)
<!-- /TOC -->

For such user case, typora will render an "extra" TOC.

[vassudanagunta]

Any extensions to GFM/CommonMark should be done in a way that degrades gracefully when viewed in or processed by another GFM compatible or even standard Markdown tool. See #1223.

How things are rendered here on GitHub itself is a good test. So let's try both:

Below is `[toc]`:

[toc]

Below is `<!-- TOC -->`

<!-- TOC -->

Renders as:

---

Below is [toc]:

[toc]

Below is <!-- TOC -->

---

Which is better? More graceful? In this case I guess it depends on whether you want the missing TOC to be obvious or invisible. I lean toward [toc], though not sure if it collides with Markdown link syntax.

Another option is the simply add a configuration option, a blank field where the user can enter what they want, defaulting to [toc] for backward compatibility, but also allowing none:

Table of Contents mark: ___________

/cc @Crissov @KirkMunro

[Crissov]

Markdown and Commonmark do not use any predefined strings of (English) text, i.e. keywords. Alas, some extensions do.

Personally, I have also not yet come to a conclusion on which syntax I would prefer for invoking and placing automatically generated content like tables of contents, figures or references.

[KirkMunro]

While I appreciate Markdown and CommonMark's decision to avoid the use of any predefined strings of English text, I think there are cases where it is justified. Symbols simply aren't enough sometimes. Do the people driving the CommonMark standard consider not only which symbols are used when, but which international keyboards provide easy access to those symbols, and which do not? Internationalization is very hard, and maybe too idealistic for what is essentially a markup language. Adoption and use of markdown may be pushing it beyond it's original goals, where symbols may not be enough to define document styling, and that's not necessarily a bad thing, as long as it's properly managed/planned.

That said, in a tool I manage, we were looking at using @toc(arguments) for the replacement, or something similar, because we overload @... for text we want replaced, not styled. It conflicts with at-mentions in GFM, but those only apply to issues, comments, etc., and not to actual markdown files, so I'm ok with that.

If you really want something that is purely defined with symbols, maybe mixing the table syntax with @ could work well across the board, but this would assume there is only one type of TOC you would want injected with no options:

|@|

I'm not sure how you would take that and make it work for a flexible TOC, which could be generated to a specific heading depth, including figures or not, etc. -- those options are important.

[abnerlee]

Summary of existing syntax of [TOC]

1. [toc] support by stackedit, https://pandao.github.io/editor.md/en.html, etc.

2. * this unordered seed list will be replaced by toc as unordered list
   {:toc}
   

   jekyll and Kramdown

3. <!--TOC--> mark2

4. use ol, and wrap with <!--TOC--> and <!--/TOC--> https://atom.io/packages/markdown-toc

5. Others https://github.com/isaacs/github/issues/215

3 and 4 won't bring any noise for markdown parser that does not support "Table of Contents", but they are incompatible with each other.

[pjeby]

I personally use tools that do <!-- toc --> and <!-- tocstop -->, rather than /toc at the close. So there are a LOT of formats out there.

[Crissov]

If you want something novel, language-independent and customizable, how about this?

<!--
1. ##
   - ###
-->

That is, all second-level headings become the top-level entries in the ToC and are numbered, while third-level headings are also included but without a number. The HTML comment would be optional but improves compatibility.

[pjeby]

I don't see any reason to do something novel -- there are already way too many ways to do it as-is.

[rahul-ahluwalia]

Is there a way to give the user the option to confirm? I may be the only one, but I’m looking for {{TOC}} specifically. Would love to be able to define my own styles so that one solution works for all.

[rockandska]

If typora could interpret this kind of comment who seems portable, it would allow to generate a plain markdown TOC and use two comments as a marker.

• It doesn't implement something new
• it seems more portable
• plain markdown even in source mode

In Remarkable for example, it results as :

[seamusdemora]

Color me dumb, but I'm horribly confused by all of this. Here's why:

• I use Typora for ~ 2 years now & like it!
• I use Typora primarily for creating content in my GitHub repos (i.e. GFM)
• Many files in my repos benefit hugely from a table of contents
• I need/want an automated way to generate & update a ToC in my *.md files

While using Typora, selecting Table of Contents from the Paragraph menu item instantly generates a great-looking ToC! It's a working ToC in that I can click an element in the ToC, and the display adjusts to show the correct section of the document in Typora.

I understand that the document itself contains only a [TOC] tag (visible when viewed in source mode), and that the [TOC] tag isn't supported by GitHub, etc. Consequently, I cannot upload a *.md file with the [TOC] tag, and have the ToC rendered. I get that much...

What I don't understand is why this working ToC cannot be rendered by Typora as GFM in some fashion so that it can be copied-and-pasted into my *.md file. This feels like Typora is teasing users... Typora said, "Here's a working ToC Loser User - but you can't have it! Ha ha ha!"

Please explain why this can't be done.

(And please forgive the theatrics - I just wanted to try and make this clear)

[pjeby]

@seamusdemora Some of us users are worried about how much Typora already takes upon itself to alter the contents of our files without our knowledge or consent. Even if Typora did have an option to generate or update an embedded table of contents, I would want it to be a manual step or command, not something that was altered automatically while I might be (say) making edits to a file that's part of some other person's project I've checked out of Github.

So, that would be one reason why "this working ToC cannot be rendered as GFM in some fashion". Not only are there competing schemes to label the block to be updated, but there also needs to be a way for the user to control whether it is actually updated or not, and when.

That's why I personally use markdown-toc, as I can decide when to run it (e.g. before a checkin) rather than wanting Typora updating it whenever I open a file that might have an out-of-dat TOC... or worse, rewriting a TOC generated by some other tool.

[Crissov]

One problem is that although many implementations, including Githubʼs cmark-gfm, automatically generate unique anchors for headings, they do so in different ways, e.g. spaces may be changed to underscores or hyphens, certain characters may be dropped or not, a static prefix or suffix may be added etc. (I hope Commonmark will recommend a single way someday.) For the same reason, you cannot insert manual links to other sections into your document yet, nor can you manually add explicit anchors. Therefore, while Typora could transform its custom [TOC] code into a standard nested list of items resembling the texts of headings, it could not hyperlink its entries.

PS: There are several browser extensions that generate interactive TOCs for readmes (or any previewed markdown files) on Github. Arguably, Github should provide that functionality themselves for everyone.

[kinoute]

Any news on this? It could be nice, when adding a Table of Contents, to have the choice of the syntax (Github, Gitlab etc). Or add an option for the preferred syntax in the preferences?

[Blackhawke]

I'm curious as to why adding YAML support got pushed to this thread when most of it seems to be about TOCs?

Adding YAML support doesn't change files, but it would increase the program's search and indexing abilities which Zettlkasten style note repositories and other similar applications require.

[seamusdemora]

Some of us users are worried about how much Typora already takes upon itself to alter the contents of our files without our knowledge or consent. Even if Typora did have an option to generate or update an embedded table of contents, I would want it to be a manual step or command, not something that was altered automatically while I might be (say) making edits to a file that's part of some other person's project I've checked out of Github.

So, that would be one reason why "this working ToC cannot be rendered as GFM in some fashion". Not only are there competing schemes to label the block to be updated, but there also needs to be a way for the user to control whether it is actually updated or not, and when.

That's why I personally use markdown-toc, as I can decide when to run it (e.g. before a checkin) rather than wanting Typora updating it whenever I open a file that might have an out-of-dat TOC... or worse, rewriting a TOC generated by some other tool.

AFAICT, nothing was explained by this post. AFAIC, what other tools people use is irrelevant.

In case no one else has noticed: This thread has been open for over 4 years, and it seems we are no closer to having a functional ToC feature in Typora. Some of us users are wondering...