Skip to content

AGENTS.md

Latest commit

 

History

History
195 lines (149 loc) · 8.47 KB

AGENTS.md

File metadata and controls

195 lines (149 loc) · 8.47 KB
Raw

Bactopia Documentation Site

Docusaurus 3.10 site for Bactopia, a bacterial genomics workflow. This file follows the agents.md convention; CLAUDE.md is an import stub.

  • Site: https://bactopia.io
  • Repo: bactopia/bactopia.github.io (deployed to Cloudflare Pages; PR deploy previews via Netlify)

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-tools-index.py data/tool-categories.yml bactopia-tools/index.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

  • Use the bactopia-dev conda environment -- it provides Node.js (>= 18) for Docusaurus and Python with the packages in requirements.txt for generation scripts
  • Prepend it to PATH: export PATH="$HOME/.conda/envs/bactopia-dev/bin:$PATH"
  • BACTOPIA_DEV_PYTHON in the Makefile points at this environment's 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)

Snapshots are built locally and pushed as orphan branches (the prepare-release-docs skill walks through this as part of a release):

# Build the outgoing version from a clean worktree of master
git worktree add /tmp/docs-snapshot master
cd /tmp/docs-snapshot
npm ci
make generate BACTOPIA_REPO=<bactopia checkout at outgoing tag>
DOCS_VERSION=vX.Y.Z npm run build

# Push the build output to an orphan branch
cd build
git init
git checkout --orphan snapshot/vX.Y.Z
git add -A
git commit -m "Snapshot vX.Y.Z ($(find . -type f | wc -l) files)"
git remote add origin git@github.com:bactopia/bactopia.github.io.git
git push origin snapshot/vX.Y.Z --force

Then register it on the docs branch: make snapshot-add VERSION=vX.Y.Z FILES=<count>. The deploy workflow assembles the snapshot into the build output on the next merge to master.

Build the snapshot BEFORE the new version's docs land on master, or the snapshot will contain the new version's content.

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

Repeat the local snapshot build with the same version. The orphan branch is force-pushed with the new build output; update the file count in snapshots.json if it changed.

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/deploy.yml Assembles active snapshots at deploy time

Skills

Agent skills live in .agents/skills/<skill-name>/SKILL.md with YAML frontmatter (name, description) followed by markdown instructions. .claude/skills is a symlink to .agents/skills/ for Claude Code compatibility.