Jupyter Book

https://jupyter-book.readthedocs.io/v1/
Admin
Jupyter Book is a tool for building beautiful, publication-quality books and documents from...
Tokens:56,494
Snippets:888
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install sphinx-proof Extension

Source: https://jupyter-book.readthedocs.io/v1/content/proof.html

Install the sphinx-proof extension using pip. This package is not included by default and requires manual installation.

```bash
pip install sphinx-proof

```

--------------------------------

### Show Version

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Displays the installed version of Jupyter Book and exits.

```bash
jupyter-book --version
```

--------------------------------

### ipywidgets Tab Example

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

Creates a tabbed interface with multiple text widgets. Ensure ipywidgets is installed; some functionality may depend on a running kernel.

```python
tab_contents = ['P0', 'P1', 'P2', 'P3', 'P4']
children = [widgets.Text(description=name) for name in tab_contents]
tab = widgets.Tab()
tab.children = children
for ii in range(len(children)):
    tab.set_title(ii, f"tab_{ii}")
tab

```

--------------------------------

### Cite Work in Multiple Documents with Key Prefix (Document 2)

Source: https://jupyter-book.readthedocs.io/v1/content/citations.html

This example shows the citation and bibliography setup for the second document when using `keyprefix` to cite a work across multiple documents.

```rst
"...Freedom is slavery."{cite}`b-Orwell1984`
```

```rst
```{bibliography}
:filter: docname in docnames
:labelprefix: B
:keyprefix: b-
```
```

--------------------------------

### Install Pre-commit Hooks

Source: https://jupyter-book.readthedocs.io/v1/contribute/intro.html

Enable pre-commit for the cloned repository to maintain code style and quality before commits.

```bash
pre-commit install
```

--------------------------------

### Install Jupyter Book with Development Dependencies

Source: https://jupyter-book.readthedocs.io/v1/contribute/intro.html

Install Jupyter Book in editable mode, including packages for testing and code style.

```bash
python -m pip install -e .[testing,code_style]
```

--------------------------------

### Install Playwright for PDF Building

Source: https://jupyter-book.readthedocs.io/v1/advanced/pdf.html

Installs the `playwright` library and its dependencies, which are required for converting HTML to PDF. Ensure you run this in your environment.

```bash
pip install playwright
playwright install --with-deps chromium
```

--------------------------------

### Create an Interactive Scatter Plot with Altair

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

This example demonstrates creating an interactive scatter plot using Altair, mapping various data columns to visual properties like position, color, and size. Ensure Altair is installed and outputs are self-contained.

```python
import altair as alt
alt.Chart(data=data).mark_point().encode(
    x="sepal_width",
    y="sepal_length",
    color="species",
    size='sepal_length'
)
```

--------------------------------

### Multi-language Tab Examples

Source: https://jupyter-book.readthedocs.io/v1/content/components.html

Demonstrates using tabbed content to display code examples in various programming languages.

```c++
int main(const int argc, const char **argv) {
  return 0;
}

```

```python
def main():
    return

```

```java
class Main {
    public static void main(String[] args) {
    }
}

```

```julia
function main()
end

```

```fortran
PROGRAM main
END PROGRAM main

```

--------------------------------

### Cite Work in Multiple Documents with Key Prefix (Document 1)

Source: https://jupyter-book.readthedocs.io/v1/content/citations.html

Use the `keyprefix` option to cite a work in multiple documents. This example shows the citation and bibliography setup for the first document.

```rst
"...If you want to keep a secret, you must also hide it from yourself"{cite}`a-Orwell1984`
```

```rst
```{bibliography}
:filter: docname in docnames
:labelprefix: A
:keyprefix: a-
```
```

--------------------------------

### Install compatible docutils version

Source: https://jupyter-book.readthedocs.io/v1/content/citations.html

If you encounter layout issues with the bibliography directive due to docutils version conflicts, install docutils==0.17.1.

```bash
pip install docutils==0.17.1
```

--------------------------------

### Configure sphinx-proof Extension in _config.yml

Source: https://jupyter-book.readthedocs.io/v1/content/proof.html

Add 'sphinx_proof' to the 'extra_extensions' list in your '_config.yml' file to enable the extension. This is necessary after installation.

```yaml
sphinx:
  extra_extensions:
    - sphinx_proof

```

--------------------------------

### Install Jupytext

Source: https://jupyter-book.readthedocs.io/v1/file-types/jupytext.html

Install Jupytext using pip. This is a prerequisite for using Jupytext file formats with Jupyter Book.

```bash
pip install jupytext
```

--------------------------------

### Install LaTeX packages on Debian-based Linux

Source: https://jupyter-book.readthedocs.io/v1/advanced/pdf.html

Recommended packages for building PDFs with LaTeX on Debian-based Linux systems.

```bash
sudo apt-get install texlive-latex-extra \
                     texlive-fonts-extra \
                     texlive-xetex latexmk

```

--------------------------------

### Install sphinx-inline-tabs

Source: https://jupyter-book.readthedocs.io/v1/advanced/sphinx.html

Install the sphinx-inline-tabs package using pip. This is a prerequisite for using synchronized tabs in your Jupyter Book.

```bash
pip install sphinx-inline-tabs

```

--------------------------------

### Block Equation Example

Source: https://jupyter-book.readthedocs.io/v1/content/math.html

Wrap equations in `$$` or `\begin` statements to create block equations. This is ideal for longer or more complex equations that require their own line.

```markdown
$$  \int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15} $$

```

--------------------------------

### Build and Deploy Jupyter Book with Pip

Source: https://jupyter-book.readthedocs.io/v1/publish/gh-pages.html

This workflow installs Python dependencies using pip from `requirements.txt`, builds the Jupyter Book, uploads the HTML output as an artifact, and deploys it to GitHub Pages. It includes caching for executed notebooks.

```yaml
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v5

      # Install dependencies
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.13"
          cache: pip # Implicitly uses requirements.txt for cache key

      - name: Install dependencies
        run: pip install -r requirements.txt

      # (optional) Cache your executed notebooks between runs
      # if you have config:
      # execute:
      #   execute_notebooks: cache
      - name: cache executed notebooks
        uses: actions/cache@v4
        with:
          path: _build/.jupyter_cache
          key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}

      # Build the book
      - name: Build the book
        run: |
          jupyter-book build .

      # https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

      # Upload the book's HTML as an artifact
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: _build/html

      # Deploy the book's HTML to GitHub Pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### MyST Notebook Structure Example

Source: https://jupyter-book.readthedocs.io/v1/file-types/myst-notebooks.html

A basic MyST notebook demonstrating the YAML frontmatter, a Python code cell with tags, and Markdown content.

```markdown
---

```

```yaml
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# My simple notebook

Some **intro Markdown**!


```

```python
```{code-cell}
:tags: [mytag]

print("A python cell")
```

## A section

And some more Markdown...


```

--------------------------------

### Netlify Build Command for Jupyter Book

Source: https://jupyter-book.readthedocs.io/v1/publish/netlify.html

Use this command in the Netlify build settings to install your book's dependencies and build the HTML version of your Jupyter Book. Ensure your requirements.txt is up-to-date.

```bash
pip install -r requirements.txt && jupyter-book build .
```

--------------------------------

### Basic Definition List Example

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

A simple definition list where each term is followed by its definition, separated by a colon.

```markdown
Term 1
: Definition

Term 2
: Definition

```

--------------------------------

### Create a Jupyter Book template

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Use this command to create a new Jupyter Book project template. You can optionally use cookiecutter for an interactive setup or disable user input with --no-input.

```bash
jupyter-book create [OPTIONS] PATH_BOOK
```

--------------------------------

### Update nb_render_priority to nb_mime_priority_overrides

Source: https://jupyter-book.readthedocs.io/v1/explain/migration.html

This example shows the transformation of the `nb_render_priority` configuration to the new `nb_mime_priority_overrides` format, which accepts a sequence of tuples with builder name, mime type, and priority.

```yaml
sphinx:
  config:
    nb_render_priority:
      - "application/vnd.jupyter.widget-view+json"
      - "application/javascript"
      - "text/html"
      - "text/latex"
      - "image/svg+xml"
      - "image/png"
      - "image/jpeg"
      - "text/markdown"
      - "text/plain"

```

```yaml
sphinx:
  config:
    nb_mime_priority_overrides: [
      ['html', 'application/vnd.jupyter.widget-view+json', 10],
      ['html', 'application/javascript', 20],
      ['html', 'text/html', 30],
      ['html', 'text/latex', 40],
      ['html', 'image/svg+xml', 50],
      ['html', 'image/png', 60],
      ['html', 'image/jpeg', 70],
      ['html', 'text/markdown', 80],
      ['html', 'text/plain', 90],
    ]

```

--------------------------------

### ipywidgets IntSlider Example

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

Renders an interactive integer slider widget. Note that ipywidgets may require a running kernel for full functionality.

```python
import ipywidgets as widgets
widgets.IntSlider(
    value=7,
    min=0,
    max=10,
    step=1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True,
    readout_format='d'
)

```

--------------------------------

### Add Custom Sphinx Extensions

Source: https://jupyter-book.readthedocs.io/v1/advanced/sphinx.html

Configure your `_config.yml` to include additional Sphinx extensions. Ensure all extensions are installed on your system before building.

```yaml
sphinx:
  extra_extensions:
   - extension1
   - extension2

