Exporting overview

You can export MyST content into one or more static documents, and optionally bundle them with a MyST website. This section gives an overview of the Exporting process and major configuration options.

List of formats you can export¶

Below are supported export types and links to documentation for further reading:

Table 1:Frontmatter Export Formats

Export type	Learn more
`pdf`	Create a PDF
`tex`	Create a PDF
`typst`	Create a PDF
`JATS`	Working with JATS
`Microsoft Word`	Microsoft Word
`CITATION.cff`	Exporting CITATION.cff
`MyST Markdown`	Export MyST Markdown from another document format

Where to configure options for exports¶

You can configure export options in two different places:

In page frontmatter:

my-markdown-file.md

---
title: My PDF
exports:
  - format: pdf
    template: arxiv_two_column
    output: exports/my-document.pdf
---

In your myst.yml configuration. In this case you will need to specify the article (or articles) that you are targeting. For example, here’s how you’d configure an export from a single-page document.

myst.yml

version: 1
project:
  exports:
    - format: pdf
      template: arxiv_two_column
      article: my-markdown-file.md
      output: exports/my-document.pdf

Configuration options for exports¶

There are a few options you can use to configure exports:

Option	Description
`format`	The type of export you’ll create. For examples, see List of formats you can export.
`template`	The template to use for the export. For more information, see Choose a template.
`output`	The output file to be created.
`id`	A unique identified for the output, in case you want to re-use exports later.
`articles`	One or more source files to use in the export (you can use `article` as well). If using page frontmatter, it will default to the current document.
`toc`	If exporting from a multi-page book, the Table of Contents that defines the book structure.

Choose a template¶

The exporting process uses a MyST Template MyST Template to transform the MyST AST into an output format. MyST Templates are written for a specific export format. A MyST Renderer converts MyST AST into components that a template can use to export a final output.

You can choose the template for a given export format with the template argument. There are several template names you can use out of the box^[1]. For a list of community templates you can use, see the MyST Templates table in the [myst-templates] GitHub organization.

You can also use a URL or a local path that points directly to a template. For example:

- format: typst
  id: typstpdf
  template: https://github.com/rowanc1/typst-book.git
  articles:
    - page1.md
    - page2.md
  output: ./_build/pdf/typst-report.pdf

The `myst-templates` GitHub organization¶

The myst-templates GitHub organization has a collection of MyST templates that are contributed and maintained by the community. These templates are made easily-consumable by MyST users via the MyST API service, see The MyST API server for technical details.

Build one or more exports¶

After defining exports in your frontmatter, you may build them with the myst build command, by default this only builds the site. You can configure the CLI command in a number of ways:

myst build --all: Build all exports in the project
myst build --pdf --docx: Build pdf (LaTeX or Typst) exports and docx in the project
myst build my-paper.md: Build all exports in a specific page
myst build my-paper.md --pdf: Build all pdf exports in a specific page

Re-use export outputs for download buttons¶

You can re-use exported artifacts by setting an id: in your export configuration. Then, reference that ID in your downloads: configuration.

Export Configuration¶

The following table shows the available properties for each export. You must define at least one of format, output, or template for MyST to be able to perform your output. You may also specify a string instead of a full export object; this string will be inferred to be either the export format or the output filename. The table below is from Exports.

Table 5:Frontmatter export definitions

Field	Description
`id`	a string - a local identifier that can be used to reference the export
`format`	one of `pdf` (built with $\LaTeX$ or Typst, depending on the template), `tex` (raw $\LaTeX$ files), `pdf+tex` (both PDF and raw $\LaTeX$ files) `typst` (raw Typst files and built PDF file), `docx`, `md`, `jats`, or `meca`
`template`	a 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.
`output`	a string - export output filename with a valid extension or destination folder
`zip`	a boolean - if `true`, zip the output - only applies for multi-file exports `tex`, `pdf+tex` and `typst`.
`articles`	a 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.
`toc`	a string - path to jupyterbook `_toc.yml` file - may be used as an alternative to listing `articles`
`sub_articles`	a list of strings - path(s) to sub-articles for `jats` export

Split your document across multiple content files¶

When writing longer documents like manuscripts, it’s common to write your document in multiple parts and then stitch them together into a single narrative. You can accomplish this in MyST with the {include} directive.

See The {include} directive for more information.

Export MyST Markdown from another document format¶

MyST can parse some non-MyST document formats as well. This makes it possible to convert something into MyST Markdown.

For example, to convert LaTeX into MyST Markdown, use the following command:

myst build doc.tex --md

Footnotes¶

These are resolved by the MyST API server.
↩