Jupyter Book Training Template

A customizable template for creating training materials on DesignSafe using Jupyter Book.

Maintained by Krishna Kumar, University of Texas at Austin

Features

• Pre-configured Jupyter Book structure
• GitHub Pages integration
• DesignSafe-specific workflows
• Easy content authoring with Markdown/Jupyter Notebooks
• Customizable table of contents
• "Open in DesignSafe" button integration

Quick Start

1. Fork the Repository
   Fork original repository

2. Enable GitHub Pages
   Go to Settings → Pages → Set source to gh-pages branch

3. Clone Your Fork

   git clone https://github.com/DesignSafe-CI/training-template.git
   

Configuration

1. Basic Settings (_config.yml)

title: "Your Training Title"
author: "Your Name"
url: "https://your-username.github.io/training-template"

2. Table of Contents (_toc.yml)

format: jb-book
root: intro
chapters:
  - file: path/to/chapter1
  - file: path/to/chapter2

3. DesignSafe Integration

To add "Open in DesignSafe" buttons:

• Upload notebooks to Community Data >> Training
• Update notebook URLs to:

Adding Content

Supported formats:

• 📝 Markdown (.md)

• 📓 Jupyter Notebooks (.ipynb)

• 🔄 MyST Markdown

Organization tips:

├── content/
│   ├── intro.md
│   ├── chapter1/
│   │   ├── notebook.ipynb
│   │   └── images/
├── _toc.yml
└── _config.yml

Building Locally

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Build book
jupyter-book build .

Serve built content (optional)

python -m http.server --directory _build/html

Deployment

Commit changes:

    git add .
    git commit -m "Update content"
    git push origin main

GitHub Actions will automatically:

- Build book

- Deploy to GitHub Pages

- View at: https://<your-username>.github.io/training-template

License

BSD 3-Clause License - See LICENSE

Jupyter example templates

Exercise:

Solution: