Skip to article content

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.

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.

version: 1
site: ...
project:
  license: CC-BY-4.0
  open_access: true

Composing multiple .yml files

You may separate your frontmatter into multiple, composable files. To reference other files from your main myst.yml file, use the extends key with relative path(s) to the other configuration files:

version: 1
site: ...
project: ...
extends:
  - ../macros.yml
  - ../funding.yml

Each entry listed under extends may be a relative path to a file or a URL. URLs must be direct links to files which are downloaded and cached locally. The files must contain valid myst.yml structure with version: 1 and site or project keys. They may also have additional entries listed under extends.

Composing files together this way allows you to have a single source of truth for project frontmatter that may be reused across multiple projects, for example math macros or funding information.

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 behavior across projects and pages

fielddescriptionfield behavior
titlea string (max 500 chars, see Titles)page & project
subtitlea string (max 500 chars, see Titles)page & project
short_titlea string (max 40 chars, see Titles)page & project
descriptiona string (max 500 chars)page & project
exportsan export object, see Exporting documentspage & project
downloadsa download object, see Downloads, Links and Static Filespage & project
labela string (max 500 chars) to identify the page in cross-referencespage only
tagsa list of strings. Use to categorize posts/articles or the project to make it easier for readers to find related content within your site.page & project
thumbnaila link to a local or remote imagepage & project
bannera link to a local or remote imagepage & project
datea valid date formatted stringpage can override project
keywordsa list of strings. Use in articles to highlight key concepts and facilitate indexing in scientific databases.page can override project
authorsa list of author objects, see Authorspage can override project
reviewersa list of author objects or string ids, see Reviewers, Editors, Funding Recipientspage can override project
editorsa list of author objects or string ids, see Reviewers, Editors, Funding Recipientspage can override project
affiliationsa list of affiliation objects, see Affiliationspage can override project
doia valid DOI, either URL or idpage can override project
arxiva valid arXiv reference, either URL or idpage can override project
open_accessboolean (true/false)page can override project
licensea license object or a string, see Licensespage can override project
copyrighta stringpage can override project
fundinga funding object, see Fundingpage can override project
githuba valid GitHub URL or owner/reponamepage can override project
binderany valid URLpage can override project
subjecta string (max 40 chars)page can override project
venuea venue objectpage can override project
biblioa biblio object with various fieldspage can override project
matha dictionary of math macros (see Math Macros)page can override project
abbreviationsa dictionary of abbreviations in the project (see Abbreviations)page can override project
numberingobject for customizing content numbering (see Section 3)page can override project
partsa dictionary of arbitrary content parts, not part of the main article, for example abstract, data_availability see Document Parts.page only
optionsa dictionary of arbitrary options validated and consumed by templates, for example, during site or PDF buildpage can override project
idid for the project, intended as a unique identifier as the project is used across different contextsproject only
referencesconfiguration for intersphinx references (see Sphinx documentation)project only
requirementsfiles required for reproducing the executional environment, included in the MECA bundle to enable portable executionproject only
resourcesother resources associated with your project, distributed in the MECA bundleproject only
jupyter or thebeconfiguration for Jupyter execution (see Integrate Jupyter-based Computation)project only

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.
project only
the field is only available on projects, and not present on pages and it will be ignored if set there.

Titles

There are several fields to title MyST projects and pages. Primary page and project titles can be specified simply as title. Pages and projects also both have short_title; this should provide a summarized title in less than 40 characters. It is used where space is limited, for example a site navigation panel, running-head titles in an static export, etc. On pages (not projects) you may specify subtitle; this conveys complimentary information to the title and may be displayed below the title.

Thumbnail & Banner

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

fielddescription
namea string OR CSL-JSON author object - the author’s full name; if a string, this will be parsed automatically. Otherwise, the object may contain given, surname, non_dropping_particle, dropping_particle, suffix, and full name literal
ida string - a local identifier that can be used to reference a repeated author
orcida string - a valid ORCID identifier with or without the URL
correspondingboolean (true/false) - flags any corresponding authors, you must include an email if true.
emaila string - email of the author, required if corresponding is true
urla 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

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_contributora boolean (true/false), indicates that the author is an equal contributor
deceaseda boolean (true/false), indicates that the author is an deceased
twittera twitter username
githuba GitHub username
notea string, a freeform field to indicate additional information about the author, for example, acknowledgments or specific correspondence information.
phonea phone number, e.g. (301) 754-5766
faxfor people who still use these machines, beep, boop, beeeep! 📠🎶

