Create a PDF

MyST can create a PDF for print-ready scientific papers or books. It does so by first rendering your MyST document into $\LaTeX$ or Typst and then using those engines to create a PDF.

Myst uses templates to allow you to control the look and feel of the final PDF output. The MyST Templates organization contains templates for rendering MyST documents into the structure of over 400 journals.

How to export to PDF¶

To create a new pdf export type for your MyST document, add an exports list to either your document frontmatter or your myst.yml configuration file.

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

To build the exports, use the myst build command, which will work with your project structure if it exists and create a document in the output path that you specify.

myst build my-document.md --pdf

Based on the output field in the export list in the frontmatter, the PDF and a log file will be written to exports/my-document.pdf and any associated log files. If the output file is a folder, the document name will be used with a .pdf or .tex extension, as appropriate. Any necessary auxiliary files (e.g. for example *.png or *.bib) will be added to the base folder (exports/ above).

Rendering PDFs with $\LaTeX$¶

The rendering process for scientific PDFs uses $\LaTeX$ and makes use of the jtex templating library, to convert to $\LaTeX$ the myst-to-tex packages is used. The libraries work together for sharing information about frontmatter (e.g. title, keywords, authors, and affiliations).

To include the $\LaTeX$ source code as well as the included images, change the format to:

tex

create a folder containing the $\LaTeX$ source code, referenced images, citation files, and any class files required by the template.

tex+pdf

create a folder containing all the same outputs as tex as well as run the build process for the pdf.

pdf

Run the above processes in a temporary folder, and only copy in the PDF export and any log files if there are problems.

Install $\LaTeX$¶

See the official documentation for installation instructions for $\LaTeX$ at:

• https://www.latex-project.org/get/

Ensure that you download a full distribution with appropriate libraries installed.

Rendering PDFs with Typst¶

Typst is a markup-based typesetting language. It is significantly faster and simpler than using $\LaTeX$ with results of equal or better quality.

How to install Typst¶

Follow the Typst installation instructions for several options to install Typst. We strongly recommend using the latest releases of Typst. If you get a confusing Typst error, a good first step is to upgrade your version of Typst.

How to render PDFs with Typst¶

To render Typst PDFs locally, you must first install Typst.

Then add Typst to your export targets. Add format: typst and select a Typst template. Below is an example that also defines the output PDF to generate:

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

Finally, build the PDF output with Typst using the following command:

myst build article.md --typst

You can use document frontmatter to control various aspects of your Typst outputs. The Typst templates use the MyST templating library and support the same configuration as $\LaTeX$.

Choosing a Template¶

There are currently 422 journals supported^[1] and it is straight forward to add new personal templates, or contribute them back to the community.

Templates exist for both $\LaTeX$ and Typst builds. To list all of the public templates, use the myst templates command:

myst templates list --pdf --tag two-column

> arXiv (Two Column)       arxiv_two_column
> Description: A two column arXiv compatible template
> Tags: paper, two-column, preprint, arxiv, bioarxiv, eartharxiv
>
> ...

Once you have found a template, you can list detailed information about the parts and options that the template exposes using:

myst templates list arxiv_two_column --tex

> ID: public/arxiv_two_column
> Version: 1.0.0
> Author: Brenhin Keller
> Description: A two column arXiv compatible template
> Tags: paper, two-column, preprint, arxiv, bioarxiv, eartharxiv
>
> Parts
> abstract (required) - Keep it short — abstracts longer than 1920 characters will not be accepted ...
>
> Options
> line_numbers (boolean) - Turn line numbers on in the PDF

There are two ways to provide information to a template, through parts and options.

Template parts¶

The parts of a template are things like abstract, acknowledgments or data_availability, see Document Parts for more information. These parts are usually written pieces of a document, but are placed specifically in a template. For example, an abstract usually has a place in templates, with a box or other typographic choices applied. These parts can be marked as required, and will raise error in the PDF export process, however, myst will always try to complete the build.

