TestBench Ecosystem Documentation

Multi-instance Docusaurus 3 documentation portal for the TestBench Ecosystem by imbus AG. Each tool has its own documentation set with independent versioning.

Repository layout

imbus/                                          # GitHub org / parent folder
├── testbench-ecosystem-documentation/          # This repo (Docusaurus site)
│   ├── .github/workflows/
│   │   ├── release-pages.yml                   # Deploy to GitHub Pages on push to main
│   │   ├── pr-preview-surge.yml                # Deploy PR previews to Surge.sh
│   │   └── version-tool-docs.yml               # Create versioned docs from tool releases
│   └── docusaurus/
│       ├── docs/                               # Global ecosystem docs (route: /docs/)
│       ├── <tool-id>/                          # Tool "next" docs (git-ignored, synced for dev)
│       ├── <tool-id>_versions.json             # Released versions (committed)
│       ├── <tool-id>_versioned_docs/           # Versioned doc snapshots (committed)
│       ├── <tool-id>_versioned_sidebars/       # Versioned sidebars (committed)
│       ├── sidebars_<tool-id>.ts               # Tool sidebar definition
│       ├── tools.config.json                   # Tool metadata (label, description, logo)
│       ├── scripts/
│       │   ├── sync-docs.mjs                   # Copies docs from neighbor repos
│       │   └── add-tool.mjs                    # Interactive wizard for adding tools
│       ├── docusaurus.config.ts                # Main site config (auto-discovers tools)
│       └── package.json
├── testbench-cli-reporter/                     # Tool repo (neighbor)
│   └── docs/                                   # Documentation source
├── testbench-requirement-service/              # Tool repo (neighbor)
│   └── docs/                                   # Documentation source
└── ...                                         # More tool repos

Important: Tool repositories must be cloned as siblings of this repo (same parent directory). The folder name of each tool repo must match its tool-id in tools.config.json.

Local development

All commands run from the docusaurus/ directory:

cd docusaurus
npm install

Start the dev server

npm run dev

This runs two things concurrently:

sync:watch — copies the docs/ folder from each neighboring tool repo into docusaurus/<tool-id>/ and watches for changes.
docusaurus start — launches the dev server at http://localhost:3000 with hot reload.

When you edit files in a tool's docs/ folder, changes are automatically synced and the browser reloads.

Sync specific tools only

# Via argument
npm run dev -- --repos testbench-cli-reporter

# Via environment variable
SYNC_REPOS=testbench-cli-reporter npm run dev

Other commands

Command	Description
`npm run build`	Production build (only versioned/released tools)
`npm run start`	Dev server without doc syncing
`npm run serve`	Serve a production build locally
`npm run sync`	One-time sync from neighbor repos
`npm run typecheck`	TypeScript type checking
`npm run clear`	Clear Docusaurus cache
`npm run add-tool`	Interactive wizard to register a new tool

Environment variables

Variable	Description
`INCLUDE_NEXT=true`	Include unreleased ("next") docs in production builds
`SYNC_REPOS=tool1,tool2`	Comma-separated list of tools to sync

Adding a new tool

1. Register the tool in this repo

Run the interactive wizard:

cd docusaurus
npm run add-tool

This creates:

An entry in tools.config.json
A sidebar file sidebars_<tool-id>.ts
A starter doc at <tool-id>/intro.md

The tool auto-discovers from the sidebar file and appears in the Ecosystem navbar dropdown.

Alternatively, do it manually:

Add the tool to docusaurus/tools.config.json:

{
  "my-new-tool": {
    "label": "My New Tool",
    "description": "What the tool does.",
    "logo": "img/my-new-tool.svg"
  }
}

Create docusaurus/sidebars_my-new-tool.ts:

const sidebars = {
  myNewToolSidebar: [{ type: 'autogenerated', dirName: '.' }],
};
export default sidebars;

Create docusaurus/my-new-tool/intro.md with at least a title.

2. Set up the tool repository

The tool repo must:

Be in the same GitHub organization (imbus).
Have a docs/ folder at its root with Docusaurus-compatible markdown.
Be named exactly like the tool-id used in this repo.

3. Add the release trigger workflow

Copy the file .github/workflows/trigger-docs-release.yml from an existing tool (e.g., testbench-cli-reporter) into the new tool's .github/workflows/ directory. No changes are needed — the workflow reads the tool-id from the repository name and the version from the release tag automatically.

4. Ensure the `ECOSYSTEM_DOCS_TOKEN` secret is available

