MyST MarkDown Typography¶

MyST is a strict superset of the CommonMark syntax specification. It adds features focussed on scientific and technical documentation authoring, as detailed below.

Headings¶

Markdown syntax denotes headers starting with between 1 to 6 #.

### Heading Level 3

Note, that headings that are not at the root level of the document will not be included in the table of contents. Using the attrs_block extension, you can also add classes to headings

> {.bg-primary}
> ### Paragraph heading

Paragraphs¶

Paragraphs are block of text separated by a blank line.

Using the attrs_block extension, you can also add classes to paragraphs:

{.bg-primary}
Here is a paragraph with a class to control its formatting.

Thematic breaks¶

You can create a thematic break, to break content between themes, using three or more *, -, or _ characters on a line by themselves.

* * *

Inline Text Formatting¶

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

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

The strikethrough extension allows you to add strike-through text:

~~strikethrough with *emphasis*~~

The smartquotes and replacements extensions can improve the typography of common symbols:

Smart-quotes 'single quotes' and "double quotes".

+-, --, ---, ... and other replacements.

Using the attrs_inline extension, you can also add classes to inline text spans:

A paragraph with a span of [text with attributes]{.bg-primary}

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.

Fleas \
Adam \
Had 'em.

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.

{style=lower-alpha}
1. a
2. b

{style=upper-alpha}
1. a
2. b

{style=lower-roman}
1. a
2. b

{style=upper-roman}
1. a
2. b

Using the tasklist extension, you can also create task lists:

- [ ] An item that needs doing
- [x] An item that is complete

Subscript & Superscript¶

For inline typography for subscript and superscript formatting, the sub and sup role, can be used respectively.

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

Quotations¶

Quotations are controlled with standard Markdown syntax, by inserting a caret (>) symbol in front of one or more lines of text.

> We know what we are, but know not what we may be.

Using the attrs_block extension, you can also add an attribution attribute to a block quote:

{attribution="Hamlet act 4, Scene 5"}
> We know what we are, but know not what we may be.

Definition lists and glossaries¶

Using the definition lists extension, you can define terms in your documentation, using the syntax:

Term 1
: Definition

Term 2
: Longer definition

  With multiple paragraphs

  - And bullet points

Using the attrs_block extension, you can also add a glossary class to a definition list, that will allow you to reference terms in your text using the term role:

{.glossary}
my term
: Definition of the term

{term}`my term`

Field lists¶

Using the field lists extension, you can create field lists, which are useful in source code documentation (see Sphinx docstrings):

:param arg1: A description of arg1
:param arg2: A longer description,
    with multiple lines.

    - And bullet points
:return: A description of the return value

Comments¶

You may add comments by putting the % character at the beginning of a line. This will prevent the line from being parsed into the output document.

For example, this won’t be parsed into the document:

% my comment

a line
% a comment
another line

Footnotes¶

Footnotes use the pandoc specification. Their labels start with ^ and can then be any alphanumeric 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 (in the order they are referenced). 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, and the text is rendered as MyST Markdown, e.g.

A longer footnote definition.[^mylongdef]

[^mylongdef]: This is the _**footnote definition**_.

    That continues for all indented lines

    - even other block elements

    Plus any preceding unindented lines,
that are not separated by a blank line

This is not part of the footnote.

By default, a transition line (with a footnotes class) will be placed before any footnotes. This can be turned off by adding myst_footnote_transition = False to the config file.