MyST Quickstart Guide

Working with MyST Markdown

An overview of syntax features

#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 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 , , and , try the demo below to get an idea of the markup.

### Heading Level 3 Try changing the number of `#`s to $n$[^math] to change the **depth** of the _heading_. 1. Learn about [Markdown](https://en.wikipedia.org/wiki/Markdown) - Go through a [tutorial](https://commonmark.org/help/tutorial/) [^math]: Where $n \in \mathbb{N}$ with $n \leq 6$, or between an H1 and an H6!

#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 ) 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.

:::{figure} https://source.unsplash.com/random/400x200?meditation :align: right The picture would look better if it is `:align: center`-ed! :::

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 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: Jane Bloggs
    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 (๐Ÿ‘ˆ click 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. 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".

```{figure} https://source.unsplash.com/random/500x200/?mountain :name: my-fig :align: center My **bold** mountain ๐Ÿ”๐Ÿš . ``` Check out [](#my-fig)!!

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

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!

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