Skip to main content

Authoring documentation

The published documentation is a Docusaurus site in TestVibe/DOCS-TestVibe. The user guide is maintained in that repository's content/guide/ directory because its former source repository, TestVibe/testvibe-docs, is archived. The developer reference still comes from the writable TestVibe/testvibe-api GitBook repository.

Edit the source​

Edit guide Markdown under content/guide/ in the site repository, or API Markdown in the API GitBook checkout. Update the corresponding SUMMARY.md when adding a page or changing navigation labels. Keep the guide's GitBook-compatible source format and asset links; do not push guide changes to or unarchive the old repository. Do not hand-edit generated docs/, api-docs/, or sidebar files: migration overwrites them.

Verify instructions against the current app and API before changing them. Use visible product labels in the user guide. Preserve literal routes, field names, command names, and response states in the developer reference.

Screenshots​

Store guide screenshots in content/guide/.gitbook/assets/ and reference them from source pages with a relative Markdown image link. Use the current app UI with an illustrative demo project, readable text, and no customer data or credentials. Update the caption when the displayed controls change.

The site repository's scripts/screenshots/ contains the capture fixtures and instructions used for this refresh. These render current app components with demo data; they do not execute billable tests. Rebuild fixtures from the app revision being documented before taking new images.

Generate and check​

In the site checkout, edit the pages under docs/ and api-docs/ directly, then run npm ci, npm run typecheck, and npm run build.

Review the resulting diff for missing pages, videos, images, and redirects. The build checks internal links and anchors. Open the built site to inspect navigation, images, code examples, and mobile layouts before publishing.

Keep URLs stable​

The guide is served at the site root; the API is under /testvibe-api/. Most paths follow the Markdown filename without .md; directory README.md files become section indexes.

  • Guide README.md becomes /.
  • forms/login.md becomes /reference/forms/login.
  • authoring.md becomes /reference/authoring.

Use descriptive page titles without changing established paths. If a URL must change, add and verify a redirect. Existing /skills/ and /ai-generation/ paths remain valid despite updated product terminology.

Publish​

Netlify builds the site repository with npm ci && npm run build and publishes build/. This build does not run migration: regenerate locally and commit the guide source together with the generated output in the site repository. Commit API source changes in its own GitBook repository as well. Verify a deploy preview before merging and publishing. The site also produces Markdown routes and documentation artifacts for its MCP endpoint, so keep API and guide content consistent.