|
1 | 1 | # Developing this site |
2 | 2 |
|
3 | | -- create a Python environment and install the dependencies: |
| 3 | +This site uses MyST (Markedly Structured Text) via Jupyter Book to build documentation with dynamic content. |
| 4 | + |
| 5 | +## Setup |
| 6 | + |
| 7 | +Create a Python environment and install the dependencies: |
4 | 8 |
|
5 | 9 | ```bash |
6 | 10 | python -m venv .venv |
7 | | -source .venv/bin/activate |
| 11 | +source .venv/bin/activate # On Windows: .venv\Scripts\activate |
8 | 12 | pip install -r requirements.txt |
9 | 13 | ``` |
10 | 14 |
|
11 | | -- run the development server: |
| 15 | +## Building the Site |
| 16 | + |
| 17 | +### Development Server |
| 18 | + |
| 19 | +Run the live development server (auto-rebuilds on file changes): |
12 | 20 |
|
13 | 21 | ```bash |
14 | 22 | cd website |
15 | 23 | jupyter book start |
16 | 24 | ``` |
17 | 25 |
|
| 26 | +The site will be available at `http://localhost:3000`. |
| 27 | + |
| 28 | +### Build Static HTML |
| 29 | + |
| 30 | +Build the complete site: |
| 31 | + |
| 32 | +```bash |
| 33 | +cd website |
| 34 | +python generate_faq_cards.py # Generate FAQ cards |
| 35 | +jupyter book build |
| 36 | +``` |
| 37 | + |
| 38 | +Or using `myst` directly: |
| 39 | + |
| 40 | +```bash |
| 41 | +cd website |
| 42 | +python generate_faq_cards.py # Generate FAQ cards |
| 43 | +myst build |
| 44 | +``` |
| 45 | + |
| 46 | +**Important:** Run `generate_faq_cards.py` before building to regenerate the FAQ card grid from the individual FAQ files in `faq/`. |
| 47 | + |
| 48 | +### Quick Build (Development) |
| 49 | + |
| 50 | +For faster builds during development (if you haven't changed FAQ content): |
| 51 | + |
| 52 | +```bash |
| 53 | +cd website |
| 54 | +jupyter book build |
| 55 | +``` |
| 56 | + |
| 57 | +## Project Structure |
| 58 | + |
| 59 | +``` |
| 60 | +website/ |
| 61 | +├── myst.yml # MyST configuration and table of contents |
| 62 | +├── *.md # Main content pages |
| 63 | +├── faq/ # Individual FAQ pages (auto-listed) |
| 64 | +│ └── *.md |
| 65 | +├── images/ # Static assets |
| 66 | +└── _build/ # Generated output (not committed) |
| 67 | + └── html/ |
| 68 | +``` |
| 69 | + |
| 70 | +## Dynamic Content |
| 71 | + |
| 72 | +The FAQ landing page (`faq.md`) uses a preprocessing script to: |
| 73 | +- Automatically scan all files in `faq/` directory |
| 74 | +- Parse frontmatter (title, tags) from each FAQ |
| 75 | +- Generate `faq-include.md` with a responsive card grid layout |
| 76 | +- Update automatically when FAQ files are added/removed |
| 77 | + |
| 78 | +To add a new FAQ: |
| 79 | +1. Create a new `.md` file in `website/faq/` |
| 80 | +2. Add frontmatter with `title` and `tags` |
| 81 | +3. Add the file to `myst.yml` under `faq.md` children |
| 82 | +4. Run `python generate_faq_cards.py` to regenerate cards |
| 83 | +5. Rebuild the site |
| 84 | + |
| 85 | +## Testing |
| 86 | + |
| 87 | +### Manual Testing |
| 88 | +Generate FAQ cards:** |
| 89 | + ```bash |
| 90 | + cd website |
| 91 | + python generate_faq_cards.py |
| 92 | + ``` |
| 93 | + |
| 94 | +2. **Local build test:** |
| 95 | + ```bash |
| 96 | + cd website |
| 97 | + jupyter book build |
| 98 | + ``` |
| 99 | + |
| 100 | +3. **Check for errors:** |
| 101 | + - Look for build errors in the terminal output |
| 102 | + - Check `_build/html/` directory was created |
| 103 | + - Verify `faq-include.md` was generated and contains card markup |
| 104 | + |
| 105 | +4. **Visual testing:** |
| 106 | + ```bash |
| 107 | + cd website |
| 108 | + jupyter book start |
| 109 | + ``` |
| 110 | + Navigate to `/faq` and verify: |
| 111 | + - All FAQ cards appear |
| 112 | + - Cards are clickable and link to correct pages |
| 113 | + - Card layout is responsive |
| 114 | + |
| 115 | +### Automated Testing (CI/CD) |
| 116 | + |
| 117 | +The GitHub Actions workflow automatically: |
| 118 | +- Installs dependencies from `requirements.txt` |
| 119 | +- Run `python generate_faq_cards.py` from the `website/` directory |
| 120 | +- Check that `faq-include.md` was generated |
| 121 | +- Verify FAQ files are in `website/faq/` and listed in `myst.yml` |
| 122 | + |
| 123 | +**Build errors:** |
| 124 | +- Check YAML syntax in FAQ file frontmatter |
| 125 | +- Ensure all required packages are in `requirements.txt` |
| 126 | +- Verify frontmatter YAML is valid in all `.md` files |
| 127 | +- Check that `faq-include.md` contains valid MyST card syntax |
| 128 | + |
| 129 | +**Links broken:** |
| 130 | +- Use relative paths with `/` prefix: `/faq/page-name` |
| 131 | +- Match filenames exactly (case-sensitive) |
| 132 | +- Check TOC entries in `myst.yml` |
| 133 | + |
| 134 | +## AI Assistant Instructions |
| 135 | + |
| 136 | +When working with this codebase: |
| 137 | +- Run `python generate_faq_cards.py` before building if FAQ files changed |
| 138 | +- FAQ pages must be added to both `website/faq/` AND `myst.yml` TOC |
| 139 | +- Use the MyST instructions file at `.github/instructions/myst.instructions.md` |
| 140 | +- Test builds locally before committing |
| 141 | +- Verify the GitHub Actions workflow passes |
| 142 | +- The preprocessing script must be run before each build when FAQ content chang |
| 143 | +## AI Assistant Instructions |
| 144 | + |
| 145 | +When working with this codebase: |
| 146 | +- Always build with `--execute` flag when FAQ or dynamic content changes |
| 147 | +- FAQ pages must be added to both `website/faq/` AND `myst.yml` TOC |
| 148 | +- Use the MyST instructions file at `.github/instructions/myst.instructions.md` |
| 149 | +- Test builds locally before committing |
| 150 | +- Verify the GitHub Actions workflow passes |
| 151 | + |
| 152 | +## Additional Resources |
| 153 | + |
| 154 | +- [MyST Documentation](https://mystmd.org/guide) |
| 155 | +- [Jupyter Book Documentation](https://jupyterbook.org/) |
| 156 | +- [MyST Instructions](.github/instructions/myst.instructions.md) |
| 157 | + |
0 commit comments