Markup language is similar to Hypertext Markup Language (HTML) made of Markup tags, and it consists of the opening tag and closing tag. In this tutorial, you can see the same result obtained by using Markup tags, and also the Markdown syntax which is supported by Jupyter Notebook. Tutorial on How to Install Jupyter on Ubuntu 16.04. Jupyter Notebook is an open source, interactive web app that you can use to create interactive documents.

• Jupyter Markdown New Line
• Jupyter Markup Language
• Jupyter Markdown Cheat Sheet

Welcome to the jupyter-book repository! We’re excited you’re here and want to contribute. ✨

Development guidelines¶

For information about development conventions, practices, and infrastructure, please see the executablebooks/ development guidelines.

Documentation guidelines¶

The documentation of Jupyter Book is inspired by the Divio Documentation Framework.This separates documentation into four main areas:

• Tutorials are step-by-step guides that are learning-oriented.They give the learner a feel for how a tool works, and get them excited about learning more.Tutorials live in a dedicated section of the documentation.

• How-To guides are shorter guides that tell the reader how to do something.They assume more background knowledge of Jupyter Book (often, that they have read the tutorial).They are focused on “doing things” rather than long explanations.How-To guides make up most of Jupyter Book’s documentation, and are separated into sections for various topics.

• Reference documentation describes Jupyter Book’s structure and functionality in a complete sense.It is more programmatic, less narrative, and more interested in covering all configuration and options in Jupyter Book rather than describing how and when to use them.Jupyter Book has a reference section after our topic sections.In addition, it has an organization-level reference section just underneath.

• Explanations are higher-level discussions about topics and concepts related to Jupyter Book.They are less focused on doing things, and more focused on gaining a conceptual framework for how Jupyter Book works.Jupyter Book currently has no dedicated explanation section, but welcomes the addition of explanatory content and potentially a dedicated section.

These four areas are not strict rules for the Jupyter Book documentation, but should serve as inspiration in deciding what to document, and where.Any contributions to the documentation that fall within this framework (e.g., adding a new tutorial, adding a How To section) are most-welcome!

Getting started¶

To get started with Jupyter Book’s codebase, take the following steps:

Clone and install the package¶

Next, install:

This will install Jupyter Book locally, along with the packages needed to test itas well as packages for ensuring code style.

Install the pre-commit hooks¶

Jupyter Book uses pre-commit to ensure code styleand quality before a commit is made. This ensures that the look and feel of Jupyter Bookremains consistent over time and across developers. pre-commit is installed when youinstall Jupyter Book with pipinstall-e.[code_style].

To enable pre-commit for your clone, run the following from the repository root:

From now on, when you make a commit to Jupyter Book, pre-commit will ensure that yourcode looks correct according to a few checks.

Run the tests¶

For code tests, Jupyter Book uses pytest).You may run all the tests, or only ones that do not require additional installations, with the following command:

You can alternatively use tox to run the tests in multiple isolated environments, and also without the need for the initial dependencies install (see the tox.ini file for available test environments and further explanation):

Either will run the Jupyter Book test suite, except for the PDF tests.This is because running the PDF generation tests requires a full LaTeX environment, which you may not have set up.

Note

Jupyter Book makes use of pytest-xdist for running tests in parallel.You can take advantage of this by running tests with the -n argument followed by the number of CPUs you would like to use.For example: pytest-n4. This makes the tests run much faster.

To test PDF generation¶

If you’d like to test (or try out) the generation of PDFs, take the following steps:

To generate PDFs via HTML, make sure you install Jupyter Book withpipinstall-e.[pdfhtml]. This will install pyppeteer,which runs a headless chrome session to convert your book to PDF. Next, followthe installation instructions at Build a PDF from your book HTML. You should then be able to build yourbook’s PDF through HTML.

To generate PDFs via LaTeX, make sure you install a working LaTeX distribution locally.Do so by following the instructions in Build a PDF using LaTeX.

If you have installed the requirements for both HTML and LaTeX generation, you shouldbe able to run the full test suite with pytest.

GitHub Actions Artifacts¶

A test included for each pull request is to build the docs as PDF files using both thepdfhtml and pdflatex writers. These tests build the pdf file and then save them as artifactsattached to each workflow run.

These pdf files can be retrieved from the top right corner of a workflow run.

Repository structure of Jupyter Book¶

This section covers the general structure of theJupyter Book repository, andexplains which pieces are where.

The Jupyter Book repository contains two main pieces:

Jupyter Markdown New Line

MyST Markdown¶

Jupyter Book supports an extended version of Jupyter Markdown called “MyST Markdown”.For information about the MyST syntax and how to use it, seethe MyST-Parser documentation.

The command-line tool and Python package¶

This is used to help create and build books.It can be found at ./jupyter_book.

• The commands/ folder has the CLI. This is the interface for users to create, build and control their book via the command-line.

• The sphinx.py module builds the books.

• The yaml.py module handles configuration.

• The toc.py module prepares the table of contents.

The other modules handle more specific functionality in Jupyter Book - see theirmodule docstrings for more information.

The template Jupyter Book¶

Jupyter Book comes bundled with a small template book to show off content. This canbe immediately built with jupyter-bookbuild.It can be found at jupyter_book/book_template.

An example¶

Here are a few examples of how this code gets used to help you get started.

• when somebody runs jupyter-bookcreatemybook/, the create.py module is used to generate an empty template using the template in jupyter_book/book_template/.

• when somebody runs jupyter-bookbuildmybook/, the build.py module loops through your page content files,and uses the page/ module to convert each one into HTML and places it in mybook/_build.

Jupyter Markup Language

Hopefully this explanation gets you situated and helps you understand how the pieces all fit together.If you have any questions, feel free to open an issue asking for help!

Other major tools in the Jupyter Book stack¶

Jupyter Book depends on a collection of open source tools in the Python / Sphinxecosystem. These tools do much of the heavy lifting of Jupyter Book, and are wheremany improvements and changes will need to be. Here is a list of the major tools andwhat kinds of functionality they support:

Jupyter Markdown Cheat Sheet

• The Sphinx Documentation engine is used to build book outputs. This relieson a number of extensions that are developed by Jupyter Book.

• MyST Markdown is parsed into Sphinx bythe MyST-Parser.

• The MyST-NB package parses Jupyter Notebooks into Sphinx and alsocontrols some parts of notebook execution.It also allows inserting code outputs into content.

• Jupyter-Cache manages the execution and cacheing of notebook content atbuild time. It is controlled by MyST-NB.

• The Sphinx Book Theme defines the look and feel of Jupyter Book, and iswhere most of the CSS rules are defined.