Finalise syntax

[chrisjsewell]

Agree that all the core syntax elements are present, and their format is acceptable

Related issues:

• Have a special syntax for page titles? #4
• Add footnote syntax? #98

[chrisjsewell]

Other syntax from rST to consider:

Substitution references, can be e.g. text, an image, a hyperlink, or (special) directive:

 |sub|

.. |sub| image:: myimage.png

Footnote references (also citation references are similar):

A footnote.[#1]_

.. [#1] A numerical footnote

Also implemented in some flavours of Markdown (see Extended Syntax):

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

(note its not technically compliant with CommonMark, as discussed here)

[chrisjsewell]

Note to self; in the documentation, should also highlight the fact that MyST can do nested inline markup, which rST cannot, e.g. Here's a link with italic text.

[akhmerov]

My 5c: I didn't see a good use for substitution references, aside of counteracting other rst limitations/annoyances.

[choldgraf]

I'm "meh" on substitutions...it doesn't seem super useful to me given the added cognitive burden. Footnotes I think are worth implementing - I believe that Pandoc uses

[^myfootnote]

[^myfootnote]: My footnote text

syntax.

---

Sometimes I also wonder if the same syntax style could be used for sidebar notes, like:

This is [>mysidebarnote]

[>mysidebarnote]: And here is the sidebar note

but that's for a different issue :-)

[najuzilu]

It would be great to finalize the syntax for footnote references since we have a few test cases that use them. Another thing to consider regarding footnote references could be automatic enumerate numbering.

[mmcky]

re: substitutions. It isn't something we need straight away but I think substitutions are useful when building more complex tables. For example adding a multiline code block is harder to do inside of a table -- when you can use simple labels and substitute in the code blocks from a list below it.

[choldgraf]

@mmcky just a note that I've found that having markdown-style cell fences for directives has helped with this a bit. You have more control over the whitespacing etc which might make it easier to make these complex tables with directives

[chrisjsewell]

I think this is pretty locked in now