How to use "Jupyter Book" to create publication quality books and documents from .ipynb

What is Jupyter Book?

As the title suggests, "Jupyter Book" allows you to create beautiful publication-quality books and documents (HTML, PDF, etc.) from Jupyter Notebook files (.ipynb) and Markdown files (.md). ** The official reference for the URL is also created using the "Jupyter Book" **.

It's similar in name to Jupyter Notebook, but ** another **, one of the projects in "Project Jupyter" and "The Executable Book Project". As far as I could find, there was no Japanese reference, so I would like to give a brief introduction to the Jupyter Book.

Installation method

It's easy to install using pip. I'm using pip, Jupyter Lab and zsh on macOS, so I'll explain them with screenshots. This article is recommended for installing Jupyter Lab. First, start the terminal. Then install with the pip/conda command.

% pip install -U jupyter-book

Basic commands

After installation, move to a directory of your choice and create a Jupyter Book project. Jupyter Book uses the jupyter-book or jb command. There is no difference between them, so we will use the short jb from now on.

jb create

Create a Jupyter Book project named "test_book" with jb create. You can change the project name. Although not used here, create can also add the --cookiecutter option.

% jb create test_book

A template Jupyter Book has been created in test_book /.

jb build You can build Jupyter Book with jb build.

% cd test_book
% jb build .

After a lengthy log is displayed, when the build is complete, you should see something like this: An HTML file has been created in test_book/_build/html. Let's display it with a browser such as Chrome. Type the HTML path directly into your browser or use a command like the one below.

% open /Applications/Google\ Chrome.app _build/html/index.html

You should see something like this: I was able to easily create a document.

Official demo book

An official demo book is also available. I personally recommend the option not to run at build time as it can cause errors at build time.

% git clone https://github.com/executablebooks/quantecon-mini-example
% cd quantecon-mini-example/mini_book
% cat _config.yml

Now rewrite execute_notebooks in _config.yml to"off". Let's build it and display it in the browser.

% jb build .
% open /Applications/Google\ Chrome.app _build/html/index.html

Create a PDF

As with HTML, creating a PDF can be as easy. There are two methods, with some differences.

① How to create from a browser

When you view the HTML in your browser, there is a download button in the upper right corner. Click to specify the download format. You can save the PDF file by clicking .pdf. That's it.

② How to build and create

This method requires pyppeteer, so install it.

% pip install pyppeteer

Jupyter Book can also be built on a page-by-page basis. Let's convert notebook.ipynb in the test_book created earlier to PDF. Specify --builder pdf html at the time of build.

% cd test_book
% jb build notebooks.ipynb --builder pdfhtml

When the following is displayed, the PDF is complete. With this method, the bar displayed on the right side in ① was not displayed. Alternatively, you can create a ".tex" file or use $ \ LaTeX $ to create a PDF. See Official Reference PDF Page for more information.

Jupyter Book Customization

So far, I have introduced how to convert ".ipynb or .md" → "HTML or PDF". Here's how to change the page content and structure of the Jupyter Book. The code here is published on GitHub as we will discuss later, so if you want to copy it, please refer to it.

Add page

To add a page, add ".ipynb" or ".md" to the directory. Here, create "test_page.ipynb". For example, create it with the following contents.

_config.yml Edit _config.yml. This file describes the Jupyter Book settings. See the official reference config page (https://jupyterbook.org/customize/config.html) for more information. Here I edited title, author, and execute_notebooks. By the way, I added it at the bottom so that I can use the formula.

_toc.yml Edit _toc.yml. This file describes the structure of the Jupyter Book. See the official reference toc page (https://jupyterbook.org/customize/toc.html) for more information. Here, the page structure is as follows. If you build with this content, it will be displayed as follows. I was able to add pages and change the structure of the table of contents.

MyST Markdown

The Jupyter Book allows you to use an extended Markdown called MyST Markdown. Here, I will explain Directives and Roles, which are frequently used personally.

For normal Markdown, see Qiita official How to write Markdown. MyST Markdown also has Official Reference and Cheat Sheet, so be sure to check them out as well.

Directives Directives is a feature that allows you to create content blocks like the one at the bottom of the "test page" earlier. The format is as follows. Create a file called directives.md to introduce the types and formats. You can create a content block by writing:

admonition is a special format that allows you to freely set the title and class. In this example, : class: tip specifies the content block of tip.

If you specify code-block and the language, it will be displayed according to each language.

The content block looks like this. Here, in the content block, the word to be written in {} is written. Please note that if there is no content, an error will occur. If you specify {code-cell} instead of {code-block} and write JupytText at the beginning of the .md file, not only the code will be displayed but also the execution result will be displayed. can also do. It can also be nested.

There are many other formats, see the Jupyter Book MyST Markdown page (https://jupyterbook.org/content/myst.html) and the MyST Directives page (https://myst-parser.readthedocs.io/en/latest/using/syntax.html#directives-a-block-level-extension-point).

Roles

Roles, unlike Derectives, are written like this on one line. For example, you can display a check mark by writing the following. There are many other formats, see the MyST Roles page (https://myst-parser.readthedocs.io/en/latest/using/syntax.html#roles-an-in-line-extension-point).

Publication of Jupyter Book

Jupyter Book generates HTML so you can configure static websites. Here, let's publish the Jupyter Book using GitHub Pages.

Repository initialization

Create a new repository for Jupyter Book on GitHub. Please access the following page.

https://github.com/new

This time, I created a repository named test_book_online. Edit the repository part of _config.yml to change the link to the repository in Jupyter Book. Set up the repository from here. First, set the master branch with the following command. Replace your username and repository name with your own.

% cd test_book
% git init
% git add .
% git commit -m "adding my first book"
% git remote add origin https://github.com/<User name>/<Repository name>.git
% git push origin master

You have now set up the repository. Next, set up GitHub Pages using Python's ghp-import package. You don't need to run git branch gh-pages etc ** as ghp-import will automatically create a gh-pages branch.

% pip install ghp-import
% ghp-import -n -p -f _build/html

After a short wait, go to https: // <username> .github.io/<repository name> and you should see the contents of test_book. In my case, replace it with https://magolors.github.io/test_book_online.

I was able to publish it. If you like, I would be grateful if you could add Star ★ to the ** repository. ** You can jump to the repository from the GitHub mark on the upper right.

Repository update

If you want to update the source code of Jupyter Book, please execute as follows.

% cd test_book
% jb build .
% git checkout master
% git add .
% git commit -m "comment"
% git push origin master

If you want to update GitHub Pages, please do as follows. You don't need to run git checkout gh-pages **.

% cd test_book
% jb build .
% git checkout master
% ghp-import -n -p -f _build/html

In addition to this method, there is also a method called Automatically update GitHub Pages when Jupyter Book is updated using GitHub Actions.

Finally

So far, I have briefly introduced the Jupyter Book. There are so many other features besides the ones mentioned here, so be sure to check out the Official Reference (https://jupyterbook.org/index.html). Also, if there are other types of Directives or if you have any mistakes, please let us know in the comments.

Thank you for reading this far. If you find it interesting, please press LGTM and it will be encouraging: smile: