Skip to content

CLAUDE.md

Latest commit

 

History

History
171 lines (129 loc) · 7.56 KB

CLAUDE.md

File metadata and controls

171 lines (129 loc) · 7.56 KB

Bactopia Documentation Site

Docusaurus 3.10 site for Bactopia, a bacterial genomics workflow.

Architecture

Five content sections with separate sidebar files, each registered as a Docusaurus docs plugin:

Directory Route Base Sidebar File
docs/ / sidebars.ts
bactopia-tools/ /bactopia-tools sidebars-bactopia-tools.ts
bactopia-pipelines/ /bactopia-pipelines sidebars-bactopia-pipelines.ts
developers/ /developers sidebars-developers.ts
impact/ /impact-and-outreach sidebars-impact.ts

Plus blog at /blog (configured in preset-classic).

Versioned snapshots of older releases are stored as orphan git branches (snapshot/vX.Y.Z). See the Version Snapshots section for details.

Auto-generation Pipeline

Most content under bactopia-tools/, bactopia-pipelines/, developers/, and impact/ is auto-generated from the bactopia source repo.

Pipeline: Python scripts in bin/ read data sources, render pages via Jinja2 templates in templates/, orchestrated by Makefile.

Scripts in bin/:

Script Input Output
parse-bactopia.py bactopia repo data/bactopia.json
parse-cli.py bactopia-py (Click introspection) data/cli.json
generate-workflows.py data/bactopia.json bactopia-tools/*.mdx, bactopia-pipelines/*.mdx
generate-subworkflows.py data/bactopia.json developers/subworkflows/*.mdx
generate-modules.py data/bactopia.json developers/modules/*.mdx
generate-cli.py data/cli.json developers/cli/*.mdx
generate-citations.py data/citations.yml impact/citations.md
generate-acknowledgements.py data/bactopia.json impact/acknowledgements.md
generate-enhancements.py data/contributions.yml impact/enhancements.md
generate-skills.py bactopia repo SKILL.md files JSON to stdout (used by skills docs skill)
generate-llms-catalog.py all content directories static/llms.txt, static/catalog.json
update-citations.py external sources data/citations.yml
generator_utils.py -- shared helpers (escape_mdx, create_jinja_env, etc.)

Data files in data/:

  • bactopia.json -- parsed bactopia repo metadata (generated by make parse)
  • cli.json -- parsed CLI metadata (generated by make parse-cli)
  • citations.yml -- citation database (committed)
  • contributions.yml -- contribution records (committed)

Environment

  • Node.js >= 18 for Docusaurus
  • Python via bactopia-dev conda env for generation scripts
  • BACTOPIA_DEV_PYTHON defaults to /home/rpetit3/.conda/envs/bactopia-dev/bin/python

Commands

Command Purpose
npm start Dev server (port 8000, host 0.0.0.0)
npm run build Production build to build/
npm run serve Serve production build locally
npm run typecheck TypeScript type checking
npm run clear Clear Docusaurus cache
make generate BACTOPIA_REPO=../bactopia Generate all docs from bactopia source
make llms-catalog Generate static/llms.txt and static/catalog.json
make snapshot-list Show all version snapshots and file budget
make snapshot-add VERSION=vX.Y.Z FILES=N Register a new active snapshot
make snapshot-deactivate VERSION=vX.Y.Z Remove a version from the active deploy
make snapshot-activate VERSION=vX.Y.Z Restore a version to the active deploy

LLM Index Files

static/llms.txt and static/catalog.json are machine-readable indexes of the documentation, generated by bin/generate-llms-catalog.py (or make llms-catalog).

  • llms.txt -- follows the llms.txt standard. Markdown file with H1 site title, blockquote tagline, H2 per section, and - [Title](URL): description entries per page. Served at /llms.txt.
  • catalog.json -- structured JSON with site metadata, section hierarchy, and per-page metadata (title, description, tags, URL path, source file). Served at /catalog.json.

Both are committed and should be regenerated when content pages are added, removed, or renamed.

Frontmatter fields:

  • title -- required
  • description -- required (quoted string or block scalar)
  • tags -- optional (list of lowercase-hyphenated strings)
  • sidebar_position -- optional (integer)
  • slug -- optional (only on index pages)

MDX files use React components from src/components/ (CardGrid, Card, Icon, etc.). Characters <, >, {, } must be escaped in MDX body text (use escape_mdx from generator_utils).

Generator Script Pattern

Each generator script in bin/ follows this structure:

  • argparse for inputs and output paths
  • Load data from JSON/YAML
  • Use create_jinja_env() with templates, or direct string generation
  • Write output with Path.write_text()
  • Print summary to stdout

Version Snapshots

Each release gets a static snapshot so users can access older docs. Snapshots are stored as orphan git branches (snapshot/vX.Y.Z) and assembled into the deploy output at build time.

  • / always serves the current version (label set in docusaurus.config.ts under versions.current.label)
  • /vX.Y.Z/ serves active snapshots (built with baseUrl: '/vX.Y.Z/' and an announcement banner)
  • snapshots.json is the registry of all versions; the active flag controls deploy inclusion
  • Cloudflare Pages has a 20,000 file limit; use make snapshot-list to check remaining budget

Creating a snapshot (new Bactopia release)

  1. Go to GitHub Actions and run the Create Version Snapshot workflow
    • version: the version tag (e.g., v4.0.0)
    • bactopia_ref: the bactopia repo ref to build from (e.g., v4.0.0)
  2. The workflow builds the site with the version banner, pushes an orphan branch snapshot/vX.Y.Z, and updates snapshots.json on master
  3. The deploy workflow runs automatically, assembling the snapshot into the build output

Updating the current version label

After creating a snapshot for the outgoing version, update the label in docusaurus.config.ts:

versions: {
  current: {
    label: 'v4.1.0',  // update to new version
    ...
  },
},

Rebuilding a snapshot

Re-run the Create Version Snapshot workflow with the same version. The orphan branch is force-pushed with the new build output.

Dropping old versions (approaching 20k file limit)

make snapshot-list                       # check budget
make snapshot-deactivate VERSION=v2.1.0  # remove from active deploy
# commit and push snapshots.json

The version moves to "Archived Versions" in the dropdown (links to the GitHub branch). The branch is preserved and can be re-activated with make snapshot-activate.

Key files

File Purpose
snapshots.json Version registry (all versions, active flag, file counts)
docusaurus.config.ts DOCS_VERSION env var controls banner and baseUrl
.github/workflows/create-snapshot.yml Builds snapshot and pushes orphan branch
.github/workflows/deploy.yml Assembles active snapshots at deploy time

Skills

Claude Code skills live in .claude/skills/<skill-name>/SKILL.md with YAML frontmatter (name, description) followed by markdown instructions.