Codecov Report

Attention: Patch coverage is75.00000% with10 lines in your changes missing coverage. Please review.

Project coverage is 89.74%. Comparing base(885651f) to head(32194f2).
Report is 210 commits behind head on master.

@@            Coverage Diff             @@##           master     #485      +/-   ##==========================================- Coverage   90.03%   89.74%   -0.30%==========================================  Files          16       16                Lines        2058     2097      +39     ==========================================+ Hits         1853     1882      +29- Misses        205      215      +10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report?Share it here.

See also documentation:https://myst-parser--485.org.readthedocs.build/en/485/syntax/optional.html#table-of-contents-lists

Thanks for the prototype - my main question is: what is the problem that this addition is trying to solve? You mention this would let people write documentation purely with CommonMark - is that something people have been requesting?

I think our main alternative would be to define a directive that behaved similarly, like:

```{toclist}[Displayed site name](https://example.com)[Displayed page name](page1.md)```

You'd lose the "pure commonmark" aspect though.

From a design standpoint:

• I agree that the+ is probably the least-used CommonMark token for lists.
• I think it will confuse people that they need to write something like[Link text](https://example.com "Example external link"). It seems like[Example external link](https://example.com) is what they'd expect to be able to do. I suggest removingLink text entirely from examples as it will make it seem like that text does something, when it does not.
• To that extent, if people have to write not-quite-markdown syntax like[Link text](https://example.com "Example external link"), then don't they lose the benefits of "Writing a TOCtree in pure CommonMark" (since the links themselves are not commonmark)

I don't have super strong opinions in general - as long as this is an optional syntax I think it's fine to evolve it over time as people use it.

Heya,

To that extent, if people have to write not-quite-markdown syntax likeLink text, then don't they lose the benefits of "Writing a TOCtree in pure CommonMark" (since the links themselves are not commonmark)

This is CommonMark syntax though. Perhaps you didn't realise the links can have titles?[link text](https://example.com "title") ->link text (if you hover over you'll see the title)

It seems likeExample external link is what they'd expect to be able to do. I suggest removing Link text entirely from examples as it will make it seem like that text does something, when it does not.

As explained in the initial comment, this would parseExample external link as markdown, which you would then have to work back to get the original raw text. this is not the case with titles.
I would note also, that the documentation does already clarify this, unless you think this is not clear:

ou mention this would let people write documentation purely with CommonMark - is that something people have been requesting?

yes, particularly in the notebook context

(also, as I note in the PR comment, it is similar to functionality recommonmark and nbsphinx already have)

what is the problem that this addition is trying to solve?

Copied from Slack:

To clarify, its not primarily meant to improve "user-friendliness" (although I believe it does), it is meant to improve "render-friendliness":

if you use:

```{toclist}...```

any non-myst renderer will just show literal text, whereas

- [text](page.md)

will "correctly" show a link to thepage.md document.

this is the "problem" being solved, not that users find it hard to use the toctree directive

As an example, go tohttps://github.com/executablebooks/MyST-Parser/blob/32194f2d45f351419b9e4dc7975c9a9d0aba6946/docs/syntax/optional.md#table-of-contents-lists and if you click on the link, it will correctly take you tohttps://github.com/executablebooks/MyST-Parser/blob/32194f2d45f351419b9e4dc7975c9a9d0aba6946/docs/syntax/subsection.md.

I think our main alternative would be to define a directive that behaved similarly, like:

this is why your suggestion does not solve the issue: you're still using it within a code fence, so it's still just going to be rendered as literal text

Sorry a bit late to this party.

I'm usually in favour of running these sort of extensions through a directive -- I typically think of coremarkdown as simple markup syntax without any large state transformations (other than visual or direct translations). For example, going from[text](link) is a simple state transformation but acontext specific interpretation of a list could be confusing.

Not suggesting it would ever be, but I think it is important this type of extension wouldnot be enabled by default (so it would be purely opt in syntax)

it is important this type of extension would not be enabled by default

just to clarify, no extensions are enabled by default, I will even be removing the current dollarmath on by default behaviour

cheers for the feedback, its always welcome 👍

@chrisjsewell : I like the concept. How could we include :caption: in some way?

Maybe

Caption:+ [Link text](subsection.md)+ [Link text](https://example.com "Example external link")

A few more thoughts below:

This is CommonMark syntax though

Ah gotcha - I did not realize that, you can disregard my comments about this not being CM compliant.

I use instead oftitle. A key reason is because the latter is parsed to markdown tokens, and so you would need to convert it back to plain text, which would be tricky.

I agree that we can clarify things with documentation, though I worry this will still be unintuitive to folks so we'd pay a UX penalty even if it were documented.

Since the main reason for using the"title" syntax is implementation complexity, is there a low-hanging fruit we could shoot for to compromise? E.g., what if you enforced the use of a literal as the title?[`my section title`](page.md), would that simplify the parsing?

captions

The syntax you proposed here seems reasonable to me:

+ `toctree 1 caption`   + [Link text](subsection1.md)   + [Link text](https://example.com "Example external link")+ `toctree 2 caption`   + [Link text](subsection2.md "a title")

@chrisjsewell: I just came across a use case for this extension again.
In this instance, we want to serve both the casual reader (VS code preview or bitbucket preview) as well as the sphinx documentation generator, and we ended up using "hidden toctrees" and writing all links twice. I'd be happy to see this extension in a future release of myst-parser 👍🏼

Just one point: Some markdown linters complain if you use the same bullet element on different levels, so maybe do something like:

+ `toctree 1 caption`   - [Link text](subsection1.md)   - [Link text](https://example.com "Example external link")+ `toctree 2 caption`   - [Link text](subsection2.md "a title")

But it's also okay to keep everything "+"