How-to and FAQ¶
This page contains more advanced and complete information about the
jupyter-book repository. See the sections below.
Enable Google Analytics¶
If you have a Google Account, you can use Google Analytics to collect some information on the traffic to your Jupyter Book. With this tool, you can find out how many people are using your book, where they come from and how they access it, whether they are using the Desktop or the mobile version etc.
To add Google Analytics to your Jupyter Book, navigate to Google Analytics, create a new Google Analytics account and add the url of your Jupyter Book to a new property. Once you have set everything up, your Google Analytics property will 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 your configuration file:
html: google_analytics_id: UA-XXXXXXXXX-X
Clean your book’s generated files¶
It is possible to “clean up” the files that you generate when you build your book. This is often useful if you have recently changed a lot of content in order to ensure that you build your book from a clean slate.
You can clean up your book’s generated content by running the following command:
jupyter-book clean mybookname/
By default, this will delete all folders inside
for a folder called
.jupyter_cache. This ensures that the content of your book
will be regenerated, while the cache that is generated by running your book’s code
will not be deleted (because regenerating it may take some time).
To delete the
.jupyter_cache folder as well, add the
--all flag like so:
jupyter-book clean mybookname/ --all
This will entirely remove the folders in the
Use raw HTML in Markdown¶
Jupyter notebook markdown allows you to use pure HTML in markdown cells. This is discouraged in most cases, because it will usually just be passed through the build process as raw text, and so will not be subject to processes like:
Relative path corrections
Copying of assets to the build folder
Multiple output type formatting (e.g. it will not show in PDFs!).
So, for instance, below we add, and you will find that the HTML link is broken:
<a href="../intro.md">Go Home HTML!</a> [Go Home Markdown!](../intro.md)
Note that MyST markdown now has some extended syntax features, which can allow you to use certain HTML elements in the correct manner.
<img src="../images/fun-fish.png" alt="the fun fish!" width="200px"/>
See the image appearance section for details.
Adding extra HTML to your book¶
There are a few places in Jupyter Book where you can add arbitrary extra HTML.
In all cases, this is done with a configuration value in your
Working on Windows¶
Jupyter Book is now also tested against a Windows environment on Python 3.7 😀
For its specification, see the
windows-latest runner used by GitHub CI.
However, there is a known incompatibility for notebook execution, when using Python 3.8 (see issue #906).
If you’re running a recent version of Windows 10 and encounter any issues, you may also wish to try installing Windows Subsystem for Linux.
As of June 5, 2020, there were three open issues that required Windows-specific changes. We hope these are now fixed in jupyter-book version 0.8 but, in case any issues still arise, leave these community tips, which are known to work for some users. Note that there is no guarantee that they will work on all windows installations.
Jupyter-book currently reads and writes files on windows in the native windows encoding, which causes encoding errors for some characters in UTF-8 encoded notebooks.
Work-around: Beginning with Python 3.7 cmd.exe or powershell enviroments that set PYTHONUTF8=1 override the native locale encoding and use UTF8 for all input/output.
A new windows event loop
The asyncio event loop has been changed for Python 3.8 causing sphinx-build to fail.
Work-around: Pin to Python 3.7.6. This environment_win.yml file does that, and also installs runjb to fix issue 1.
Nested tables of contents
_toc.ymlfiles that reference markdown files in sub-folders are failing for some windows users. That is, this original _toc.yml file will fail with a message saying jupyter-book “
cannot find index.md”
Work-around: Flatten the layout of the book to a single level, i.e. this _toc.yml file works with windows.
The following workflow should succeed using a miniconda powershell terminal on Windows 10:
conda install git
git clone https://github.com/eoas-ubc/quantecon-mini-example.git
git checkout windows
conda env create -f environment_win.yml
conda activate wintest
After the build, view the html with: