Skip To Article

Working with MyST Markdown

An overview of syntax features

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
---

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.

Try clicking the footnote above, you can nest information and interactive figures for the interested reader! You can help with reading comprehension by around 26% by providing information when the reader needs it!!

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. Ponyies 🐴) 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.

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:

Footnotes
  1. If you aren’t familiar with git, it isn’t required for this tutorial, you can download the zip file with the contents from the quickstart repository.

  2. If port 3000 is in use on your machine, an open port will be used instead, follow the link provided in the terminal.

  3. By default the myst clean command doesn’t remove installed templates or cached web responses; however, the function can with a:
    myst clean --all, or
    myst clean --templates --cache.

    Before deleting any folders myst will confirm what is going to happen, or you can bypass this confirmation with the -y option. For example:

  4. If the server stopped, you can restart the server using myst start.

  5. Where nNn \in \mathbb{N} with n6n \leq 6, or between an H1 and an H6!

  6. Abbreviations are also great structured data for screen-readers!

  7. For example, in Head et al. (2021) the authors showed you can speed up comprehension of a paper by 26% when showing information in context, rather than requiring researchers to scroll back and forth to find figures and equations.

    Imagine if all of science was ⚡️ 26% faster ⚡️[3]!! (👈💥)
    Designing the user-experience of scientific communication is really important.

  8. Just as an example of having lots of helpful information at your finger-tips, it would be nice to see the video of that article, right? Well here it is:

    Can’t do that in a PDF! [4] (👈💥)

  9. I mean, now that you are down the rabbit-hole, we can get you back on track with a demo of referencing equations (👈💥)

    Or maybe you want to explore an 💥 interactive figure 💥.

References
  1. Cockett, R. (2022). Future of Research Communication & Collaboration. 10.5281/ZENODO.6476040
  2. Head, A., Lo, K., Kang, D., Fok, R., Skjonsberg, S., Weld, D. S., & Hearst, M. A. (2021, May). Augmenting Scientific Papers with Just-in-Time, Position-Sensitive Definitions of Terms and Symbols. Proceedings of the 2021 CHI Conference on Human Factors in Computing Systems. 10.1145/3411764.3445648
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.