With a general understanding of document creation using MyST and our choice to use Typst for PDF generation, you are ready to create a PDF from your book repository using Jupyter Book.
In this lesson, we will:
Install Typst (or use it within a GitHub Action workflow if working online-only)
Generate a PDF using the
lapreprint-typsttemplateSet up and use the
plain_typst_booktemplateModify the GitHub Action workflow to generate a PDF
Explore how the PDF can be customized and shared via the book website
Install Typst¶
To produce a PDF output locally, you need to have Typst installed on your system.
Generate a PDF¶
Once Typst is installed and available in your terminal it can be used with Jupyter Book to generate a PDF file.
PDF output with GH Actions¶
Building and including your PDF is possible through a GitHub Action workflow 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, and if there is an error in the workflow your website may not be updated, or the PDF may not be included as a download. On the other hand, you do not need to install anything locally and the PDF is always up to date when you push changes. The most important reason for including the PDF build in your GHA workflow is that your PDF will be generated and included automatically as a downloadable file along with your website. You will learn to do this in several ways by the end of this lesson.
The workflow steps are:
jobs:
deploy:
...
steps:
...
- uses: typst-community/setup-typst@v4
...
- name: Build PDF
run: |
jupyter book build --pdf
- name: Upload Output PDF as Artifact
uses: actions/upload-artifact@v4
with:
name: Output PDF
path: exports/book.pdf
compression-level: 0Change the PDF template¶
Take a look at the PDF generated in the previous exercises using the lapreprint-typst template. You probably notice that it is does a good job at converting the website into a PDF document. However, you may have also noticed some text or formatting that isn’t perfect, or perhaps you thought that you might want a cover page or table of contents for the PDF.
It turns out the lapreprint-typst template is not ideal for rendering content designed as a website made with the book-theme. Luckily, another Typst template is available: the Plain Typst Book plain_typst_book (not yet listed on the MyST Templates GH Organization). An example YAML snippet that implements this in the myst.yml file is illustrated here:
exports:
- format: typst
template: https://github.com/myst-templates/plain_typst_book.git
output: exports/book.pdf
id: output-pdfMore fun with PDF’s¶
Now that you have successfully created a PDF and changed the template, a few small exercises are provided here to illustrate how the template can be customized, as well as how the PDF can be included as a download via the website.
You can complete the exercises in this section in any order.
Customize the PDF output¶
The plain_typst_book template includes options that can be set by the user to customize how the PDF is generated. For example, cover, logo logo_width and ToC_depth are added to the myst.yml file.
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: 2Add Download PDF button to website¶
You may have noticed a large “Feedback” button at the top right of your website. This is one example of what Jupyter Book 2 (and MyST) refer to as “actions” (not the same as GitHub Actions!). It would be very useful to include a similar button for downloading the PDF of your book. This can be done by adding the following values to the actions sub-section of the site section in myst.yml:
site:
...
actions:
...
- title: PDF
url: ./exports/book.pdf