Repository navigation
[Enhancement]: Replace redocusaurus for API reference rendering #1294
Description
Page or section
API reference pages rendered by redocusaurus from static/api-specs/:
- ToolHive API
- Registry API
- Enterprise Manager API
- Connector Gateway API
- AI Gateway API
What could be better?
The API reference renders as a separate embedded Redoc app inside the docs. It has its own layout and navigation, and it doesn't match the site's look or plug into the site's sidebars and search the way other pages do.
redocusaurus also breaks code highlighting site-wide: its client module leaves Prism in a state where no additionalLanguages grammar registers (#1293).
Proposed improvement
Replace redocusaurus. Two candidates:
docusaurus-plugin-openapi-docs(Palo Alto Networks): generates an MDX page per endpoint, with a built-in request client.- Pages use the Docusaurus theme, sidebars, site search, and
llms.txtlike any other docs page, and they version with the enterprise snapshots. - The cost is a generation step and hundreds of generated files in the repo.
- Work in progress on
spike/openapi-native-sidebarmigrates every API to plugin v5.2.0. Its preview also confirms the [Bug]: Code blocks inadditionalLanguageslanguages render without syntax highlighting #1293 fix.
- Pages use the Docusaurus theme, sidebars, site search, and
- Scalar (
@scalar/docusaurus): one embedded reference page per spec with a modern UI.- It has a polished request client, theme presets, custom CSS, preset servers, and prefilled authentication.
- Very little config and no generated files.
- It stays a separate app with its own sidebar and search, much like Redoc today. Its search and
llms.txtcoverage, and whether the request client goes through a hosted proxy by default, are unverified.
Things to settle:
- Fit with versioned enterprise docs.
- Integration with the release-sync scripts that refresh
static/api-specs/. - Redirects for the current API reference URLs.
Additional context
Supersedes the earlier attempt on the docusaurus-openapi-docs branch (plugin v4, kept redocusaurus alongside).
Fully or partially written by an AI agent.
Activity
danbarr commentedon Oct 29, 2026
Pushed the Scalar evaluation to
spike/scalar-api-reference, replacing Redocusaurus for all five APIs. It uses@scalar/docusaurus0.8.54 with the renderer pinned to 1.76.2.Enterprise Manager preview · Full spike notes
The main tradeoff is navigation. Scalar keeps the site navbar but replaces the product sidebar with its own API navigation. Opening a reference takes you out of the docs journey. Existing overview URLs and connection/authentication guidance remain in place, with links to the separate explorer pages, but that transition feels disconnected.
Other findings:
llms.txtplugin exported only the site shell for explorer routes; those exports are excluded in the spike. OpenAPI downloads remain available.localhost:8080. Real deployments still need authentication and CORS configuration; this does not establish the plugin's default proxy behavior.Local production build, typecheck, formatting, lint, and browser smoke checks passed. Additional Prism grammars register after Redocusaurus is removed. Release-sync CI and live authenticated API calls have not been tested.
The Palo Alto plugin looks like the better fit for this site: preserving the site's navigation is more valuable here than Scalar's lower generation overhead. Scalar could be embedded in a normal docs page through a custom integration, but the official plugin does not provide that experience. Search/export coverage still needs verification for the Palo Alto spike before treating that comparison as settled.