TaxonPages

TaxonPages is a tool to serve taxon pages. At present it draws data from TaxonWorks' API, however we seek to keep the TaxonPages platform agnostic therefor facilitating the modular addition of functionality that may reference data from any biodiversity data-serving API.

Already running TaxonPages? Read this first

TaxonPages used to be installed by forking this repository and editing the setup branch. That workflow is no longer supported, TaxonPages is now distributed as an NPM package and existing sites need a one-time migration.

If you already have a TaxonPages site, do not create a new fork. Follow the Migration Guide instead. It explains exactly which files to add, remove, and rewrite on your existing setup branch, the whole process can be done from the GitHub website without any local tooling.

Installation

TaxonPages is distributed as an NPM package. Use the taxonpages CLI to scaffold and manage your project.

Requirements

• Node.js >= 20.19.0 or >=22.12.0

Quick start

There are two ways to create a new TaxonPages site, pick whichever fits your situation.

Option 1 — From the GitHub template (recommended, no local setup)

Use the taxonpages-config template if you want to publish a site to GitHub Pages without installing anything locally. Most users should start here.

1. Open SpeciesFileGroup/taxonpages-config and click Use this template → Create a new repository.
2. In your new repository, go to Settings → Pages and set Source to GitHub Actions.
3. Edit config/api.yml from the GitHub web interface and fill in your TaxonWorks API URL and project token.
4. Commit. GitHub Actions builds and publishes your site automatically at https://<your-user>.github.io/<your-repo>/.

See the template's README for the full step-by-step.

Option 2 — From the CLI (for local development)

Create a new project using npx (no global install needed):

npx @sfgrp/taxonpages init my-project
cd my-project
npm install

Edit config/api.yml with your TaxonWorks API URL and project token, then start the development server:

npm run dev

Your site will be running at http://localhost:5173/

Global installation

If you prefer to have the CLI available globally:

npm install -g @sfgrp/taxonpages

Then you can use it directly:

taxonpages init my-project

CLI Commands

All commands are available through npm run scripts in your project or directly via the taxonpages CLI:

| Command | npm script | Description | | ---------------------------------- | ------------------- | -------------------------------------------------- | | taxonpages init [directory] | — | Scaffold a new TaxonPages project | | taxonpages dev | npm run dev | Start development server (SPA mode, port 5173) | | taxonpages dev:ssr | npm run dev:ssr | Start SSR development server (port 6173) | | taxonpages build | npm run build | Build for production (SPA mode) | | taxonpages build:ssr | npm run build:ssr | Build for production (SSR mode) | | taxonpages serve | npm run serve | Start production SSR server (port 6173) | | taxonpages preview | npm run preview | Preview production build locally (port 4173) | | taxonpages package list | — | List all discovered plugins, panels, and modules | | taxonpages package add <name> | — | Install a TaxonPages package and auto-configure it | | taxonpages package remove <name> | — | Uninstall a package and clean up config | | taxonpages package unpack <name> | — | Unpack an NPM package into a local directory | | taxonpages package outdated | — | Check installed packages for available updates | | taxonpages package update [name] | — | Update one package, or all outdated packages | | taxonpages update | — | Update TaxonPages to the latest version | | taxonpages setup | — | Start the web-based configuration interface |

Example workflow

npx @sfgrp/taxonpages init my-project
cd my-project
npm install
# Edit config/api.yml with your API settings
npm run dev

Documentation

• User Guide — Configure your site: pages, theme, analytics, layout, taxa page panels, and installing extensions from NPM.
• Developer Guide — Build and publish your own panels, modules, and plugins for the TaxonPages ecosystem.
• Migration Guide — Upgrade an existing TaxonPages site (legacy fork-based setup) to the new NPM-based version.

License

TaxonPages is released under the MIT License. See LICENSE for details.