Reviewers, Editors, Funding Recipients

Other contributors besides authors may be listed elsewhere in the frontmatter. These include reviewers, editors, and funding award investigators and recipients. For all of these fields, you may use a full author object, or you may use the string id from an existing author object defined elsewhere in your frontmatter.

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
---

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

Table 3:Frontmatter information for affiliations

fielddescription
ida string - a local identifier that can be used to reference a repeated affiliation
namea 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.

departmenta string - the affiliation department (e.g. Chemistry 🧪)

doi, ror, isni, ringgold

Identifiers for the affiliation (DOI, 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
    doi: 10.13039/100018578
emaila string - email of the affiliation, required if corresponding is true
address, city, state, postal_code, and countryaffiliation address information. In place of state you can use province or region.
urla string - website or homepage of the affiliation (website is an alias!)
phonea phone number, e.g. (301) 754-5766
faxA fax number for the affiliation
collaborationa 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

Exports

Exports allow you to generate static versions of your MyST documents, often through intermediary build engines like Latex. For usage information, see Exporting documents.

Table 4:Frontmatter export definitions

fielddescription
ida string - a local identifier that can be used to reference the export
formatone of pdf (built with LaTeX\LaTeX or Typst, depending on the template), tex (raw LaTeX\LaTeX files), pdf+tex (both PDF and raw LaTeX\LaTeX files) typst (raw Typst files and built PDF file), docx, md, jats, or meca
templatea string - name of an existing MyST template or a local path to a template folder. Templates are only available for pdf, tex, typst, and docx formats.
outputa string - export output filename with a valid extension or destination folder
zipa boolean - if true, zip the output - only applies for multi-file exports tex, pdf+tex and typst.
articlesa list of strings - path(s) to articles to include in your export - this is required for exports defined in project frontmatter; for page frontmatter, the default article will be the page itself. Not all exports currently support multiple articles.
toca string - path to jupyterbook _toc.yml file - may be used as an alternative to listing articles
sub_articlesa list of strings - path(s) to sub-articles for jats export

Downloads

Downloads allow you to include downloadable files with a MyST website. They are specified in either:

myst.yml
project:
  downloads:
    - file: ...
    - id: ...

In page frontmatter:

page.md
---
downloads:
  - file: ...
  - id: ...
---

See Downloads, Links and Static Files information about how to use this feature. Below is a list of all possible downloads configuration.

Table 5:Frontmatter download definitions

fielddescription
ida string - reference to an existing export identifier. The referenced export may be defined in a different file. If id is defined, file/url are not allowed.
filea string - a path to a local file. If file is defined, id/url are not allowed.
urla string - either a full URL or a relative URL of a page in your MyST project. If url is defined, id/file are not allowed.
titlea string - title of the downloads entry. This will show up as text on the link in your MyST site. title is recommended for all downloads, but only required for url values; files will default to filename title
filenamea string - name of the file upon download. By default, this will match the original filename. url values do no require a filename; if provided, the url will be treated as a download link rather than page navigation.
statica boolean - this is automatically set to true for local files and false otherwise. You may also explicitly set this to false; this will bypass any attempt to find the file locally and will keep the value for url exactly as it is provided.

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 LicensesCommon 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.

Funding

Funding frontmatter is able to contain multiple funding and open access statements, as well as award info.

It may be as simple as a single funding statement:

funding: This work was supported by University.

Funding may also specify award id, name, sources (affiliation object or reference), investigators (contributor objects or references), and recipients (contributor objects or references).

authors:
  - id: auth0
    name: Jane Doe
funding:
  statement: This work was supported by University.
  id: award-id-000
  name: My Award
  sources:
    - name: University
  investigators:
    - name: John Doe
  recipients:
    - auth0

Multiple funding objects with multiple awards are also possible:

authors:
  - id: auth0
    name: Jane Doe
funding:
  - statement: This work was supported by University.
    awards:
      - id: award-id-000
        name: My First Award
        sources:
          - name: University
        investigators:
          - name: John Doe
        recipients:
          - auth0
      - id: award-id-001
        name: My Second Award
        sources:
          - name: University
        investigators:
          - name: John Doe
        recipients:
          - auth0
  - statement: Open access was supported by Consortium.
    open_access: Users are allowed to reproduce without prior permission
    awards:
      - id: open-award-999
        sources:
          - name: Consortium

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

or

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

OR

biblio:
  volume: '2022'
  issue: Winter
  first_page: Inside cover # can be a number or string
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication