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:

1. sync:watch — copies the docs/ folder from each neighboring tool repo into docusaurus/<tool-id>/ and watches for changes.
2. 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:

1. 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"
     }
   }

2. Create docusaurus/sidebars_my-new-tool.ts:

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

3. 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:

1. The tool's trigger-docs-release.yml workflow fires.
2. It sends a repository_dispatch event to this repo with the tool-id and version.
3. 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.
4. The PR triggers a Surge.sh preview deployment for review.
5. 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.