A part of a template can be defined using the page frontmatter or metadata on a block. An example of using the frontmatter is:

---
abstract: |
  MyST (Markedly Structured Text) is designed to create publication-quality documents
  written entirely in Markdown. The markup and publishing build system is fantastic,
  MyST seamlessly exports to any PDF template, while collecting metadata to make your
  writing process as easy as possible.
---

Template options¶

Template authors should choose to use standard frontmatter properties where possible, however, all templates can also expose custom options through their Template.yml. Include options for the build in the exports list. For example, to turn on line_numbers in the template, add the option to the dictionary.

1
2
3
4
5
6
7
8
---
title: My PDF
exports:
  - format: pdf
    template: arxiv_two_column
    output: exports/my-document.pdf
    line_numbers: true
---

Any unrecognized, or malformed entries will be logged as errors as well as required options that are not provided.

Creating a Template¶

The export list can also point to local templates, for $\LaTeX$ these are built using jtex, and you can learn more about how to create a template for: any $\LaTeX$ document and Beamer presentations.

To make use of the template locally, validate it using jtex check and then point to the template folder in your export:

1
2
3
4
5
6
7
---
title: My PDF
exports:
  - format: pdf
    template: ../templates/my-template
    output: exports/my-document.pdf
---

Please consider contributing your template to the growing list of templates so that other people can benefit and improve your work!

Excluding Content from Specific Exports¶

If you have a block or notebook cell that you do not want to render to your $\LaTeX$ output, add the no-tex tag to the cell. Similarly, to exclude a cell from Typst, use no-typst. To exclude a cell from both formats, use no-pdf.

Including Content with Specific Exports¶

If you need to inject some $\LaTeX$- or Typst-specific content into their respective exports, you may use the {raw:latex} or {raw:typst} role and directive. For example, to insert a new page in Typst with two columns:

```{raw:typst}
#set page(columns: 2, margin: (x: 1.5cm, y: 2cm),);
```

The content in these directives and roles will be included exactly as written in their respective exports, and will be ignored in all other contexts.

Multi-Article Exports¶

Sometimes you may want to combine multiple MyST documents into a single export, for example a thesis or a book. MyST makes this possible with multi-article exports for PDFs built with either $\LaTeX$ or Typst.

For perform a multi-article export, add multiple articles to the export frontmatter:

---
title: My PDF
exports:
  - format: pdf
    template: plain_latex_book
    output: exports/my-thesis.pdf
    articles:
      - introduction.md
      - project-one.md
      - project-two.md
      - conclusions.md
---

As an alternative to listing articles in MyST frontmatter, you may specify a table of contents using the Jupyter Book V1 format:

---
title: My PDF
exports:
  - format: pdf
    template: plain_latex_book
    output: exports/my-thesis.pdf
    toc: thesis_toc.yml
---

By default if no articles are given, exports defined in page frontmatter will produce a single-article export from of that page, and exports defined in the myst.yml project configuration will produce a multi-article export based on the project structure.

Custom Frontmatter for Exports¶

Export frontmatter may differ from page or project frontmatter. For example, you may with to give your export its own title, which does not match the project title. To do so, add the alternative frontmatter to your export:

---
title: My Interactive Research!
exports:
  - format: pdf
    title: My Static Research as a PDF
    output: exports/my-document.pdf
---

You may redefine any frontmatter fields. These redefined fields will replace the values found in page frontmatter and myst.yml project configuration.

Further, for Multi-Article Exports, you may redefine frontmatter for every specific page. To do so, you must use a list of article objects (as opposed to a _toc.yml file or a list of article names):

---
title: My PDF
exports:
  - format: pdf
    title: My Thesis
    date: 10 May 2023
    template: plain_latex_book
    output: exports/my-thesis.pdf
    articles:
      - file: introduction.md
        title: Introduction to This Thesis
      - file: project-one.md
      - file: project-two.md
      - file: conclusions.md
        title: Summary of this Thesis
---