Skip to article content

Headings

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

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

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

Inline Text Formatting

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

strikethrough
Use the del or strike role, for example, {del}`text` yields text
underline
Use the u or underline role, for example, {u}`text` yields text
Note, using this can often be confused with a link and usage of underlines isn’t recommended, consider using strong or emphasis instead.
smallcaps
Use the sc or smallcaps role, for example, {sc}`MyST` yields 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:

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.

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.

Task Lists

You can use GitHub Flavoured Markdown to create task lists, these may be read only or editable depending on the use case or the theme used.

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[1], respectively.

Abbreviations

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.

Abbreviations in Frontmatter

You can also set abbreviations in your page or project frontmatter to replace all instances of your abbreviation without writing the role every time!

See Abbreviations for more information.

Quotations

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.

Definition Lists

Definition lists are based on the Pandoc definition list specification, starting with the term followed by a colon on the next line. For example:

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

Complex Definition Lists

Footnotes

Footnotes use the pandoc specification. A footnote is labeled with [^label] and can then be any alphanumeric string (no spaces), which is case-insensitive. This creates a link to the footnote definition, which is a line that starts with the same [^label]: and then the text of the footnote.

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.

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

Complex Footnotes
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication