Repository navigation
Finalise syntax #31
Description
Activity
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)
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.
Reacted by Anton AkhmerovMy 5c: I didn't see a good use for substitution references, aside of counteracting other rst limitations/annoyances.
Reacted by Chris Sewell and Martin Hasoň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 textsyntax.
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 notebut that's for a different issue :-)
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.
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.I think this is pretty locked in now
Agree that all the core syntax elements are present, and their format is acceptable
Related issues: