MyST Quickstart Guide

# Working with MyST Markdown

## #Overview

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

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 , , or ; and roles are inline extension points, for components like , , , or . 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 () -- but overall is designed to be very simple to read and write as text! MyST adds various typography extensions to the markup including , , and , 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 , , and . At its simplest, you can use directives using a "fence" (either ) 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 . 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 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 . For example:

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

As you have seen in the links in MyST (e.g. ), 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 (👈 click the footnote!). Additionally, all of these have fallbacks in static PDF or Word documents.

To link to a document, for example , 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. ) as well as Github code (e.g. ).

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!

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

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 , or a or a website like this site!

References
1. Cockett, R. (2022). Future of Research Communication &amp; 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 Tools
MyST Markdown Tools
Documentation