Just opening an issue to register my smile ;-)

I love things that are disruptive like this...

@mpacer and I had a conversation about this yesterday. One place where Markdown does add attributes to the resulting markup is with the HTML title attribute. It does this in a somewhat semantically confusing way, adding them to the round brackets (). So somthing like

[link text](http://link.url "Title")

becomes

<a href="http://link.url" title="Title">link text</a>

My understanding is that a more myst-like way of doing this same thing would be to pass the title attribute into the curly brackets:

[link text](http://link.url){title="Title"}

@mpacer and I agreed that we did not like the markdown way of doing this, but it should be flagged as another possible incompatibility.

One thing that is quite useful Markdown is the ability to fall back to HTML if Markdown is not expressive enough. This would be somewhat alleviated here by (1) the ability to pass attributes into markdown links/images and (2) the generally richer reST format. However, this is still an important feature to iron out for things like iframes, HTML video/audio, etc. The main options would seem to be

1. Using the default approach with reST, where you enter a raw HTML block:

.. raw: html
    <iframe src=''></iframe>

2. Use a more Markdown-style approach, where we identify HTML tags and let them pass through to the renderer:

<iframe src=''></iframe>

Since we are discussing basing this on a sphinx extension, option (1) would be easier, and probably more explicit, but there is an attractiveness to the ease of authoring with option (2).

While I really prefer ATX style headers, I've found myself challenged by how to implement multiline ATX style headers. Has anyone been condidering this?

The real challenge comes in reconciling two different semantics for multi-line headers.

On he one hand, is the problem of moderately long headers on the context of software development. Some software style guides effectively require headers that span multiple lines in the text format but are intended to be a single-line in the output format. This occurs, for example, if people are adhering to an 80 char per line limit for their files whether they are for source code or prose.

The other case is for you want to have a single header that actually include line breaks and therefore must span multiple lines in the final output format. Where this gets tricky is when the line break itself is semantic and occurs before an actual line break would occur in the text. This arises most often in the context of section titles that have a opening clause a colon (:) or em-dash (—) and a secondary clause that is long enough that it would break the line in a confusing or unconventional position.

Fernando told me about this today, and said that the idea was to support regular links like [foo](https://bar) and also allow customization like [foo](https://bar){type=img width=100%} or similar.

ReST already has a generic syntax for different link "types", that get routed through the extensible "role" system. For example, you can write

:img:`foo <https://bar>`

or

:ref:`introduction`

or

:ref:`as discussed in the introduction <introduction>`

And at least for paragraph level markup it has a generic idea of arbitrary key-value arguments, though I'm not sure if there's any equivalent for inline markup. Nonetheless, maybe it would make sense to say that [foo](https://bar){type=img} was exactly the same as

:img:`foo <https://bar>`

i.e. the word img here is naming a role, not a raw HTML tag?

Because there is a general adherence to the ATX style of headers this presents a great opportunity!

Specifically there is a well defined model for adding manual header ids by adding a {#my-id} after a space following the end of the header text.

Example Header {#example-id}

This syntax is used in pandoc to specify header ids link, which also supports a syntax for setext style headers as well.

I'm not sure how this would work out in light of #5.

I came across this lightweight Python package that converts Markdown to rST...perhaps it could be useful as a pre-processor for Sphinx that could be used to support Myst-like syntax:

https://github.com/miyakogi/m2r

Probably the most interesting thing about it is that m2r allows you to use directives and roles directly in the markdown, and passes those through normally to the rST (as opposed to recommonmark, which requires you to use eval_rst). I wonder if @chrisjsewell has heard of this?

We should likely grab name like on PyPI (mystjs on npm?) beforemaking any public announce.

Maybe I just missed it, but I don't see any mention of ReST's most pointlessly obnoxious limitation: the brokenness of nested inline markup. E.g. in markdown I can trivially do bold italics with a link but in ReST this requires extraordinary hacks.

Any serious work on ReST should just fix this. We've known how to write real parsers since, like, the 60s.

Markdown lists are almost compatible with reST lists, except that nested reST lists must be separated from the parent list by a blank line. This means that by default a lot of nested lists that are valid markdown are not valid reST.

As (AFAIU) this is going to be a Sphinx Extension on top of RST more than a complete custom parser/rendered; here are a project that implement (part of) the modification we'd like.

• https://github.com/ericholscher/sphinx-markdown-transform

I'm pretty sure Eric also have something that find ATX header and transform them for sphinx to understand, but I can't find it right now.

While these are in the markdown spec, AFAIK fenced ones are much more popular. At the same time having those makes myst the second markup format to recommend indenting by 3 spaces ;)

Perhaps there could be a parser setting that controls whether these are parsed as code?