DesignSafe training template

Author: kks32

README.md

@@ -1,30 +1,118 @@
-# Training Template
+# Jupyter Book Training Template
 
-> Krishna Kumar, UT Austin
+[![GitHub Pages](https://img.shields.io/badge/GitHub-Pages-blue?logo=github)](https://img.shields.io/badge/GitHub-Pages-blue?logo=github)
+[![Jupyter Book](https://img.shields.io/badge/Powered%20by-Jupyter%20Book-orange)](https://jupyterbook.org)
 
-- Template for DesignSafe training built using [Jupyter Book](https://jupyterbook.org/en/stable/intro.html).
-- Fork this [repo](https://github.com/DesignSafe-CI/training-template)
-- To add `Open In DesignSafe` in Jupyter Notebooks copy the jupyter notebook to Community Data and then point the URL to the folder in Community Data `https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/`
-- The repo will automatically build a website using GitHub pages
+A customizable template for creating training materials on DesignSafe using [Jupyter Book](https://jupyterbook.org/en/stable/intro.html).
 
-## Template edits
-- `_config.yml` Edit for title, author and URL
-- `_toc.yml` Set-up the table of contents
-- You can write markdown and Jupyter Notebooks and add to table of contents `_toc.yml`
+> Maintained by Krishna Kumar, University of Texas at Austin
 
-## Build locally
+## 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](https://github.com/DesignSafe-CI/training-template/fork)
+
+2. **Enable GitHub Pages**  
+   Go to Settings → Pages → Set source to `gh-pages` branch
+
+3. **Clone Your Fork**
+   ```bash
+   git clone https://github.com/DesignSafe-CI/training-template.git
+
+## Configuration
+1. Basic Settings (`_config.yml`)
+
+```yaml
+title: "Your Training Title"
+author: "Your Name"
+url: "https://your-username.github.io/training-template"
 ```
-# Create a virtual env
-virtualenv env
-source env/bin/activate
-# Install required packages
-pip3 install -r requirements.txt
-# Build your book
+
+2. Table of Contents (`_toc.yml`)
+```yaml
+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:
+[![Try on DesignSafe](https://raw.githubusercontent.com/DesignSafe-CI/training-template/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Training/template/01-template-exercise.ipynb)
+
+## 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
+```bash
+# 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 .
 ```
 
-This will create a `_build/html` directory with all the files. Open the `index.html` file to start
+## Serve built content (optional)
+
+> python -m http.server --directory _build/html
+
+## Deployment
+
+Commit changes:
+```bash
+    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](LICENSE.md)
 
 ## Jupyter example templates