Follow us on TwitterFork us on GitHub
MyST Markdown



Markdown syntax denotes headers starting with between 1 to 6 #. For example, a level 3 header looks like:

### Heading Level 3 Try changing the number of `#`s to change the `depth`.

An alternative syntax, , is also supported for level 1 and 2 headers.

To reference a heading in your text, you can use the (target)= syntax, see for more.

#Inline Text Formatting

Standard inline formatting including bold, italic, code, as well as escaped symbols and line breaks:

**strong**, _emphasis_, `literal text`, \*escaped symbols\*

Use the del or strike role, for example, {del}`text` yeilds text
Use the u or underline role, for example, {u}`text` yeilds text
Note, using this can often be confused with a link and usage of underlines isn't recommended, consider using strong or emphasis instead.
Use the sc or smallcaps role, for example, {sc}`MyST` yeilds MyST

#Line Breaks

To put a line break, without a paragraph, use a \ followed by a new line. This corresponds to a <br> in HTML and \\ in LaTeX\LaTeX. For example, here is the worlds shortest poem:

Fleas \ Adam \ Had 'em. By Strickland Gillilan

#Bullet points and numbered lists

You can use bullet points and numbered lists as you would in standard markdown. Starting a line with either a - or * for a bullet point, and 1. for numbered lists. These lists can be nested using two spaces at the start of the line.

- Lists can start with `-` or `*` * My other, nested * bullet point list! 1. My numbered list 2. has two points

For numbered lists, you can start following lines with any number, meaning they don't have to be in numerical order, and this will not change the rendered output. The exception is the first number, which if it is not 1. this will change the start number of the list.

#Subscript & Superscript

For inline typography for subscript and superscript formatting, it is best practice to use a text-based representation over resorting to math exponents, i.e. 4$^{th}$. This is required in some journal submissions, and using these roles ensure that the output in HTML and LaTeX\LaTeX is correct. The two roles for subscript and superscript are sub and sup, respectively.

H{sub}`2`O, and 4{sup}`th` of July


To create an abbreviation, you can use the abbr role, in HTML this will ensure that the title of the acronym or abbreviation appears in the title when you hover over the element. In the role, follow the syntax HR (Heart Rate) with the abbreviation first followed by the expanded title in parenthesis.

Well {abbr}`MyST (Markedly Structured Text)` is cool!


Quotations are controlled with standard Markdown syntax, by inserting a caret (>) symbol in front of one or more lines of text. You can provide an attribution to a blockquote by adding - author or source to the final line.

> We know what we are, but know not what we may be. > - Hamlet act 4, Scene 5

#Definition Lists

Definition lists are based on the Pandoc definition list specification.

Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces.

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraphs, code blocks, lists, etc.)

Pandoc documentation

Here's an example:

Term 1 : Definition Term 2 : Definition


Footnotes use the pandoc specification. A footnote is labeled with [^label] and can then be any alpha-numeric string (no spaces), which is case-insensitive.

  • If the label is an integer, then it will always use that integer for the rendered label (i.e. they are manually numbered).
  • For any other labels, they will be auto-numbered in the order which they are referenced, skipping any manually numbered labels.

All footnote definitions are collected, and displayed at the bottom of the page for print or as hover-notes online. Note that un-referenced footnote definitions will not be displayed.

- This is a manually-numbered footnote reference.[^3] - This is an auto-numbered footnote reference.[^myref] [^myref]: This is an auto-numbered footnote definition. [^3]: This is a manually-numbered footnote definition.

Any preceding text after a footnote definitions, which is indented by four or more spaces, will also be included in the footnote definition.