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.

GFM Table
List Table

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.

article.md
---
title: My Paper
abstract: |
  This is a multi-line
  abstract.
---
References
  1. Cockett, R. (2022). Future of Research Communication & Collaboration. 10.5281/ZENODO.6476040