Writing a Scientific Paper using MyST

Curvenote uses a flavour of Markdown called MyST Markdown (Markedly Structured Text), which is designed to create publication-quality, computational documents written entirely in Markdown.

MyST Markdown Overview¶

MyST is a superset of CommonMark (a standard form of Markdown) with special syntax for citations, cross-references, and block and inline extension points called “directives” and “roles”. MyST is influenced by reStructuredText (RST) and Sphinx – pulling on the nomenclature and introducing additional standards where appropriate.

Typography¶

The official documentation for MyST Markdown is found on mystmd.org, below we give some brief documentation for writing content.

Basic Markdown¶

Documents are Markdown, .md, and have additional features when compiled with a tool like the curvenote or mystmd CLIs. A full list of the syntax can be found in the typography documentation, including ### for headings, _ for emphasis, ** for strong, backticks for `code`, and - for bullet points.

Extended Typography¶

In addition to the basic markdown, MyST includes extended typography for things like definition lists, footnotes, superscript, quotation authors, and task lists.

Citations¶

Citations can be added inline using @cite-key syntax and having a BibTeX file in your project. You can also directly link to DOIs using @10.5281/zenodo.6476040, which will create a hover reference Cockett, 2022 and a references section at the bottom of the page. For multiple references in a parenthetical use [@cite-key1; @cite-key2]. See the full MyST documentation on citations and bibliographies.

Block Content¶

Block-level content, or directives, provide multi-line containers surrounded by either backticks or colons that include a type, arguments, options, and content. Examples include callout panels, figures, equations and tables. You can use directives using the following markup:

The directive above is of type note, and can take an arguments of the note’s title, as well as a number of options in :key1: value syntax. A common option to use is label, which allows for you to cross-reference content.

Figures¶

In addition to the markdown ![](image.png) syntax to create images, you can create figures in MyST with captions. These are the {figure} directive, and can be labeled and referenced using the same syntax as citations. The figure numbering is automatic. See figure documentation for more.

Inline Math and Equations¶

Equations can be created using a {math} directive and inline “dollar-math”, both of these can also have a label and cross-referenced in text. See full documentation on math and equations.

Tables¶

Tables can be created using GFM tables and a caption/label added using the {table} directive. See the documentation on tables.

Cross Referencing¶

Cross-references can be added in the exact same way as citations, using an @fig:label syntax, by default this adds the kind of the element that you are referencing and the auto-generated number (e.g. Figure 12). To get more specific about the way that you reference, you can use a markdown link: [See %s](#fig:label), the %s will be replaced by the number (i.e. See 12). See full documentation for information on additional targets, numbering and other rules.

Abstracts and Parts¶

To define parts of your document, like an abstract, use the page frontmatter. The full documentation on page parts shows how to create these inline or in a notebook cell.

---
title: My Paper
abstract: |
  This is a multi-line
  abstract.
---