This repository is a template for creating a GeoSMART use case book. These use the Jupyter Book format, documentation for which can be found here. Jupyter Book websites are built using Jupyter Notebook (.ipynb) and markdown (.md) files.
- On the top right of the page, click Use this template and then Create a new repository
- This should take you to a new page titled Create a new repository
- Double check that the dropdown menu below Repository template says either geo-smart/simple-template or geo-smart/use_case_template
- Leave the box unchecked for Include all branches
- For Owner select your github user account, or another organization to create the new repository under
- Give your use case repository a name under Repository name
- Add a short Description
- Select the option for Public
- Finally, click Create repository
With your new use case repository, you can choose to clone the repository to work on your local system, or edit configuration files within the web browser.
In the book directory, update the _config.yml file with some basic information:
title:author:repository:url:
You can leave all the other configuration options unchanged for now.
In your repository Settings (gear icon on top of your repository's page), go to the Pages section.
Under the Build and deployment settings, click on the dropdown menu below Source and select GitHub Actions.
Your JupyterBook is now configured to build and deploy following each new commit you make to the repository. Note: The file that runs the build and deploy action is located at /.github/workflows/publish.yml but you do not need to make any changes to this file.
If a commit fails to produce a new version of the Book, go to the Actions tab on the GitHub repository page to read the action logs and diagnose errors (failed actions will have a red icon with an X next to them).
Now that you have completed the creation, configuration, and setup steps, you can begin adding your use case content to the JupyterBook.
- update the
environment.ymlfile to include any packages that your use case code will require (the Jupyter Notebooks are executed with this environment each time the GitHub action that builds and deploys the website is ran). book/intro.mdis where you can add content for your Jupyter Book's home pagebook/chapters/will contain markdown or Jupyter Notebook files, the main content of your use case Jupyter Book- This template contains placeholder Jupyter Notebook files to illustrate a recommended way to organize your content. You can edit each of these files to add your content following the suggested organization, or remove and replace the placeholder files with your own content.
- Update the table of contents file (
/book/_toc.yml) to organize page navigation through the website- Jupyter Books organize content by Parts, and within each part are Chapters. A chapter consists of a single Jupyter Notebook or markdown file.
- You create and title parts in the table of contents file with
- caption: Part Title - Under each part you can list one or more chapters using
- file: chapters/my_filewhich points to eithermy_file.ipynbormy_file.md
We recommend that you refer to the JupyterBook documentation on the following topics to help your organize your content:
- Structure and Configure the table of contents,
book/_toc.yml - Markdown and Jupyter Notebook files for the content in
book/chapters/ - Embedding images and figures from
book/img/, and writing inline math and equations - Links and references, special content blocks, and more ways to structure chunks of content