Anatomy of a Jupyter Book

Jupyter-Book comes with a demo book so that you can see how the content filesare used in the book. We'll begin with a quick tour of these files, as they arethe pieces that you'll modify for your own book.

To create a demo Jupyter Book to use as a template, run the following command:

  1. jupyter-book create mybookname --demo

A new book will be created at the path that you've given (in this case, mybookname/).

Let's take a quick look at some important files in the demo book you created:

  1. mybookname/
  2. ├── assets
  3. │   └── custom
  4. │       ├── custom.css
  5. │       └── custom.js
  6. ├── _config.yml
  7. ├── content
  8. │   ├── features
  9. │   │  ├── features.md
  10. │   │  └── notebooks.ipynb
  11. │   └── LICENSE.md
  12. ├── _data
  13. │   └── toc.yml
  14. └── requirements.txt

Here's a quick rundown of the files you can modify for yourself, and thatultimately make up your book.

Book configuration

All of the configuration for your book is in the following file:

  1. mybookname/
  2. ├── _config.yml

You can define metadata for your book (such as its title), adda book logo, turn on different "interactive" buttons (such as aBinder button for pages built from a Jupyter Notebook), and more.

Book content

Your book's content can be found in the content/ folder. Some contentfiles for the demo book are shown below:

  1. mybookname/
  2. ├── content
  3.     └── features
  4.        ├── features.md
  5.        └── notebooks.ipynb

Note that the content files are either Jupyter Notebooks or Markdownfiles. These are the files that define "pages" in your book.

You can store these files in whatever collection of folders you'd like, note thatthe structure of your book when it is built will depend solely on the order ofitems in your _data/toc.yml file (see below section)

Table of Contents

Jupyter Book uses your Table of Contents to define the structure of your book.For example, your chapters, sub-chapters, etc.

The Table of Contents lives at this location:

  1. mybookname/
  2. ├── _data
  3.     └── toc.yml

This is a YAML file with a collection of pages, each one linking to afile in your content/ folder. Here's an example of a few pages defined in toc.yml.

  1. - title: Features and customization
  2.   url: /features/features
  3.   not_numbered: true
  4.   expand_sections: true
  5.   sections:
  6.   - title: Markdown files
  7.     url: /features/markdown
  8.     not_numbered: true
  9.   - title: Jupyter notebooks
  10.     url: /features/notebooks
  11.     not_numbered: true

The top-most level of your TOC file are book chapters. Above, this is the"Features and customization" page. Each chapter can haveseveral sections (defined in sections:) and each section can have several sub-sections(which would be define with a deeper level of sections:). In addition, you canuse a few extra YAML values to control the behavior of Jupyter-Book (for example,not_numbered: true will prevent Jupyter Book from numbering the pages in that chapter).

Each item in the YAML file points to a single content file. The linksshould be relative to the /content/ folder and with no extension.

For example, in the example above there is a file inmybookname/content/features/notebooks.ipynb. The TOC entry that points tothis file is here:

  1. - title: Jupyter notebooks
  2.         url: /features/notebooks

A license for your content

When you share content online, it's a good idea to add a license so that others knowwhat rights you retain to the work. This can make your book more sharable and (re)usable.

The license for a Jupyter Book lives in this location:

  1. mybookname/
  2. ├── content
  3.     └── LICENSE.md

When you create a new book, if you don't specify a license, then jupyter-book will by defaultadd a Creative Commons Attribution-ShareAlike 4.0 International(CC BY-SA 4.0) license to your book. CC BY-SA requires attribution ofyour work, and also requires that any derivations someone creates are releasedunder a license at least as permissive as CC BY-SA.

If you'd like to choose a different license, you can add whatever text you like to the filein /content/LICENSE.md. We commend checking out the Creative Commons licenses pagefor several options for licenses that may suit your needs.

Book code requirements files

Since your Jupyter Book likely has computational material specified in JupyterNotebooks, you should specify the packages needed to run your Jupyter Book.In this case, we use a requirements.txt file:

  1. mybookname/
  2. └── requirements.txt

The demo book uses requirements.txt because it has Python code, but you caninclude any other files that you'd like to.

Book bibliography for citations

If you'd like to build a bibliography for your book, you can do so by includingthe following file:

  1. mybookname/
  2. ├── _bibliography
  3.     └── references.bib

This BiBTex file can be used along with the jekyll-scholar extension. For more informationon how to use citations in Jupyter Book, see Citations with Jupyter Book

Custom Javascript and CSS

These are the files in this location:

  1. ├── assets
  2.     └── custom
  3.         ├── custom.css
  4.         └── custom.js

Jupyter Book lets you supply your own CSS and Javascript that will bebuilt into your book. Feel free to edit these files with whatever you like.

Next section

Now that you're familiar with the Jupyter Book structure, head to the next sectionto learn how to create your own!

This page was created by The Jupyter Book Community