Working with MyST Markdown

Overview¶

MyST is designed to create publication-quality documents written entirely in Markdown. The extensions and design of MyST is inspired by the Sphinx and reStructuredText (RST) ecosystems and is is a superset of CommonMark.

MyST allows you to directly create “directives” and “roles” that extend markdown to support technical and scientific documents. Directives are block-level extension points, like callout panels, tabs, figures or embedded charts; and roles are inline extension points, for components like cross-references, external references, citations, or inline math. MyST also supports rich information about linking to other documents in common services (like Wikipedia or a DOI link), these allow for rich-previews of the links as well as easy ways to include citations.

Typography¶

MyST is built on CommonMark Markdown, to learn more about that standard form of Markdown as well as a tutorial visit commonmark.org. CommonMark allows for headings, bold, italic, lists, links, images, code, breaks and quotes (see more) -- but overall is designed to be very simple to read and write as text! MyST adds various typography extensions to the markup including footnotes, inline math, and definition lists, try the demo below to get an idea of the markup.

Directives and Roles¶

Directives are multi-line containers that include an identifier, arguments, options, and content. Examples include admonitions, figures, and equations. At its simplest, you can use directives using a “fence” (either back-ticks or colons) and the name of the directive enclosed in braces ({name}).

For example, try editing the following {figure} directive, you can center the figure with an :align: center option or change the colons for backticks.

Roles are very similar to directives, but they are written entirely in one line. There are a number of roles included in MyST, including abbreviations, subscript, and superscript, as well as inline Math and Equations. The syntax of a role is:

Some content {rolename}`and here is my role's content!`

Of course, roles will only work if rolename is a valid role name! The abbr role creates inline abbreviations, for example, {abbr}`MyST (Markedly Structured Text)` will become MyST! When you hover over^[1] the abbreviation you will see the title appear!

Frontmatter¶

Frontmatter allows you to specify metadata about your page including the title, thumbnail, authors, and scientific identifiers like a doi. Adding frontmatter ensures that these properties are available to downstream tools or build processes like building Scientific PDFs. For example:

---
title: My First Article
thumbnail: ./thumbnails/nice-image.png
date: 2022-05-11
authors:
  - name: Mason Moniker
    affiliations:
      - University of Europe
---

Links & Cross-References¶

As you have seen in the links in MyST (e.g. Frontmatter), there is information that is pulled forward into your reading context on hover or click. We believe it is important to provide as much possible context when you are reading on elements like links to other pages, cross-references to figures, tables and equations as well as traditional academic citations^[2] (👈 see the footnote!). Additionally, all of these have fallbacks in static PDF or Word documents.

To link to a document, for example Frontmatter, is done through a simple Markdown link [](./frontmatter.md), you can put your own content in between the square brackets, but if you leave it out the link contents will be filled in with the title of the page. If you define the frontmatter on that page (i.e. the description and tooltip), you will also see that information when you hover over the link. This also works for links to Wikipedia (e.g. Ponies 🐴) as well as Github code (e.g. README.md).

To create a cross-reference, you need to label a “target”, like a figure, section, equation or table (or anything!!). To be referenceable, these elements can add the label option in many directives. To then reference the figure, use the link syntax again pointing to the label as the target [](#my-fig). If you leave the title blank the default will fill in with an enumerated “Figure 1”.

Citations¶

Citations are at the heart of technical writing, and are well handled by MyST!

If I have seen further it is by standing on the shoulders of Giants.

• Newton making a sarcastic remark directed at Hooke’s appearance?!

The easiest way to create a citation is just link to a DOI as any other link! For example:
[](https://doi.org/10.5281/zenodo.6476040) will create:
Cockett (2022).

If you already have a citation list locally as a BiBTeX file (*.bib), then you can reference the keys inside it using a similar syntax to LaTeX, but adapted to roles: {cite:p}`myst2023,jupyterbook2021`. The cite:p will create a parenthetical citation, or a textual citation using cite:t, the cite role can also be used, and will adapt to the citation style of the document. The citations will show up inline in your documents, and also automatically create a references section at the bottom of your page!

What’s Next?¶

We hope the above sections in this overview should have given you a sense of the types of things that MyST can do! Once you write a document in MyST, you can use the command line tools to translate that into a scientific PDF article, or a Word Document or a website like this site!

Check out the following tutorials for more step-by-step guides: