Jupyter Book Fundamentals - Jupyter Book 2 Workshop Template

Anatomy of a Jupyter Book¶

A Jupyter Book is a collection of files and folders that together make up the content and structure of your book. The structure of the book is specified in the myst.yml file, which is located in the root directory of your book. This file contains information about the title, author, and other metadata of the book, as well as documents and its structure to build the book itself.

myst.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  id: 7204695b-7485-4989-863c-16cf6e4db155
  title: Jupyter Book 2 Workshop Template
  description: This description goes in the preface of the pdf output. 
  # keywords: []
  authors:
    - name: Freek Pols
    - name: Luuk Fröling
    - name: Robert Lanzafame
    - name: Kirstie Whitaker
    - name: Jim Madge
  license:
    content: CC-BY-4.0

Program 1:The head of this book’s myst.yml

Your first change¶

As explained in the previous chapter, your files are on GitHub and the template ensures the book is built. You can make changes directly to the files online in GitHub, and create or upload new files.

Some files are already present in the template book. The folder structure is shown below

myst.yml

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
    - 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_setup.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

Program 2:The Table of Contents (ToC) for this book.

We will now make a small change to one of the files and then look at the result of that change.

Exercise 1 (Your first change)

GH IDE

Local

Navigate to the file Content/Lessons/1_firstedit.md. Then click on the pencil on the right (edit this file).

Change the text after the #. This is the title of the file.

Choose your file, click on edit and make changes. Ready? Commit your changes to your repository and see the output.

Optionally, make other changes in the text editor and when you’re done, commit your changes to the “remote repository” by clicking the green Commit changes button.

The book will now be rebuilt. Once that’s done, you can view the result on the GitHub page.

Commit summary

If you are working with multiple people in GitHub, or on a large project yourself, it is wise to give the commit a recognizable title (commit message) and optionally add a summary (extended description) of exactly what was changed, see also this more elaborative description. This way, you can detect and undo any errors early. You can also explain why certain changes were made.

Adding a page¶

The Table of Contents defines the structure of your Jupyter Book. Items in your myst.yml’s toc will be added to the book’s table of contents. Markdown, TeX and Jupyter Notebook files will be rendered as pages (in the case of a website) or chapters (in the case of a document).

To add a new page from a Markdown file,

Create a new markdown file
Add some content to the file
Include in the ToC

Exercise 2 (Add a new page)

Using the GitHub IDE

Locally

Create a new markdown file

navigate to the folder where you want to include the sourcefile
click add file / + Create new file
create a clear name for the file and use the .md extension (e.g. newfile.md)

Create a H1 heading

use for the header # and include the title
commit your changes

Include the file in the ToC.

navigate to the myst.yml file in the root
at the right location in your book, include the path to your file (e.g. - file: content/lessons/newfile.md)
commit your changes and check the output on GitHub pages.

Headings¶

Similarly to how your table of contents gives structure to your Jupyter Book, within a page you can build structure using headings. You can use levels of headings from 1 to 6 to structure a page.

Essential typography¶

You should now be confident making changes locally or through the GH IDE. Try making the changes indicated in the following exercise. Refer to the cheat sheet if you need a reminder on the syntax.