Modify the Content

Anatomy of a Jupyter Book

Three things are needed for building a Jupyter Book:

Important

jupyter-book build builds Jupyter Book off of a content source:

  • Jupyter Notebook (.ipynb) and

  • Markdown (.md) files.

Supported files

For the full list of the available file formats go to the JupyterBook.

Jupyter Notebook

Markdown also easily integrates into Jupyter Notebook files . For more refer to the MyST.

Use the files presented here as the template of your Jupyter Book, as they will reduce your content development time.

  • The .ipynb and the .md content files are to be located in the root, or a subfolder, of the cloned data-science-for-esm, and specified accordingly in the _toc.yml[1].

  • Both the _config.yml, as well as the _toc.yml, are to remain in the root of the data-science-for-esm folder.

  • The website logo, as well as the other figures, can be placed in the data-science-for-esm/_images/ folder.

Modify the Content#

  • Modify the .ipynb and the .md files as seen fit. They are the core-content.

  • When changing the images and modifying the content files, the referencing throughout the .md and the .ipynb files needs changing as well[2].

To have the content changes reflected in the website, there is a chain of git to-do commands:

# make changes to the content
git status
git add .
git commit -m 'new changes applied'
git push origin content_branch

  • The metadata of the website, such as the author, logo, and other relevant GitHub and Google Colab links, are to be defined in the _config.yml[3]:

    • Use the already provided _toc.yml and _config.yml files as a template, and follow their structure.

  • In the data-science-for-esm/_toc.yml file, a sequence of files to be included in the Jupyter Book, and the GitHub Page, is defined, and further used by the jupyter-build book command.

    • Detailed customization instructions on both the _toc.yml and the _config.yml are provided in link and link. ⇶ MUST READ!

After a successful run, the TOC will be displayed in the left-side menu of the website.