Document Parts

Document parts allow you to add content and metadata for specific components of your page or project, including example, abstract, dedication, and acknowledgment. Templates may use the parts and their metadata, and render such content in various locations.

Add document parts¶

Document parts can be used in any export media (html, pdf, etc). There are several ways you can define document parts, each described below:

1. In project-level configuration
2. In page frontmatter
3. With a content block
4. With specific section headings
5. With Jupyter Notebook cell tags

Parts in myst.yml Project configuration¶

You may also specify parts in the project configuration of your myst.yml file. These are defined exactly the same as parts defined in page frontmatter.

version: 1
project:
  abstract:  |
    This is a multi-line
    abstract, with _markdown_!
  parts:
    special_part: |
      This is another _special_ part!

Project-level parts are useful, for example, if you have an abstract, acknowledgments, or other part that applies to your entire project and doesn’t make sense attached to an individual page.

Parts in Frontmatter¶

On any page, you can add a part to your document directly in the frontmatter, for example, the abstract:

---
title: My document
abstract: |
  This is a multi-line
  abstract, with _markdown_!
---

You may also write your part in a separate file, and point to that file from the frontmatter, for example:

---
title: My document
abstract: ../abstract.md
---

Parts with content blocks¶

You can use content blocks in a page to define a part. This will be parsed differently from the other content on the page for re-use in templates and websites.

The following example shows how to define an abstract part in a content block on a page.

# Page title

+++ { "part": "abstract" }

This is my abstract block.

+++

Page content

Parts with specific header titles¶

If you are rendering your project in other places, it can be helpful to leave these sections directly in the document. Complete this using a header as usual:

# Abstract

This is my abstract!

Note that frontmatter parts and explicitly tagged cells/blocks will take precedence over this method. Themes may choose to only pick up a subset of implicit parts, for example, only an Abstract and not Summary as summary section can be used in other contexts.

Parts with Jupyter cell tags¶

When using a Jupyter Notebook, you can add a tag to the cell with the part name. If multiple cells share that tag, they will be extracted and merged.

Known Document Parts¶

The known parts that are recognized as top-level document parts keys are:

abstract

A concise overview of the entire document, highlighting the main objectives, methods, results, and conclusions. It’s meant to give readers a quick snapshot of what to expect without having to read the entire document.

summary

Similar to an abstract, but can either be slightly longer and more detailed or used as a plain-language summary, depending on the context. It summarizes the document’s content, including the background, purpose, methodology, results, and conclusions.

Alias: plain_language_summary, lay_summary

keypoints

A brief list that highlights the main findings, conclusions, or contributions of the document. Key points are often used to quickly convey the core message or most important aspects to the reader.

dedication

A short section where the author dedicates the document to someone, often as a gesture of honor or respect.

epigraph

A quote or poem that the author includes at the beginning of the document to set a tone or theme, or to hint at the document’s underlying message. It is often relevant to the content but not directly related to it.

Alias: quote

data_availability

A statement or section that details how readers can access the data sets and resources used in the document. This can include links to repositories, conditions for access, and any restrictions on the data. It’s crucial for transparency and reproducibility in research documents.

Alias: availability

acknowledgments

A section where the author thanks individuals, organizations, or agencies that contributed to the completion of the document. This can include support in the form of funding, expertise, feedback, or moral support.

Alias: ack, acknowledgements

Custom Frontmatter Parts¶

If you have a custom part name for a template, you can nest it under parts:, which takes arbitrary keys.

---
title: My document
parts:
  special_part: |
    This is another _special_ part!
---

The advantage of this method is that the content is not rendered in your document.

Add website parts¶

Website themes have additional parts because they render user interface elements that are not part of a standard “document” structure. These are theme-dependent: for example, the default myst themes support a footer part.

Specify the content of a site part in the site.parts key of the myst.yml configuration file:

version: 1
site:
  template: ...
  parts:
    footer: |
      (c) MyST Markdown
  ...

Alternatively, you may specify a path to a file that contains the part content:

version: 1
site:
  template: ...
  parts:
    footer: parts/myfooter.md
  ...

Content in parts will generally be parsed similarly to other MyST content (though some functionality like code execution will not work).

Share the same part across multiple sites¶

If you wish to share the same part across multiple sites, use the extends: key to compose multiple configuration files. This lets you define the part in one location, and re-use it in several others. It is useful if you want to standardize website components like a footer across many websites.

For example, in one file:

site:
  parts:
    footer: |
      My nifty footer!
  ...

And in another:

version: 1
extends: parts.yml
site:
  template: ...

If you’re extending configuration from a remote source, make sure that you use absolute URLs if you must refer to an image or other asset in your part content. Relative paths that are defined inside the part content will generally break.