|
| 1 | +# Bactopia Documentation Site |
| 2 | + |
| 3 | +Docusaurus 3.10 site for [Bactopia](https://github.com/bactopia/bactopia), a bacterial genomics workflow. |
| 4 | +This file follows the [agents.md](https://agents.md/) convention; `CLAUDE.md` is an import stub. |
| 5 | + |
| 6 | +- Site: https://bactopia.io |
| 7 | +- Repo: bactopia/bactopia.github.io (deployed to Cloudflare Pages) |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +Five content sections with separate sidebar files, each registered as a Docusaurus docs plugin: |
| 12 | + |
| 13 | +| Directory | Route Base | Sidebar File | |
| 14 | +|----------------------|----------------------|--------------------------------| |
| 15 | +| `docs/` | `/` | `sidebars.ts` | |
| 16 | +| `bactopia-tools/` | `/bactopia-tools` | `sidebars-bactopia-tools.ts` | |
| 17 | +| `bactopia-pipelines/`| `/bactopia-pipelines`| `sidebars-bactopia-pipelines.ts`| |
| 18 | +| `developers/` | `/developers` | `sidebars-developers.ts` | |
| 19 | +| `impact/` | `/impact-and-outreach`| `sidebars-impact.ts` | |
| 20 | + |
| 21 | +Plus blog at `/blog` (configured in preset-classic). |
| 22 | + |
| 23 | +Versioned snapshots of older releases are stored as orphan git branches (`snapshot/vX.Y.Z`). |
| 24 | +See the [Version Snapshots](#version-snapshots) section for details. |
| 25 | + |
| 26 | +## Auto-generation Pipeline |
| 27 | + |
| 28 | +Most content under `bactopia-tools/`, `bactopia-pipelines/`, `developers/`, and `impact/` is |
| 29 | +auto-generated from the [bactopia](https://github.com/bactopia/bactopia) source repo. |
| 30 | + |
| 31 | +Pipeline: Python scripts in `bin/` read data sources, render pages via Jinja2 templates in `templates/`, |
| 32 | +orchestrated by `Makefile`. |
| 33 | + |
| 34 | +Scripts in `bin/`: |
| 35 | + |
| 36 | +| Script | Input | Output | |
| 37 | +|--------|-------|--------| |
| 38 | +| `parse-bactopia.py` | bactopia repo | `data/bactopia.json` | |
| 39 | +| `parse-cli.py` | bactopia-py (Click introspection) | `data/cli.json` | |
| 40 | +| `generate-workflows.py` | `data/bactopia.json` | `bactopia-tools/*.mdx`, `bactopia-pipelines/*.mdx` | |
| 41 | +| `generate-tools-index.py` | `data/tool-categories.yml` | `bactopia-tools/index.mdx` | |
| 42 | +| `generate-subworkflows.py` | `data/bactopia.json` | `developers/subworkflows/*.mdx` | |
| 43 | +| `generate-modules.py` | `data/bactopia.json` | `developers/modules/*.mdx` | |
| 44 | +| `generate-cli.py` | `data/cli.json` | `developers/cli/*.mdx` | |
| 45 | +| `generate-citations.py` | `data/citations.yml` | `impact/citations.md` | |
| 46 | +| `generate-acknowledgements.py` | `data/bactopia.json` | `impact/acknowledgements.md` | |
| 47 | +| `generate-enhancements.py` | `data/contributions.yml` | `impact/enhancements.md` | |
| 48 | +| `generate-skills.py` | bactopia repo SKILL.md files | JSON to stdout (used by skills docs skill) | |
| 49 | +| `generate-llms-catalog.py` | all content directories | `static/llms.txt`, `static/catalog.json` | |
| 50 | +| `update-citations.py` | external sources | `data/citations.yml` | |
| 51 | +| `generator_utils.py` | -- | shared helpers (escape_mdx, create_jinja_env, etc.) | |
| 52 | + |
| 53 | +Data files in `data/`: |
| 54 | +- `bactopia.json` -- parsed bactopia repo metadata (generated by `make parse`) |
| 55 | +- `cli.json` -- parsed CLI metadata (generated by `make parse-cli`) |
| 56 | +- `citations.yml` -- citation database (committed) |
| 57 | +- `contributions.yml` -- contribution records (committed) |
| 58 | + |
| 59 | +## Environment |
| 60 | + |
| 61 | +- Use the `bactopia-dev` conda environment -- it provides Node.js (>= 18) for |
| 62 | + Docusaurus and Python with the packages in `requirements.txt` for generation scripts |
| 63 | +- Prepend it to PATH: `export PATH="$HOME/.conda/envs/bactopia-dev/bin:$PATH"` |
| 64 | +- `BACTOPIA_DEV_PYTHON` in the `Makefile` points at this environment's Python |
| 65 | + |
| 66 | +## Commands |
| 67 | + |
| 68 | +| Command | Purpose | |
| 69 | +|---------|---------| |
| 70 | +| `npm start` | Dev server (port 8000, host 0.0.0.0) | |
| 71 | +| `npm run build` | Production build to `build/` | |
| 72 | +| `npm run serve` | Serve production build locally | |
| 73 | +| `npm run typecheck` | TypeScript type checking | |
| 74 | +| `npm run clear` | Clear Docusaurus cache | |
| 75 | +| `make generate BACTOPIA_REPO=../bactopia` | Generate all docs from bactopia source | |
| 76 | +| `make llms-catalog` | Generate `static/llms.txt` and `static/catalog.json` | |
| 77 | +| `make snapshot-list` | Show all version snapshots and file budget | |
| 78 | +| `make snapshot-add VERSION=vX.Y.Z FILES=N` | Register a new active snapshot | |
| 79 | +| `make snapshot-deactivate VERSION=vX.Y.Z` | Remove a version from the active deploy | |
| 80 | +| `make snapshot-activate VERSION=vX.Y.Z` | Restore a version to the active deploy | |
| 81 | + |
| 82 | +## LLM Index Files |
| 83 | + |
| 84 | +`static/llms.txt` and `static/catalog.json` are machine-readable indexes of the documentation, |
| 85 | +generated by `bin/generate-llms-catalog.py` (or `make llms-catalog`). |
| 86 | + |
| 87 | +- `llms.txt` -- follows the [llms.txt standard](https://llmstxt.org/). Markdown file with H1 site |
| 88 | + title, blockquote tagline, H2 per section, and `- [Title](URL): description` entries per page. |
| 89 | + Served at `/llms.txt`. |
| 90 | +- `catalog.json` -- structured JSON with site metadata, section hierarchy, and per-page metadata |
| 91 | + (title, description, tags, URL path, source file). Served at `/catalog.json`. |
| 92 | + |
| 93 | +Both are committed and should be regenerated when content pages are added, removed, or renamed. |
| 94 | + |
| 95 | +Frontmatter fields: |
| 96 | +- `title` -- required |
| 97 | +- `description` -- required (quoted string or block scalar) |
| 98 | +- `tags` -- optional (list of lowercase-hyphenated strings) |
| 99 | +- `sidebar_position` -- optional (integer) |
| 100 | +- `slug` -- optional (only on index pages) |
| 101 | + |
| 102 | +MDX files use React components from `src/components/` (CardGrid, Card, Icon, etc.). |
| 103 | +Characters `<`, `>`, `{`, `}` must be escaped in MDX body text (use `escape_mdx` from `generator_utils`). |
| 104 | + |
| 105 | +## Generator Script Pattern |
| 106 | + |
| 107 | +Each generator script in `bin/` follows this structure: |
| 108 | +- `argparse` for inputs and output paths |
| 109 | +- Load data from JSON/YAML |
| 110 | +- Use `create_jinja_env()` with templates, or direct string generation |
| 111 | +- Write output with `Path.write_text()` |
| 112 | +- Print summary to stdout |
| 113 | + |
| 114 | +## Version Snapshots |
| 115 | + |
| 116 | +Each release gets a static snapshot so users can access older docs. Snapshots are stored as |
| 117 | +orphan git branches (`snapshot/vX.Y.Z`) and assembled into the deploy output at build time. |
| 118 | + |
| 119 | +- `/` always serves the current version (label set in `docusaurus.config.ts` under `versions.current.label`) |
| 120 | +- `/vX.Y.Z/` serves active snapshots (built with `baseUrl: '/vX.Y.Z/'` and an announcement banner) |
| 121 | +- `snapshots.json` is the registry of all versions; the `active` flag controls deploy inclusion |
| 122 | +- Cloudflare Pages has a 20,000 file limit; use `make snapshot-list` to check remaining budget |
| 123 | + |
| 124 | +### Creating a snapshot (new Bactopia release) |
| 125 | + |
| 126 | +1. Go to GitHub Actions and run the **Create Version Snapshot** workflow |
| 127 | + - `version`: the version tag (e.g., `v4.0.0`) |
| 128 | + - `bactopia_ref`: the bactopia repo ref to build from (e.g., `v4.0.0`) |
| 129 | +2. The workflow builds the site with the version banner, pushes an orphan branch |
| 130 | + `snapshot/vX.Y.Z`, and updates `snapshots.json` on master |
| 131 | +3. The deploy workflow runs automatically, assembling the snapshot into the build output |
| 132 | + |
| 133 | +### Updating the current version label |
| 134 | + |
| 135 | +After creating a snapshot for the outgoing version, update the label in `docusaurus.config.ts`: |
| 136 | + |
| 137 | +```typescript |
| 138 | +versions: { |
| 139 | + current: { |
| 140 | + label: 'v4.1.0', // update to new version |
| 141 | + ... |
| 142 | + }, |
| 143 | +}, |
| 144 | +``` |
| 145 | + |
| 146 | +### Rebuilding a snapshot |
| 147 | + |
| 148 | +Re-run the **Create Version Snapshot** workflow with the same version. The orphan branch |
| 149 | +is force-pushed with the new build output. |
| 150 | + |
| 151 | +### Dropping old versions (approaching 20k file limit) |
| 152 | + |
| 153 | +```bash |
| 154 | +make snapshot-list # check budget |
| 155 | +make snapshot-deactivate VERSION=v2.1.0 # remove from active deploy |
| 156 | +# commit and push snapshots.json |
| 157 | +``` |
| 158 | + |
| 159 | +The version moves to "Archived Versions" in the dropdown (links to the GitHub branch). |
| 160 | +The branch is preserved and can be re-activated with `make snapshot-activate`. |
| 161 | + |
| 162 | +### Key files |
| 163 | + |
| 164 | +| File | Purpose | |
| 165 | +|------|---------| |
| 166 | +| `snapshots.json` | Version registry (all versions, active flag, file counts) | |
| 167 | +| `docusaurus.config.ts` | `DOCS_VERSION` env var controls banner and `baseUrl` | |
| 168 | +| `.github/workflows/create-snapshot.yml` | Builds snapshot and pushes orphan branch | |
| 169 | +| `.github/workflows/deploy.yml` | Assembles active snapshots at deploy time | |
| 170 | + |
| 171 | +## Skills |
| 172 | + |
| 173 | +Agent skills live in `.agents/skills/<skill-name>/SKILL.md` with YAML frontmatter |
| 174 | +(`name`, `description`) followed by markdown instructions. `.claude/skills` is a symlink |
| 175 | +to `.agents/skills/` for Claude Code compatibility. |
0 commit comments