MyST Markdown

Frontmatter

Frontmatter allows you to specify metadata and options about how your project should behave or render. Included in frontmatter are things like the document or project title, what thumbnail to use for site or content previews, authors that contributed to the work, and scientific identifiers like a doi. Adding frontmatter ensures that these properties are available to downstream tools or build processes like building Scientific PDFs.

Where to set frontmatter¶

Frontmatter can be set in a markdown (md) or notebook (ipynb) file (described as a “page” below) or in the project: section of a myst.yml file. When project frontmatter is set in a myst.yml file, those settings will be applied to all content in that project (apart from “page only” fields).

In a MyST markdown file¶

A frontmatter section can be added at the top of any md file using --- delimiters.

---
title: My First Article
date: 2022-05-11
authors:
  - name: Mason Moniker
    affiliations:
      - University of Europe
---

In a Jupyter Notebook¶

Frontmatter can be added to the first cell of a Jupyter Notebook, that cell should be a Markdown cell and use --- delimiters as above.

Using jupytext or a Markdown-based notebook?

If your Jupyter Notebook is described as a markdown file (e.g. using jupytext, or MyST), then this should be included in the frontmatter section as usual in addition to the jupyter key that defines the kernel and jupytext metadata.

In a `myst.yml` file¶

Frontmatter fields can be added directly to any project: section within a myst.yml file. If your root myst.yml file only contains a site: section, and you want to add frontmatter, add a project: section at the top level and add the fields there. e.g.

myst: v1
site: ...
project:
  license: CC-BY-4.0
  open_access: true

Available frontmatter fields¶

The following table lists the available frontmatter fields, a brief description and a note on how the field behaves depending on whether it is set on a page or at the project level. Where a field itself is an object with sub-fields, see the relevant description on the page below.

Table 1:A list of available frontmatter fields and their behaviour across projects and pages

field	description	field behaviour
`title`	a string (max 500 chars)	page & project
`description`	a string (max 500 chars)	page & project
`short_title`	a string (max 40 chars)	page & project
`name`	a string (max 500 chars)	page & project
`tags`	a list of strings	page only
`thumbnail`	a link to a local or remote image	page only
`subtitle`	a string (max 500 chars)	page only
`date`	a valid date formatted string	page can override project
`authors`	a list of author objects	page can override project
`affiliations`	a list of affiliation objects	page can override project
`doi`	a valid DOI, either URL or id	page can override project
`arxiv`	a valid arXiv reference, either URL or id	page can override project
`open_access`	boolean (true/false)	page can override project
`license`	a license object or a string	page can override project
`github`	a valid GitHub URL or `owner/reponame`	page can override project
`binder`	any valid URL	page can override project
`subject`	a string (max 40 chars)	page can override project
`venue`	a venue object	page can override project
`biblio`	a biblio object with various fields	page can override project
`math`	a dictionary of math macros (see Math Macros)	page can override project
`abbreviations`	a dictionary of abbreviations in the project (see Abbreviations)	page can override project

Field Behavior¶

Frontmatter can be attached to a “page”, meaning a local .md or .ipynb or a “project”. However, individual frontmatter fields are not uniformly available at both levels, and behavior of certain fields are different between project and page levels. There are three field behaviors to be aware of:

page & project: the field is available on both the page & project but they are independent
page only: the field is only available on pages, and not present on projects and it will be ignored if set there.
page can override project: the field is available on both page & project but the value of the field on the page will override any set of the project. Note that the page field must be omitted or undefined, for the project value to be used, value of null (or [] in the case of authors) will still override the project value but clear the field for that page.

The thumbnail is used in previews for your site in applications like Twitter, Slack, or any other link preview service. This should, by convention, be included in a thumbnails folder next to your content. You can also explicitly set this field to any other image on your local file system or a remote URL to an image. This image will get copied over to your public folder and optimized when you build your project.

thumbnail: thumbnails/myThumbnail.png

If you do not specify an image the first image in the content of a page will be selected. If you explicitly do not want an image, set thumbnail to null.

