Typography

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$. 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$ is correct. The two roles for subscript and superscript are {sub} and {sup}^[1], respectively.

Keyboard Input¶

To denote textual user input from a keyboard, such as Ctrl + Space, you can use the {kbd} role^[2].

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.

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 a final paragraph whose text starts with -- or an em-dash (—), followed by the author or source. The blank > line is required!

The quotes can also be created using a directive (either {blockquote} or {epigraph}), which allows you to add classes or labels to the quote. MyST also supports {pull-quote} directive, which act as attention-grabbing visual elements.

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

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.