If you have a Google Account, you can use Google Analytics to collect someinformation on the traffic to your Jupyter Book. With this tool, you can findout how many people are using your book, where they come from and how theyaccess it, wether they are using the Desktop or the mobile version etc.

To add Google Analytics to your Jupyter Book, navigate toGoogle Analytics, create a newGoogle Analytics account and add the url of your Jupyter Book to a newproperty. Once you have set everything up, your Google Analytics propertywill have a so-called Tracking-ID, that typically starts with the letters UA.All that you need to do is to copy this ID and paste it into yourconfiguration file:

Retain custom YAML front-matter in your files

Jupyter book will check your files for YAML front-matter and will appendany newly-generated YAML to the built files for the page. This means youcan provide your own custom YAML to files (which may be useful if you'd liketo modify this book's HTML).

Be careful not to add YAML with the same key names as the auto-generated YAML, asthis will create duplicated keys in your page's front-matter.

If you wish, you may deploy a JupyterHub alongside your textbook. This way, for pages that are built fromJupyter Notebooks, students can click the "interact" linksat the top of each page and be taken to a live Jupyter Notebook running on your JupyterHub.

The easiest way to set up a JupyterHub is to follow The Littlest JupyterHub guide.This is a straightforward deployment of JupyterHub on a single VM, and is suitable forcourses / workshops of less than 50-60 students.

Auto-generating a TOC file for your book

Sometimes it can be a pain to create the Table of Contents YAML file by hand.Jupyter Book has a convenience function to automatically create this fileusing the alpha-numeric sorting of the file/folder names in your content folder.To use it, simply use the following command:

jupyter-book toc path/to/mybook

This put all .md and .ipynb files in the root of the content folderas top-level pages. For any files that are in folders, it will create onesection per top-level folder and place all content files inside thatsection.

By default, running this command will print the TOC YAML to the screen.If you'd like to overwrite your _data/toc.yml file with the result ofrunning this command, you can use the argument like so

This will overwrite the contents of toc.yml with the new TOC.

Sometimes you'd like to quickly scan through a notebook's cells in order toadd tags based on the content of the cell. For example, you might want tohide any cell with an import statement in it using the remove_input tag.

import nbformat as nbf
from glob import glob
 
notebooks = glob("./content/**/*.ipynb", recursive=True)
 
# Text to look for in adding tags
text_search_dict = {
    "# HIDDEN": "remove_cell",  # Remove the whole cell
    "# NO CODE": "remove_input",  # Remove only the input
    "# HIDE CODE": "hide_input"  # Hide the input w/ a button to show
}
 
# Search through each notebook and look for th text, add a tag if necessary
for ipath in notebooks:
    ntbk = nbf.read(ipath, nbf.NO_CONVERT)
 
        cell_tags = cell.get('metadata', {}).get('tags', [])
        for key, val in text_search_dict.items():
            if key in cell['source']:
                if val not in cell_tags:
                    cell_tags.append(val)
        if len(cell_tags) > 0:
            cell['metadata']['tags'] = cell_tags
 
    nbf.write(ntbk, ipath)

Customizing your toc.yml file

The toc.yml file is used to control the chapter order etc of your book.There are a few extra features you can use to trigger certain kinds of behavior.This section explains the possible structure of this file so you can customize itas you like.

Below is all of the possible fields in the entry of a single page in :

To add an external link in your TOC, simply make the url point to a fully-resolvedURL and add the external: true field. Here's an example:

- title: Jupyter Homepage   # Title of chapter or section
  url: https://jupyter.org  # URL of external site
  external: true

These are special entries that will trigger different behavior if they arein the toc.yml file:

If you're comfortable with continuous integration services like CircleCI, you can set upa build job to build your book's HTML automatically and push them to an online repository(such as a gh-pages branch). This is a fairly advanced topic, but for some guidance,check out these resources:

• covers how you can give CircleCI permissions to push to a branch from within a job.

This page was created by The Jupyter Book Community