7.1MyST Document Creation 🌶

This page introduces a few key concepts that will help understand how Jupyter Book 2 creates documents from source files written using MyST Markdown. We are particularly interested in understanding how themes and templates are used to create a website and PDF, respectively.

Only a very brief overview is provided here; for additional technical explanation, refer to the stack overview section of the MyST Guide, as well as the SciPy Paper.

Key MyST Components¶

As you already know, Jupyter Book 2 is able to convert MyST Markdown written *.md and *.ipynb source files into websites: online books. However, there are many other formats that MyST can convert to, including PDF, LaTeX, Word, JATS XML, and more. The process is illustrated in the following figure:

In the demonstration below below, each tab illustrates the various output formats for a given MyST Markdown input:

MyST Build Process¶

The “build” process, the process of converting MyST Markdown into a given output format, is more complex than the figure above suggests. In fact, it has 5 key steps: writing, parsing, resolving, rendering and exporting. Of this process, illustrated below, only the final step is of interest to us here, as it is where the rendered components of a document are combined with a theme (for websites) or a template (for PDF’s) to create the final output document.

Themes and Templates¶

For our purposes, a theme or template defines the final appearance of our document. Though a concise explanation is provided here, for this workshop it is sufficient to know that there are a number of different themes and templates available in the MyST ecosystem, and that it is possible to customize them to a high degree. An overview is provided at the myst-templates GitHub organization.

Note in particular that there are currently only two themes in this organization: book-theme and article-theme. These are the two themese bundled with MyST and correspond to the two types of websites that can be created. The code snippet below is from the myst.yml file of this book, which indicates the book-theme is used:

73
74
75
76
77
78
79
80
site:
  template: book-theme
  options:
    favicon: ./content/figures/favicon.svg      # path to your favicon
    style: ./css/custom.css
    logo: ./content/figures/logo.svg            # path to your logo, shown top left at site
    folders: false
    hide_authors: true

There is a relatively large number of templates listed in the myst-templates GitHub organization, the vast majority of which create LaTeX documents (i.e., *.tex files). In fact, many of these templates are for articles formatted for publishing with specific journals and are used in combination with websites created using the article-theme to generate a PDF. The code snippet below is from the myst.yml file of this book, which indicates the book-theme is used:

28
29
30
31
32
  exports:
    - format: typst
      template: lapreprint-typst
      output: exports/book.pdf
      id: output-pdf

Summary¶

That’s enough detail about the MyST ecosystem for now. The main takeaways from this page are to recognize:

• themese and templates are used to customize the creation of final documents for a given source

• this book is initially set up with the book-theme for website generation and the lapreprint-typst template for PDF generation

Up to this point in the workshop you have been modifying the source code and using the book-theme to view changes on the rendered website; however, you have not yet generated a PDF. After a quick introduction to LaTeX and Typst on the following page, we will do just that in the next round of exercises!