The tool repo needs a secret called ECOSYSTEM_DOCS_TOKEN — a GitHub PAT (or fine-grained token) with permission to trigger repository_dispatch on testbench-ecosystem-documentation. This is best configured as an organization-level secret shared across all tool repos.

Versioning

Each tool has independent versioning. Versioned files are committed to this repo; the "next" (current/unreleased) docs are git-ignored and synced from the tool repo during development.

Automated versioning (recommended)

When you create a GitHub release in a tool repository:

The tool's trigger-docs-release.yml workflow fires.
It sends a repository_dispatch event to this repo with the tool-id and version.
This repo's version-tool-docs.yml workflow:
- Downloads the docs/ folder from the release tag.
- Runs docusaurus docs:version:<tool-id> <version> to create a versioned snapshot.
- Commits the versioned docs to a new branch and opens a PR.
The PR triggers a Surge.sh preview deployment for review.
Merging the PR triggers a GitHub Pages production deployment.

┌──────────────┐    repository_dispatch    ┌──────────────────────────┐
│  Tool repo   │ ────────────────────────► │  ecosystem-docs repo     │
│  (release)   │  tool_id, version, tag    │  version-tool-docs.yml   │
└──────────────┘                           └────────────┬─────────────┘
                                                        │
                                                        ▼
                                              Create branch + PR
                                                        │
                                                        ▼
                                              PR preview (Surge.sh)
                                                        │
                                                        ▼
                                              Merge → GitHub Pages

Manual versioning

From the docusaurus/ directory:

npm run docusaurus -- docs:version:<tool-id> <version>

Example:

npm run docusaurus -- docs:version:testbench-cli-reporter 1.3.0

This snapshots the current docs from docusaurus/<tool-id>/ into versioned directories.

Version files

Path	Content
`<tool-id>_versions.json`	Array of released version numbers
`<tool-id>_versioned_docs/version-X.Y.Z/`	Frozen docs for that version
`<tool-id>_versioned_sidebars/version-X.Y.Z-sidebars.json`	Frozen sidebar for that version

CI/CD

Workflow	Trigger	Purpose
`release-pages.yml`	Push to `main`	Build and deploy to GitHub Pages
`pr-preview-surge.yml`	Pull request events	Deploy preview to `<repo>-pr-<number>.surge.sh`
`version-tool-docs.yml`	`repository_dispatch` from tool repos	Create versioned docs PR

Required secrets

Secret	Scope	Used by
`SURGE_TOKEN`	This repo	PR preview deployments
`ECOSYSTEM_DOCS_TOKEN`	Org-level (all repos)	Tool repos: trigger `repository_dispatch`. This repo: checkout private tool repos for docs download.

The ECOSYSTEM_DOCS_TOKEN should be a fine-grained PAT (or classic PAT) with:

Read access to contents of all tool repositories in the org
Write access to trigger repository_dispatch on this repo

Configuring it as an organization-level secret shared across all repos is the simplest approach.

Troubleshooting

Tool doesn't appear in the Ecosystem dropdown: Ensure sidebars_<tool-id>.ts exists and docusaurus/<tool-id>/intro.md exists.
npm run dev doesn't sync a tool: The tool repo must be cloned as a sibling directory with a name matching the tool-id. Check tools.config.json.
Versioned tool doesn't show in production build: Only tools with at least one entry in <tool-id>_versions.json are included in production builds.
Automated versioning PR not created: Check that ECOSYSTEM_DOCS_TOKEN is set in the tool repo and has repo scope on this repo.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

TestBench Ecosystem Documentation

Repository layout

Local development

Start the dev server

Sync specific tools only

Other commands

Environment variables

Adding a new tool

1. Register the tool in this repo

2. Set up the tool repository

3. Add the release trigger workflow

4. Ensure the `ECOSYSTEM_DOCS_TOKEN` secret is available

Versioning

Automated versioning (recommended)

Manual versioning

Version files

CI/CD

Required secrets

Troubleshooting

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

TestBench Ecosystem Documentation

Repository layout

Local development

Start the dev server

Sync specific tools only

Other commands

Environment variables

Adding a new tool

1. Register the tool in this repo

2. Set up the tool repository

3. Add the release trigger workflow

4. Ensure the ECOSYSTEM_DOCS_TOKEN secret is available

Versioning

Automated versioning (recommended)

Manual versioning

Version files

CI/CD

Required secrets

Troubleshooting

4. Ensure the `ECOSYSTEM_DOCS_TOKEN` secret is available