| name | serve-docs |
| description | Spin up the Astro / Starlight documentation site locally for live preview, optionally for a specific nf-metro branch. Use when the user wants to run, serve, preview, or develop the docs site (website/) - phrases like "serve the docs", "spin up the site", "run the docs locally", "preview the website", "start the astro server", "preview the docs for branch X / this PR", or when iterating on docs content, theme/layout overrides, or the gallery/pipelines/playground pages and wanting to see changes in a browser. Wraps scripts/serve_docs.sh, which generates the git-ignored dynamic content (gallery, pipelines, playground manifest) before starting the dev server, and with --branch checks the branch out into an isolated worktree and installs its nf_metro so the renders reflect that branch. |
| allowed-tools | Bash(scripts/serve_docs.sh*), Bash(./scripts/serve_docs.sh*), Bash(source *), Bash(cd *), Bash(curl *) |
Serve the docs site locally
The docs live in two places (see CLAUDE.md): docs/ holds the hand-written
Markdown, and website/ is the Astro / Starlight app that renders it. The
Gallery, nf-core pipelines, and playground pages plus all rendered example SVGs
are generated and git-ignored, so a bare npm run dev gives an incomplete
site. scripts/serve_docs.sh handles the generation and the dev server in one
command.
Conventions
- Local checkout:
~/projects/nf-metro (substitute if yours differs).
- The gallery/playground generators import the
nf_metro Python package, so the
project env must be active. The convention here is the nf-metro micromamba
env: source ~/.local/bin/mm-activate nf-metro. If nf_metro is not
importable the script warns and still starts the server, but the
Gallery / pipelines / playground pages will be empty.
- The dev server serves at http://localhost:4321/nf-metro/ (note the
/nf-metro/ base path).
Step 1: Activate the Python env
source ~/.local/bin/mm-activate nf-metro
Step 2: Run the script
Preview a specific branch (the common case - e.g. reviewing a PR's docs or
render changes):
scripts/serve_docs.sh --branch <ref>
Or preview the current checkout:
scripts/serve_docs.sh
Useful flags:
| Flag | Effect |
|---|
| (none) | Generate dynamic content if missing (for the current checkout), then start the dev server. |
--branch <ref> | Serve a specific branch: set up/reuse a worktree, install its nf_metro, regenerate content, serve. Always regenerates so renders match the ref. |
--worktree-dir <p> | Where --branch places its worktree (default ../nf-metro-serve-<ref>). |
--rebuild | Force-regenerate gallery + playground content (use after editing examples/ or the layout engine). |
--skip-content | Skip content generation entirely - fastest when you only touch theme/layout/Markdown and already have content. |
--preview | Production astro build + astro preview instead of the dev server (mirrors the deployed output more closely). |
--no-install | Skip the npm dependency check. |
-- <args> | Everything after -- is forwarded to astro, e.g. -- --host 0.0.0.0 --port 4000. |
--branch installs the branch's nf_metro (editable) into the active env,
so afterwards that env points at the worktree. Re-point it with
pip install -e ~/projects/nf-metro when you go back to the main checkout, or
use a dedicated env for branch previews.
Step 3: Open it
Visit http://localhost:4321/nf-metro/. The dev server hot-reloads on
edits to website/ and docs/. Stop it with Ctrl-C.
Notes
--branch serves a detached checkout of the ref, so it works even when
that branch is already checked out in another worktree (e.g. a dev worktree).- Content (gallery/pipelines/playground) is regenerated, not hot-reloaded:
re-run with
--rebuild after changing examples/ or the rendering code.
- For a visual regression diff of renders against
origin/main, that's a
different job - see the render-topologies skill.