```

--------------------------------

### GitHub Actions Workflow for Pip Deployment

Source: https://jupyter-book.readthedocs.io/v1/publish/gh-pages.html

This YAML configuration sets up a GitHub Action to deploy a Jupyter Book. It triggers on pushes to the master or main branches, installs Jupyter Book using pip, builds the HTML output, and deploys it to GitHub Pages. Ensure you are using Jupyter Book version 1.0.0 or later.

```yaml
name: deploy-book

# Run this when the master or main branch changes
on:
  push:
    branches:
      - master
      - main
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - some-subfolder/**

```

--------------------------------

### Use Built-in Admonition Directives

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Provides examples for using standard admonition directives like note, warning, tip, caution, attention, danger, error, hint, and important.

```rst
.. note::

   text
```

```rst
.. note:: text

some more text...
```

```rst
.. warning::

   This is an example
   of a warning directive.
```

```rst
.. tip::

   This is an example
   of a tip directive.
```

```rst
.. caution::

   This is an example
   of a caution directive.
```

```rst
.. attention::

   This is an example
   of an attention directive.
```

```rst
.. danger::

   This is an example
   of a danger directive.
```

```rst
.. error::

   This is an example
   of an error directive.
```

```rst
.. hint::

   This is an example
   of a hint directive.
```

```rst
.. important::

   This is an example
   of an important directive.
```

--------------------------------

### Build your book using the command line

Source: https://jupyter-book.readthedocs.io/v1/basics/build.html

Use this command to build your book's outputs. Replace `<path-to-book>` with the actual path to your book's directory.

```bash
jupyter-book build <path-to-book>

```

--------------------------------

### Show Create Command Help

Source: https://jupyter-book.readthedocs.io/v1/basics/create.html

View available options for creating a Jupyter Book template. This command displays usage information and available flags.

```bash
jupyter-book create --help

```

--------------------------------

### Plotly Scatter Plot Example

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

This code generates a scatter plot using Plotly Express with the iris dataset. Ensure Plotly is installed and configured.

```python
import plotly.io as pio
import plotly.express as px
import plotly.offline as py

df = px.data.iris()
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", size="sepal_length")
fig

```

--------------------------------

### Bokeh Scatter Plot Example

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

This code creates a scatter plot using Bokeh, mapping data columns to visual properties. Ensure Bokeh is installed.

```python
p = figure()
p.circle(data["sepal_width"], data["sepal_length"], fill_color=data["species"], size=data["sepal_length"])
show(p)

```

--------------------------------

### Build with Custom Configuration

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Builds the book using a specified YAML configuration file.

```bash
jupyter-book build --config <config> PATH_SOURCE
```

--------------------------------

### Build with Specific Builder

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Specifies which builder to use for the book build. Options include 'html', 'pdfhtml', 'latex', etc.

```bash
jupyter-book build --builder <builder> PATH_SOURCE
```

--------------------------------

### Configure Sphinx LaTeX Top-Level Sectioning

Source: https://jupyter-book.readthedocs.io/v1/advanced/pdf.html

Pass Sphinx configuration options through the `_config.yml` file to customize LaTeX output. This example sets `latex_toplevel_sectioning` to 'part' instead of the default 'chapter'.

```yaml
sphinx:
  config:
    latex_toplevel_sectioning: 'part'

```

--------------------------------

### Build with Output Path

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Builds the book and specifies a custom path for the output artifacts.

```bash
jupyter-book build --path-output <path_output> PATH_SOURCE
```

--------------------------------

### Create a Simple Jupyter Book Template

Source: https://jupyter-book.readthedocs.io/v1/basics/create.html

Generate a basic Jupyter Book structure locally. This is useful for quickly creating a sample book to build and explore, with initial configuration files provided.

```bash
jupyter-book create mynewbook/

```

--------------------------------

### Common Launch Button Configuration

Source: https://jupyter-book.readthedocs.io/v1/interactive/launchbuttons.html

Configure repository information to specify where your book content is hosted online. This is essential for creating functional launch buttons.

```yaml
repository:
  url                       : https://github.com/yourusername/yourbookrepo  # Online location of your book
  path_to_book              : path/to/book  # Optional path to your book, relative to the repository root
  branch                    : master  # Which branch of the repository should be used when creating links (optional)

```

--------------------------------

### Display command line help menu

Source: https://jupyter-book.readthedocs.io/v1/file-types/notebooks.html

Use the '!' prefix to execute shell commands and display their output. This is useful for showing command-line tool help menus.

```shell
!jupyter-book build --help
```

```text
Usage: jupyter-book build [OPTIONS] PATH_SOURCE

  Convert your book's or page's content to HTML or a PDF.

Options:
  --path-output TEXT              Path to the output artifacts
  --config TEXT                   Path to the YAML configuration file
                                  (default: PATH_SOURCE/_config.yml)
  --toc TEXT                      Path to the Table of Contents YAML file
                                  (default: PATH_SOURCE/_toc.yml)
  -W, --warningiserror            Error on warnings.
  -n, --nitpick                   Run in nit-picky mode, to generates warnings
                                  for all missing references.
  --keep-going                    With -W, do not stop the build on the first
                                  warning, instead error on build completion
  --all                           Re-build all pages. The default is to only
                                  re-build pages that are new/changed since
                                  the last run.
  --builder [html|dirhtml|singlehtml|pdfhtml|latex|pdflatex|linkcheck|custom]
                                  Which builder to use.
  --custom-builder TEXT           Specify alternative builder provided by
                                  Sphinx, including text and epub. This can
                                  only be used with --builder=custom. Valid
                                  options listed at https://www.sphinx-
                                  doc.org/en/master/man/sphinx-build.html
  -v, --verbose                   increase verbosity (can be repeated)
  -q, --quiet                     -q means no sphinx status, -qq also turns
                                  off warnings
  --individualpages               [pdflatex] Enable build of PDF files for
                                  each individual page
  -h, --help                      Show this message and exit.

```

--------------------------------

### Install JupyterHub Dependencies

Source: https://jupyter-book.readthedocs.io/v1/interactive/launchbuttons.html

Install necessary Python packages, jupytext and nbgitpuller, for JupyterHub integration by adding a RUN command to your Dockerfile.

```dockerfile
RUN pip install jupytext nbgitpuller

```

--------------------------------

### Build a Template Jupyter Book

Source: https://jupyter-book.readthedocs.io/v1/contribute/intro.html

Build the bundled template Jupyter Book using the command-line tool.

```bash
jupyter-book build
```

--------------------------------

### Build Book or Page

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Converts your book's or page's content to HTML or a PDF. Specify the source path and use options to customize the build process.

```bash
jupyter-book build [OPTIONS] PATH_SOURCE
```

--------------------------------

### Create a basic grid with items

Source: https://jupyter-book.readthedocs.io/v1/content/components.html

Use the `grid` directive with `grid-item` directives inside to create a grid layout. Gutters between items can be controlled with the `:gutter:` option.

```rst
::::{grid}
:gutter: 2

:::{grid-item}
:outline:
A
:::
:::{grid-item}
:outline:
B
:::
:::{grid-item}
:outline:
C
:::
:::{grid-item}
:outline:
D
:::

::::

```

--------------------------------

### RMarkdown Block Example

Source: https://jupyter-book.readthedocs.io/v1/file-types/jupytext.html

Example of an RMarkdown block within a Jupyter Book document. Note that some execution features may not be available.

```markdown
```{python echo=TRUE}
print("Hallo I'm an RMarkdown block!")
```
```

--------------------------------

### Create Book Project from TOC

Source: https://jupyter-book.readthedocs.io/v1/basics/create.html

Use this command to generate book files based on the structure defined in your `_toc.yml` file. This is useful for quickly setting up the basic file structure of your book.

```bash
jupyter-book toc to-project path/to/_toc.yml
```

--------------------------------

### Epigraph Example

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

Use the `epigraph` MyST directive to highlight quotes and their authors. Keep epigraphs concise.

```markdown
```{epigraph}
Here is a cool quotation.

From me, Jo the Jovyan
```

```

--------------------------------

### Markdown Quotation Example

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

Standard Markdown syntax using a caret (>) symbol to create block quotations.

```markdown
> Here is a cool quotation.
>
> From me, Jo the Jovyan

```

--------------------------------

### Build with a Custom Sphinx Builder via CLI

Source: https://jupyter-book.readthedocs.io/v1/advanced/sphinx.html

Initiate builds for a custom Sphinx builder from the command line using the `jb build` command with the `--builder` and `--custom-builder` options.

```bash
jb build <project> --builder=custom --custom-builder=<builder-name>
```

--------------------------------

### Build a book-style PDF using pdflatex builder

Source: https://jupyter-book.readthedocs.io/v1/advanced/pdf.html

Command to build a PDF of your entire project using the pdflatex builder.

```bash
jupyter-book build mybookname/ --builder pdflatex

```

```bash
jb build mybookname/ --builder pdflatex

```

--------------------------------

### Build Book with Link Checker

Source: https://jupyter-book.readthedocs.io/v1/advanced/html.html

Use the `jupyter-book build` command with the `--builder linkcheck` option to verify all external links in your book.

```bash
jupyter-book build mybookname/ --builder linkcheck
```

--------------------------------

### MyST Quote Syntax

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Create blockquotes in MyST Markdown by starting a line with '>'. This is useful for highlighting specific text.

```markdown
> text
```

--------------------------------

### Nested Markdown-Friendly Directives

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

Admonitions defined with `:::` fences can be nested. This example shows a nested note within an important directive.

```markdown
::::{important}
:::{note}
This text is **standard** _Markdown_
:::
::::
```

--------------------------------

### MyST Line Comment Syntax

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Add line comments in MyST Markdown by starting a line with '%'. These comments are ignored during rendering.

```markdown
% text
```

--------------------------------

### Build with Custom Table of Contents

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Builds the book using a specified YAML file for the Table of Contents.

```bash
jupyter-book build --toc <toc> PATH_SOURCE
```

--------------------------------

### View Sphinx Configuration

Source: https://jupyter-book.readthedocs.io/v1/explain/sphinx.html

Run this command to see the Sphinx configuration file that Jupyter Book generates for your project.

```bash
jupyter-book config sphinx path/to/mybook/
```

--------------------------------

### Build book with error checking and continuous build

Source: https://jupyter-book.readthedocs.io/v1/basics/build.html

Use this command to check for missing references, treat them as errors, and continue the build to see all errors in one run. Increase verbosity with -v or -vvv.

```bash
jupyter-book build -W -n --keep-going mybookname/
```

--------------------------------

### Create HTML Admonition

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

Define admonitions using pure HTML with the `html_admonitions` extension. This example shows a 'note' admonition with custom styling.

```html
<div class="admonition note" name="html-admonition" style="background: lightgreen; padding: 10px">
<p class="title">This is the **title**</p>
This is the *content*
</div>

```

--------------------------------

### Build with Quiet Output

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Reduces the verbosity of the build output. Use -q for no Sphinx status messages, and -qq to also suppress warnings.

```bash
jupyter-book build -q PATH_SOURCE
```

--------------------------------

### Inline Math Example

Source: https://jupyter-book.readthedocs.io/v1/content/math.html

Use the `$` symbol to insert inline math directly within a Markdown cell. This is useful for short mathematical expressions.

```markdown
`$this_{is}^{inline}$`
```

--------------------------------

### Paste Glued Variable as Block

Source: https://jupyter-book.readthedocs.io/v1/content/executable/output-insert.html

This is an example of how to paste a glued variable as a block element in your Jupyter Book page using the `glue` directive.

```markdown
```{glue:} your-key
```
```

--------------------------------

### Create Jupyter Book with Cookiecutter Template

Source: https://jupyter-book.readthedocs.io/v1/reference/_changelog.html

Use the `jupyter-book create --cookiecutter` command to initialize a new book project using a cookiecutter template. This is suitable for advanced users wanting a pre-configured repository with metafiles and workflows.

```bash
jupyter-book create --cookiecutter my-new-book
```

--------------------------------

### Remove Stderr at Cell Level

Source: https://jupyter-book.readthedocs.io/v1/content/execute.html

Prevent stderr from being displayed for a specific code cell by applying the `remove-stderr` tag. This example also shows stdout.

```python
```{code-cell} ipython3
:tags: [remove-stderr]

import sys
print("this is some stdout")
print("this is some stderr", file=sys.stderr)
```
```

--------------------------------

### Example of Full-Width Code Cell Output

Source: https://jupyter-book.readthedocs.io/v1/content/layout.html

This code snippet demonstrates how to create a wider figure by adjusting the `figsize` when using the `full-width` cell tag.

```python
make_fig(figsize=(20, 5))
```

--------------------------------

### Build PDF from HTML using jb command

Source: https://jupyter-book.readthedocs.io/v1/advanced/pdf.html

Alternative command to build a PDF from your book's HTML content using the `jb` shortcut. This command also uses the `pdfhtml` builder. Replace `mybookname/` with your book's directory.

```bash
jb build mybookname/ --builder pdfhtml
```

--------------------------------

### Add Source Repository Button

Source: https://jupyter-book.readthedocs.io/v1/basics/repository.html

Enable a button that links users directly to your source repository. Requires the repository URL to be configured.

```yaml
repository:
  url: https://github.com/{your-book-url}
html:
  use_repository_button: true

```

--------------------------------

### Configure Text Lexer

Source: https://jupyter-book.readthedocs.io/v1/content/code-outputs.html

Example configuration to disable ANSI color lexing for text outputs in a Sphinx environment. Set 'nb_render_text_lexer' to 'none' in '_config.yml'.

```yaml
sphinx:
  config:
    nb_render_text_lexer: "none"

```

--------------------------------

### MyST Ordered List Syntax

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Create ordered lists in MyST Markdown by starting lines with numbers followed by a period. Sub-lists can be created with indentation.

```markdown
1. First item
2. Second item
    1. First sub-item
```

```markdown
1. First item
2. Second item
    * First sub-item
```

--------------------------------

### Suppress Plotly Build Warnings

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

Starting from jupyter-book version 0.14, Plotly figures may generate warnings. Suppress these by adding configuration to your `_config.yml`.

```yaml
sphinx:
  config:
    suppress_warnings: ["mystnb.unknown_mime_type"]

```

--------------------------------

### Jupyter Book Create Command Usage

Source: https://jupyter-book.readthedocs.io/v1/basics/create.html

Displays the usage and options for the `jupyter-book create` command, including flags for using cookiecutter and controlling user input.

```bash
Usage: jupyter-book create [OPTIONS] PATH_BOOK

  Create a Jupyter Book template that you can customize.

Options:
  --cookiecutter  Use cookiecutter to interactively create a Jupyter Book
                  template.
  --no-input      If using cookiecutter, do not prompt the user for input.
  -h, --help      Show this message and exit.

```

--------------------------------

### Add JupyterHub Launch Button

Source: https://jupyter-book.readthedocs.io/v1/interactive/launchbuttons.html

Configure the URL for your JupyterHub to automatically insert interactive launch links for your readers. Ensure nbgitpuller and jupytext are installed on the server.

```yaml
launch_buttons:
  jupyterhub_url: "your-hub-url"  # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)

```

--------------------------------

### Initialize Variable with Thebe

Source: https://jupyter-book.readthedocs.io/v1/interactive/thebe.html

Use the `thebe-init` tag to run this cell upon kernel initialization. Subsequent cells can access variables defined here. Consider pairing with `hide-input` to conceal initialization code.

```python
my_hidden_variable = 'wow, it worked!'

```

--------------------------------

### Figure Glue Directive Syntax

Source: https://jupyter-book.readthedocs.io/v1/explain/migration.html

The `glue` directive for figures also results in a text representation. This example shows the syntax for gluing a figure from another document.

```myst
```{glue} sorted_means_fig
:doc: /content/executable/output-insert.md
```

```

--------------------------------

### Figure Scaling and Alignment (Right)

Source: https://jupyter-book.readthedocs.io/v1/content/figures.html

Control figure alignment and scaling using directive options. This example shows a figure scaled to 50% and aligned to the right.

```myst
```{figure} ../images/cool.jpg
---
scale: 50%
align: right
---
Here is my figure caption!
```
```

--------------------------------

### Figure Scaling and Alignment (Left)

Source: https://jupyter-book.readthedocs.io/v1/content/figures.html

Control figure alignment and scaling using directive options. This example shows a figure scaled to 50% and aligned to the left.

```myst
```{figure} ../images/cool.jpg
---
scale: 50%
align: left
---
Here is my figure caption!
```
```

--------------------------------

### Create Custom Admonitions

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Explains how to create custom admonition blocks with titles and specific classes like 'warning'.

```rst
.. admonition:: Title

   text
```

```rst
.. admonition:: This is a title

   An example of an admonition with a title.
```

```rst
.. admonition:: This is a title
   :class: warning

   An example of an admonition with a title and a warning style.
```

--------------------------------

### Set bibliography style using directive

Source: https://jupyter-book.readthedocs.io/v1/content/citations.html

Use the `:style:` option within the bibliography directive to customize the appearance of your references. This example sets the style to 'unsrt'.

```myst
```{bibliography}
:style: unsrt
```
```

--------------------------------

### Add Binder Launch Button

Source: https://jupyter-book.readthedocs.io/v1/interactive/launchbuttons.html

Configure the URL for your BinderHub to automatically insert Binder launch buttons on pages built from notebook content.

```yaml
launch_buttons:
  binderhub_url: "https://mybinder.org"  # The URL for your BinderHub (e.g., https://mybinder.org)

```

--------------------------------

### Numbering Equations with Math Directive

Source: https://jupyter-book.readthedocs.io/v1/content/math.html

Use the math directive with a label to number equations for later reference. Ensure labels do not start with an integer to avoid warnings.

```markdown
```{math}
:label: my_label
my_math
```
```

```markdown
```{math}
:label: my_label
w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
```
```

--------------------------------

### Build with Custom Sphinx Builder

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Allows specifying an alternative builder provided by Sphinx, such as 'text' or 'epub'. This option requires --builder=custom.

```bash
jupyter-book build --custom-builder <custom_builder> --builder custom PATH_SOURCE
```

--------------------------------

### Tabbed Content

Source: https://jupyter-book.readthedocs.io/v1/content/components.html

Use the `{tab-set}` and `{tab-item}` directives to create content organized into clickable tabs. This is useful for presenting multiple language examples or different views of the same information.

```rst
````{tab-set}
```{tab-item} Tab 1 title
My first tab
```

```{tab-item} Tab 2 title
My second tab with `some code`!
```
````
```

--------------------------------

### Shorthand for Jupyter Book CLI

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

Demonstrates the shorthand 'jb' command, which is equivalent to 'jupyter-book' for executing CLI commands.

```bash
jb build mybook/
```

--------------------------------

### Run Jupyter Book Tests with Pytest

Source: https://jupyter-book.readthedocs.io/v1/contribute/intro.html

Execute the Jupyter Book test suite using pytest, excluding tests that require additional installations like Chrome or LaTeX.

```bash
>> pytest -m 'not requires_chrome and not requires_tex'
```

--------------------------------

### Build and Deploy Jupyter Book with Conda

Source: https://jupyter-book.readthedocs.io/v1/publish/gh-pages.html

This workflow uses Conda to manage Python dependencies via `environment.yml`. It sets up Miniconda, activates the specified environment, builds the Jupyter Book, uploads the HTML output, and deploys to GitHub Pages.

```yaml
name: deploy-book

# Run this when the master or main branch changes
on:
  push:
    branches:
      - master
      - main
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - some-subfolder/**

# This job installs dependencies, builds the book, and pushes it to `gh-pages`
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    # https://github.com/marketplace/actions/setup-miniconda#example-3-other-options
    defaults:
      run:
        shell: bash -el {0}
    steps:
      - uses: actions/checkout@v5

      # Install dependencies
      - uses: conda-incubator/setup-miniconda@v3
        with:
          # If you don't have `python` included as a package in your `environment.yml`:
          # python-version: '3.13'
          environment-file: environment.yml
          auto-activate-base: false
          activate-environment: computing-in-context

      # Build the book
      - name: Build the book
        run: |
          jupyter-book build .

      # Upload the book's HTML as an artifact
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _build/html

      # Deploy the book's HTML to GitHub Pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### Configure a custom Sphinx theme

Source: https://jupyter-book.readthedocs.io/v1/advanced/sphinx.html

Set a custom Sphinx theme for your Jupyter Book by specifying the theme name in the sphinx: config section of _config.yml. Ensure the theme is installed separately.

```yaml
sphinx:
  config:
    html_theme: pydata_sphinx_theme

```

--------------------------------

### Initialize Bokeh Output

Source: https://jupyter-book.readthedocs.io/v1/interactive/interactive.html

Initialize Bokeh for notebook output. This should be in a separate cell to allow JavaScript to load.

```python
from bokeh.plotting import figure, show, output_notebook
output_notebook()

```

--------------------------------

### Nesting Literal Code Blocks

Source: https://jupyter-book.readthedocs.io/v1/content/myst.html

Nest literal code blocks by increasing the number of backticks in the outer-most block. This example shows nesting a standard code block within another.

```markdown
````
```
```
````
```

--------------------------------

### Complex Definition List Example

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

Demonstrates advanced definition list features including Markdown within terms, multiple paragraphs in definitions, multiple definitions for a term, and embedded HTML.

```markdown
Term *with Markdown*
: Definition [with reference](content/definition-lists)

  A second paragraph
: A second definition

Term 2
  ~ Definition 2a
  ~ Definition 2b

Term 3
:     A code block
: > A quote
: A final definition, that can even include images:

  <img src="../images/fun-fish.png" alt="fishy" width="200px">

```

--------------------------------

### Include Images

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Shows how to include images with specified height and name using the `image` directive.

```rst
.. image:: ../images/C-3PO_droid.png
   :height: 150px
   :name: image-example
```

--------------------------------

### Use sphinx-inline-tabs with MyST Markdown

Source: https://jupyter-book.readthedocs.io/v1/advanced/sphinx.html

Integrate synchronized tabs into your Jupyter Book using MyST Markdown syntax. This example demonstrates defining and printing functions across different languages.

```markdown
````{tab} Python
```python
def main():
    return
```
````
````{tab} C++
```c++
int main(const int argc, const char **argv) {
  return 0;
}
```
````

Second two tabs showing off printing.

````{tab} Python
```python
print("Hello World!")
```
````

````{tab} C++
```c++
#include <iostream>

int main() {
  std::cout << "Hello World!" << std::endl;
}
```
````

```

--------------------------------

### Build with Missing Reference Checks

Source: https://jupyter-book.readthedocs.io/v1/content/references.html

Use build options `-W` (treat warnings as errors) and `-n` (check for missing references) to identify broken links during the build process. `--keep-going` allows the build to continue.

```bash
jupyter-book build -W -n --keep-going docs/
```

--------------------------------

### Basic API Reference with Automodule

Source: https://jupyter-book.readthedocs.io/v1/advanced/developers.html

Use the `automodule` directive in an `.rst` file to generate documentation for an entire module. Ensure this file is referenced in `_toc.yml`.

```rst
API Reference
=============

.. automodule:: my_project.my_module
    :members:


```

--------------------------------

### Add Deepnote Launch Button

Source: https://jupyter-book.readthedocs.io/v1/interactive/launchbuttons.html

Configure the URL for Deepnote to automatically insert launch buttons. These links only work for pages with the .ipynb extension.

```yaml
launch_buttons:
  colab_url: "https://deepnote.com"

```

--------------------------------

### Configure cell-level options for myst-nb

Source: https://jupyter-book.readthedocs.io/v1/explain/migration.html

Override default configuration at the cell level by placing options under the `mystnb` key. This example sets image dimensions, alt text, classes, and figure caption.

```python
```{code-cell} ipython3
---
mystnb:
  image:
    width: 200px
    alt: fun-fish
    classes: shadow bg-primary
  figure:
    caption: |
      Hey everyone its **party** time!
    name: fun-fish
---
from IPython.display import Image
Image("../images/fun-fish.png")
```

```

--------------------------------

### Jupyter Book CLI Usage

Source: https://jupyter-book.readthedocs.io/v1/reference/cli.html

The main entry point for the Jupyter Book command-line interface. Use this to manage book builds and other common functions.

```bash
jupyter-book [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### Numbering Equations with Dollar Math Syntax

Source: https://jupyter-book.readthedocs.io/v1/content/math.html

Alternatively, use dollar math syntax with a prefixed label to number equations. This method also requires valid label names that do not start with integers.

```markdown
$$
  w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
$$ (my_other_label)
```

--------------------------------

### Basic Card Structure

Source: https://jupyter-book.readthedocs.io/v1/content/components.html

Use the `card` directive to create content with a title, header, body, and footer. Header and footer sections are optional.

```rst
````{card} Card 1 title

Card header 1
^^^
Card body 1
+++
Card footer 1
````
```

--------------------------------

### Enable Definition Lists Extension

Source: https://jupyter-book.readthedocs.io/v1/content/content-blocks.html

To use definition lists, enable the `deflist` extension in your `_config.yml` file. This leverages the markdown-it-py deflist plugin.

```yaml
parse:
  myst_enable_extensions:
    # don't forget to list any other extensions you want enabled,
    # including those that are enabled by default!
    - deflist

```

--------------------------------

### Create and Display an Interactive Folium Map

Source: https://jupyter-book.readthedocs.io/v1/file-types/notebooks.html

This code generates an interactive map using the folium library. The code itself is retained in the book build, allowing for interactive map display. Ensure folium is installed.

```python
import folium
m = folium.Map(
    location=[45.372, -121.6972],
    zoom_start=12,
    tiles='Stamen Terrain'
)

folium.Marker(
    location=[45.3288, -121.6625],
    popup='Mt. Hood Meadows',
    icon=folium.Icon(icon='cloud')
).add_to(m)

folium.Marker(
    location=[45.3311, -121.7113],
    popup='Timberline Lodge',
    icon=folium.Icon(color='green')
).add_to(m)

folium.Marker(
    location=[45.3300, -121.6823],
    popup='Some Other Location',
    icon=folium.Icon(color='red', icon='info-sign')
).add_to(m)

m

```

--------------------------------

### Basic API Reference Generation with automodule

Source: https://jupyter-book.readthedocs.io/v1/advanced/developers.html

You can generate API documentation for an entire module by using the `automodule` directive in an `.rst` file. This directive extracts all docstrings from the specified module.

```APIDOC
API Reference
=============

.. automodule:: my_project.my_module
    :members:
```

--------------------------------

### Activate Utterances Comments in Jupyter Book

Source: https://jupyter-book.readthedocs.io/v1/interactive/comments/utterances.html

Add this configuration to your `_conf.yml` file to enable Utterances comments. Ensure the repository is public and the Utterances app is installed on the repo. The UI will only appear when hosted online.

```yaml
html:
  comments:
    utterances:
      repo: "github-org/github-repo"
```

--------------------------------

### Run Jupyter Book Tests with Tox

Source: https://jupyter-book.readthedocs.io/v1/contribute/intro.html

Use tox to run tests in isolated environments, bypassing the need for initial dependency installations. Specify the Python version and Sphinx version for the test environment.

```bash
>> tox -e py39-sphinx4 -- -m 'not requires_chrome and not requires_tex'
```

--------------------------------

### Reference Tables with ref

Source: https://jupyter-book.readthedocs.io/v1/reference/cheatsheet.html

Demonstrates referencing tables using the `ref` directive with custom text.

```rst
.. ref:: text <example-table>

This is an example.
```

--------------------------------

### MyST Markdown Code Cell with Scroll Output Tag

Source: https://jupyter-book.readthedocs.io/v1/content/code-outputs.html

In MyST Markdown, use the ':tags: [scroll-output]' option for the `code-cell` directive to make the output scrollable. This example demonstrates its usage with Python code.

```markdown
```{code-cell} ipython3
:tags: [scroll-output]

for ii in range(40):
    print(f"this is output line {ii}")
```

```

--------------------------------

### Block-level Mathematics with \begin{align*}

Source: https://jupyter-book.readthedocs.io/v1/file-types/markdown.html

Include block-level mathematics using LaTeX-style syntax with `\begin{align*}`. This requires the `amsmath` MyST extension to be enabled.

```latex
\begin{align*}
 y = its_{more}^{math}
\end{align*}
```
Tokens:
Raw