7Create PDF output 🌶

WIP

• overview of PDF output stuff

• install Typst (local and GHA with tab-set)

• set up and build book as PDF with lapreprint Typst template

• look at output

• set up and build book with plain_typst_template

• look at output

• explain/illustrate setup: not committing PDF to repo; build in - GHA as a form of software testing

• set up extra stuff: add MyST action button, add download on page, upload as artifact (GHA only)

Jupyter Book 2 is centered around creating interactive online documents. However, there are several instances when a PDF, next to the online book, is desired, for example:

• for use in note taking applications (e.g., students annotating a textbook chapter, or reviewing the draft of a website),

• if a printed copy of the book is required,

• to more easily carry out a plagiarism check.

One of the strengths of Jupyter Book 2 is the ease with which high-quality PDF’s can be created from the same source files as an online book. To accomplish this, a template is used to create a PDF with a consistent look and feel between the two document formats. In addition, such templates can be customized to fit the specific needs of the documents being created.

This lesson provides an overview the PDF output capabalities of the Jupyter Book 2 and MyST ecosystem, accompanied by exercises to get you started creating your own PDF output (with Typst) using two different templates.

MyST Document Formats¶

Jupyter Book 2 (JB2) supports both Markdown files and Jupyter Notebooks as content sources.

Markdown¶

Markdown is a simple markup language: plain text that is formatted with small pieces of ‘code’. This allows you to create rich, interactive books that combine text, code, and visualizations. This text can then be quickly exported to various other formats such as PDF, Word, HTML, etc.

See below for an example of the Markdown language and how it is rendered in JB2.

# This is a heading
This is a paragraph with **bold** and *italic* text.
- This is a list item
- Another list item
```{warning} raw HTML
You can also include raw HTML in your Markdown files, but this will not be rendered in the PDF output.
```

In the next chapter we cover most of the basic Markdown syntax you will need to create your own content.

PDF Generation: Typst and LaTeX¶

Jupyter Book 2 currently supports two primary ways to export your book as a PDF: LaTeX or Typst. Both are powerful tools for generating high-quality PDFs, but they differ in several key aspects (additional advantages and disadvantages described here):

In short: choose Typst for simplicity and speed, or LaTeX for advanced customization and compatibility with academic standards.

Below we provide the screen shots of the PDF output using Typst (left) using the plain_typst_template and LaTeX (right) using the plain_latex_template.

You can specify the output template, download the template and tweak to match your preferences. We won’t go into detail here, but you can find more information in the MyST Markdown documentations.

Considerations¶

When starting your own project, consider whether a PDF output is desired. If so, consider the interactive elements that may be included and wether or not, some functionality and not all multimedia are supported in a PDF. For instance, a *.gif file cannot be included in a PDF. JB2 is thoughtful in this by choosing the best possible alternative if multiple files with the same name but different extensions are present: gif is chosen over png, png over jpg. Rather than specifying the extension, you can just use the file name and an asterisk, e.g. ![figure](figures/mystvstex.*).

For YouTube clips and online interactive materials embedded through iframes, you can make use of plugins. See for instance the iframe-to-thumbnail plugin. This plugin replaces the iframe with a thumbnail image that links to the original content as well as a QR code and a link in the caption.

Export through GitHub actions or locally¶

We specified in the myst.yml file that we want to export to PDF using Typst. You can also choose LaTeX. See the myst.yml file, or Program 1 for the syntax.

28
29
30
31
32
33
34
35
36
  exports:
    - format: typst
      template: https://github.com/myst-templates/plain_typst_book.git
      output: exports/book.pdf
      id: output-pdf
      cover: content/figures/logo.svg
      logo: content/figures/logo.svg
      logo_width: 5
      ToC_depth: 2

Local build¶

When both myst and typst are installed, you can build the PDF locally using the command line:

myst build --typst

The book will be built in the exports directory as specified in the myst.yml file and the build files will be in the _build directory.

GH actions¶

Building and including your PDF is possible through a GitHub action that automatically builds the PDF when you push changes to GitHub. This has both is pros and cons. For instance, the build of your PDF is done prior to the build of your book. If there is an error in your book, the PDF AND your book will not be built. On the other hand, you do not need to install anything locally and the PDF is always up to date when you push changes.

There is a third option where you have a separate PDF build github action that only builds the PDF when you push to a specific branch, e.g. main or release or when you initialize the workflow yourselves.

    # Install Typst for PDF generation
    - name: Install Typst
      run: |
        typst --version

    # Build the PDF using Typst
    - name: Build PDF
      run: |
        myst build --typst

Excluding and including sections for PDF^[1]¶

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:

Or,

+++ { "page-break": true } for a page break.

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.

You may use block metadata to insert page breaks into your PDF or docx export with +++ { “page-break”: true }. This will have no impact on your MyST site build nor other static exports that disregard “pages” (e.g. JATS).

This won’t be in the PDF.

Configure PDF output¶

Typst¶

When exporting to Typst format, you can provide Typst-specific math content using the typst option. This allows you to use native Typst syntax instead of relying on tex-to-typst conversion, which may give incorrect results.

Example with typst argument in a math block: https://mystmd.org/guide/math#typst-math