6Create pdf output 🌶

Jupyter Book 2 is centered around creating interactive online documentation. However, there are several instances when a pdf, next to the online book, is desired. We may consider a printed exam, a pdf version for plagiarism check, an journal article (using MySTMD), the ability to take notes for students, and so on…

One of the strengths of Jupyter Book 2 is the easy of creating a high-quality pdf from the same source files as the online book. A template can be used to create a pdf with a consistent look and feel. These templates can be customized to fit the specific needs of the document being created.

Typst or LaTeX¶

You can export your book to a pdf in two ways, with LaTeX or Typst. Both methods have advantages and disadvantages. Typst and LaTeX are both powerful tools for generating high-quality PDFs from markup sources, but they differ in several key aspects:

Choose Typst for simplicity and speed, or LaTeX for advanced customization and compatibility with academic standards.

Moreover, Typst has a more modern feel and look, which seems more compatible with the online book. 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.

Things to consider¶

When starting your JB2 project, consider whether a pdf output is desired. If so, consider that interactive elements, 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 YT 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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
  exports:
    - format: typst
      template: https://github.com/myst-templates/plain_typst_book.git        #plain_typst_book
      output: exports/book.pdf
      id: output-pdf
      cover: logo.svg
      logo: logo.svg
      logo_width: 5
      ToC_depth: 2

  # Jupyter Notebook configuration
  jupyter:
    binder:
      repo: https://github.com/executablebooks/thebe-binder-base

  toc:
    - file: index.md                      # the landing page
    - file: content/1_intro.md
    - file: content/2_jup_nb.ipynb
    - file: content/3_cheat_sheet.md
    - file: content/lessons/your_turn.md          # dropdown menu
      children:
        - file: content/lessons/0_headstart.md
        - file: content/lessons/1_firstedit.md
        - file: content/lessons/2_nextstep.md
          children:
          - file: content/lessons/2a_plugins.md          
        - file: content/lessons/3_interactive.ipynb
        # - file: content/lessons/4_styling.md
        - file: content/lessons/5_GHworkflow.md
        - file: content/lessons/6_pdfoutput.md
    - file: content/advanced_start.md
    - file: content/software.md
    - file: content/gallery.md

site:
  template: book-theme
  options:
    favicon: favicon.svg      # path to your favicon
    style: ./css/custom.css
    logo: logo.svg            # path to your logo, shown top left at site
    folders: false
    hide_authors: true

  actions:
    - title: Feedback
      url: https://github.com/FreekPols/JB2_book_template/issues

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