You can also set a banner image which will show up in certain themes, for example, the article-theme:

banner: banner.png

Authors¶

The authors field is a list of author objects. Available fields in the author object are:

Table 2:Frontmatter information for authors

field description

name a string - the author’s full name

orcid a string - a valid ORCID identifier with or without the URL

corresponding boolean (true/false) - flags any corresponding authors, you must include an email if true.

email a string - email of the author, required if corresponding is true

url a string - website or homepage of the author

roles

a list of strings - must be valid CRediT Contributor Roles

authors:
  - name: Penny Crediton
    roles:
      - Conceptualization
      - Data curation
      - Validation

CRediT Roles

There are 14 official contributor roles that are in the NISO CRediT Role standard. In addition to British english, incorrect case or punctuation, there are also a number of aliases that can be used for various roles.

Official CRediT Role	Alias
Conceptualization	`conceptualisation`
Data curation
Formal analysis	`analysis`
Funding acquisition
Investigation
Methodology
Project administration	`administration`
Resources
Software
Supervision
Validation
Visualization	`visualisation`
Writing – original draft	`writing`
Writing – review & editing	`editing`, `review`

affiliations

a list of strings that identify or create an affiliation or a full Affiliation object, for example:

authors:
  - name: Marissa Myst
    affiliations:
      - id: ubc
        institution: University of British Columbia
        ror: 03rmrcq20
        department: Earth, Ocean and Atmospheric Sciences
  	  - ACME Inc
  - name: Miles Mysterson
    affiliation: ubc

See Affiliations for more information on how to concisely write affiliations.

equal_contributor a boolean (true/false), indicates that the author is an equal contributor

deceased a boolean (true/false), indicates that the author is an deceased

twitter a twitter username

github a GitHub username

note a string, a freeform field to indicate additional information about the author, for example, acknowledgements or specific correspondence information.

phone a phone number, e.g. (301) 754-5766

fax for people who still use these machines, beep, boop, beeeep! 📠🎶

Affiliations¶

You can create an affiliation directly by adding it to an author, and it can be as simple as a single string.

authors:
  - name: Marissa Myst
    affiliation: University of British Columbia

You can also add much more information to any affiliation, such as a ROR, ISNI, or an address. A very complete affiliations list for an author at the University of British Columbia is:

authors:
  - name: Marissa Myst
    affiliations:
      - id: ubc
        institution: University of British Columbia
        ror: https://ror.org/03rmrcq20
        isni: 0000 0001 2288 9830
        department: Department of Earth, Ocean and Atmospheric Sciences
        address: 2020 – 2207 Main Mall
        city: Vancouver
        region: British Columbia
        country: Canada
        postal_code: V6T 1Z4
        phone: 604 822 2449
  - name: Miles Mysterson
    affiliation: ubc

Notice how you can use an id to avoid writing this out for every coauthor. Additionally, if the affiliation is a single string and contains a semi-colon ; it will be treated as a list. The affiliations can also be added to your project frontmatter in your myst.yml and used across any document in the project.

article.md

myst.yml

---
title: My Article
authors:
  - name: Marissa Myst
    affiliation: ubc
  - name: Miles Mysterson
    affiliations: ubc; stanford
---

affiliations:
  - id: ubc
    institution: University of British Columbia
    ror: https://ror.org/03rmrcq20
    isni: 0000 0001 2288 9830
    department: Department of Earth, Ocean and Atmospheric Sciences
    address: 2020 – 2207 Main Mall
    city: Vancouver
    region: British Columbia
    country: Canada
    postal_code: V6T 1Z4
    phone: 604 822 2449
  - id: stanford
    name: ...

If you use a string that is not recognized as an already defined affiliation in the project or article frontmatter, an affiliation will be created automatically and normalized so that it can be referenced:

Written Frontmatter

Normalized

authors:
  - name: Marissa Myst
    affiliations:
      - id: ubc
        institution: University of British Columbia
        ror: 03rmrcq20
        department: Earth, Ocean and Atmospheric Sciences
      - ACME Inc
  - name: Miles Mysterson
    affiliation: ubc

