--- title: Document Parts description: Parts allow you to specify special parts of your document, like abstract, key points, and acknowledgements. --- Document *parts* allow you to add content and metadata for specific components of your page or project, including `example`, `abstract`, `dedication`, and `acknowledgment`. [Templates](./documents-exports.md) 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](#parts:project) 2. [In page frontmatter](#parts:frontmatter) 3. [With a content block](#parts:blocks) 4. [With specific section headings](#parts:implicit) 5. [With Jupyter Notebook cell tags](#parts:cell-tags) (parts:project)= ### 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](#parts:frontmatter). ```yaml 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. ```{caution} Project-level `parts` are a new feature and may not yet be respected by your chosen MyST template or export format. If the project `part` is not behaving as you expect, try moving it to page frontmatter for now. ``` (parts:frontmatter)= ### Parts in Frontmatter On any page, you can add a part to your document directly in the frontmatter, for example, the `abstract`: ```yaml --- 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: ```yaml --- title: My document abstract: ../abstract.md --- ``` (parts:blocks)= ### Parts with content blocks You can use [content blocks](./blocks.md) 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. ```{code} markdown :filename: mypage.md # Page title +++ { "part": "abstract" } This is my abstract block. +++ Page content ``` (parts:implicit)= ### 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:cell-tags)= ### 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. ```yaml --- 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. (parts:site)= ## Add website parts [Website themes](./website-templates.md) 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](#default-web-themes) support a [`footer` part](#navigation:footer) and [`banner` part](#navigation:banner). Specify the content of a site `part` in the `site.parts` key of the `myst.yml` configuration file: ```{code} yaml :filename: myst.yml version: 1 site: template: ... parts: footer: | (c) MyST Markdown banner: My banner [content](https://mystmd.org)! ... ``` Alternatively, you may specify a path to a file that contains the part content: ```{code} yaml :filename: myst.yml version: 1 site: template: ... parts: footer: parts/myfooter.md banner: _site/banner.md ... ``` You can also specify a URL to a remote markdown file: ```{code} yaml :filename: myst.yml version: 1 site: template: ... parts: footer: https://example.com/shared-footer.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](#composing-myst-yml). 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: ```{code} yaml :filename: parts.yml site: parts: footer: | My nifty footer! ... ``` And in another: ```{code} yaml :filename: myst.yml 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. :::{seealso} Referring to parts directly with a URL is coming See the [issue tracking this enhancement](https://github.com/jupyter-book/mystmd/issues/2127). ::: (parts-ast)= ## How parts appear in the AST Each way of defining a part lands in a different place in the JSON that `myst build` emits. This section describes how these are represented in the AST. See [](xref:spec) for more details about the MyST AST. ### Page-level parts in the page AST There are three ways to mark a region as a named part in a document. Each one ends up in a different place in the served JSON, even though they are often treated the same in the rendered output (see [](#ast-parse-helper) for guidance in parsing them). We show each method below, and where it lands in the AST: ````{list-table} - - Method - Example - Location in AST - - **Page frontmatter** (in the `parts:` key) - ```markdown --- parts: acknowledgments: "..." abstract: "My abstract" --- My content... ``` - Stored in the page frontmatter key: `frontmatter.parts..mdast`. - - **Block metadata** (within content of a page) - ```markdown +++ {"part": "abstract"} My abstract content. +++ My content +++ {"part": "acknowledgements"} Thanks to ... ``` - Stored in a `block` node inside `mdast` with `data.part` set. `.mdast.children..data.part = "acknowledgements"` - - **Heading auto-match** (heading text equals a known part name) - ```markdown ## Abstract My abstract ... ## Header one A normal (non-part) header ## Acknowledgments Thanks to ... ``` - Remains a regular `heading` + paragraphs sequence. Only becomes a part block when [`extractPart()`](#ast-parse-helper) is called. ```` ### Site-level parts in the project AST Site-level `parts:` (under `site:` in `myst.yml`) is a different `mystmd`-specific system for content shared across pages (like a project footer or header). These are project-level and not part of any page's AST. The [theme developer guide](./theme-developer.md) covers the rest of what mystmd serves alongside per-page JSON. (ast-parse-helper)= ### Programmatically extract a part from an AST Instead of manually parsing the page AST for these parts, use the [`extractPart()`](https://github.com/jupyter-book/mystmd/blob/0d626b198093fa740125d02267a111d84547fd36/packages/myst-common/src/extractParts.ts) helper to retrieve a named part regardless of how it was defined. For example, exporters like [`myst-to-jats`](https://github.com/jupyter-book/mystmd/blob/0d626b198093fa740125d02267a111d84547fd36/packages/myst-to-jats/src/index.ts#L720-L729) call `extractPart()` to pull these regions into their output.