Make your own templates

Jupyter Book allows you to convert your project from markdown to a full functional website, or a high-quality pdf using either LaTeX or Typst. For the latter, a template is needed including a .yml file which ‘transfers’ the variables set in your JB project.

PLACEHOLDER CONCEPTUAL FIGURE OF PROCESS JB project -> export.yml file -> myst engine -> typst / tex project -> pdf

The main files¶

The export.yml can be a bare bone version where only the format and template location are specified. However, it is a courtesy to the user to also include the (default)settings which can be changed by the user (e.g. margins, number of columns), moreover, it will help to speed up the building of an output with your own preferences.

  exports:
    - id: output-pdf                # ID of the export, to be used for download
      format: pdf                   # Define type of export (--pdf flag uses latex)
      template: ./template          # Location of the template
      output: ./exports/thesis.pdf  # Specify output path (name) here

The template.yml file resembles to a large extend the export.yml file: all variables that are specified there. Information on the template (e.g. title, licenses etc) are specified in this file.

options:
  - id: show_cover_full
    type: boolean
  - id: show_title_page
    type: boolean
  - id: show_contributor_affiliations
    type: boolean

The template.typ file takes care of the conversion from your JupyterBook project to variables that are needed to build the template. For instance:

[# if project.subtitle #]
  subtitle: "[-project.subtitle-]",
[# elif doc.subtitle #]
  subtitle: "[-doc.subtitle-]",
[# else #]
  subtitle: none,
[# endif #]

reads the subtitle from the project settings. If no subtitle is found, it is set to none (the else is redundant as the subtitle can be set to none by default in the main.typ).

The main.typ is the actual template: it specifies the rules for your design. For instance:

  set page(
    paper: paper_size,
    margin: (
      top: margin_top_cm,
      bottom: margin_bottom_cm,
      left: margin_left_cm,
      right: margin_right_cm,
    ),
    numbering: front_numbering,
  )

specifies the paper size and all margins.

Variables¶

It is possible to create a new variable which defines a certain setting (e.g. margin) in your project. To make it easy editable, it should be included in the export.yml file.

When making a new variable which can be set in the export.yml file, three files need to be changed:

• export.yml

• template.yml

• template.typ