authors:
  - name: Marissa Myst
    affiliations: ['ubc', 'ACME Inc']
  - name: Miles Mysterson
    affiliations: ['ubc']
affiliations:
  - id: ubc
    institution: University of British Columbia
    ror: https://ror.org/03rmrcq20
    department: Earth, Ocean and Atmospheric Sciences
  - id: ACME Inc
    name: ACME Inc

Table 3:Frontmatter information for affiliations

field	description
`id`	a string - a local identifier that can be used to easily reference a repeated affiliation
`name`	a string - the affiliation name. Either `name` or `institution` is required
`institution`	a string - Name of an institution or organization (for example, a university or corporation) If your research group has a name, you can use both `name` and `institution`, however, at least one of these is required.
`department`	a string - the affiliation department (e.g. Chemistry 🧪)
`ror`, `isni`, `ringgold`	Identifiers for the affiliation (ROR, ISNI, and Ringgold). We suggest using https://ror.org if possible to search for your institution. `affiliations: - name: Boston University ringgold: 1846 isni: 0000 0004 1936 7558 ror: 05qwgg493`
`email`	a string - email of the affiliation, required if `corresponding` is `true`
`address`, `address`, `city`, `state`, `postal_code`, and `country`	affiliation address information. In place of `state` you can use `province` or `region`.
`url`	a string - website or homepage of the affiliation (`website` is an alias!)
`phone`	a phone number, e.g. `(301) 754-5766`
`fax`	A fax number for the affiliation
`collaboration`	a boolean - Indicate that this affiliation is a collaboration, for example, `"MyST Contributors"` can be both an affiliation and a listed author. This is used in certain templates as well as in JATS.

Date¶

The date field is a string and should conform to a valid Javascript data format. Examples of acceptable date formats are:

2021-12-14T10:43:51.777Z - an ISO 8601 calendar date extended format, or
14 Dec 2021
14 December 2021
2021, December 14
2021 December 14
12/14/2021 - MM/DD/YYYY
12-14-2021 - MM-DD-YYYY
2022/12/14 - YYYY/MM/DD
2022-12-14 - YYYY-MM-DD

Where the latter example in that list are valid IETF timestamps

Licenses¶

This field can be set to a string value directly or to a License object.

Available fields in the License object are content and code allowing licenses to be set separately for these two forms of content, as often different subsets of licenses are applicable to each. If you only wish to apply a single license to your page or project use the string form rather than an object.

String values for licenses should be a valid “Identifier” string from the SPDX License List. Identifiers for well-known licenses are easily recognizable (e.g. MIT or BSD) and MyST will attempt to infer the specific identifier if an ambiguous license is specified (e.g. GPL will be interpreted as GPL-3.0+ and a warning raised letting you know of this interpretation). Some common licenses are:

Common Content Licenses	Common Code Licenses
`CC-BY-4.0` `CC-BY-SA-4.0` `CC-BY-N-SA-4.0` `CC0-1.0`	`MIT` `BSD` `GPL-3.0+` `Apache-2.0` `LGPL-3.0-or-later` `AGPL`

By using the correct SPDX Identifier, your website will automatically use the appropriate icon for the license and link to the license definition.

Venue¶

The term venue is borrowed from the OpenAlex API definition:

Venues are where works are hosted.

Available fields in the venue object are title and url.

Some typical venue values may be:

venue:
  title: Journal of Geophysics
  url: https://journal.geophysicsjournal.com

venue:
  title: EuroSciPy 2022
  url: https://www.euroscipy.org/2022

Biblio¶

The term biblio is borrowed from the OpenAlex API definition:

Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover."

Available fields in the biblio object are volume, issue, first_page and last_page.

Some example biblio values may be:

biblio:
  volume: '42'
  issue: '3'
  first_page: '1' # can be a number or string
  last_page: '99' # can be a number or string

biblio:
  volume: '2022'
  issue: Winter
  first_page: Inside cover # can be a number or string

Reference

MyST Syntax Overview