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. 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.
- 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:
Enhance your MyST documents with interactivity, open scholarship, and reproducibility.
Learn how to use computation and execution with Jupyter in MyST.
Export MyST documents to a Word document, PDF, and !
See an overview of MyST Markdown syntax with inline demos and examples.
Learn how to use MyST in Jupyter Interfaces.
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.
If port
3000
is in use on your machine, an open port will be used instead, follow the link provided in the terminal.By default the
myst clean
command doesn’t remove installed templates or cached web responses; however, the function can with a:myst clean --all
, ormyst 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:If the server stopped, you can restart the server using
myst start
.Where with , or between an H1 and an H6!
Abbreviations are also great structured data for screen-readers!
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.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 💥.
- Cockett, R. (2022). Future of Research Communication & Collaboration. 10.5281/ZENODO.6476040
- 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