- Move Hugo spec (relative links) to _build/ instead of static/ with
-hugo- suffix, preserving original basenames for tag spec filenames
- Add articleDataKey, articleSection, and specDownloadPath to generated
section and tag page frontmatter for sidebar nav and download button
- Fix sidebar link test to use #nav-tree instead of .sidebar (avoids
matching the hamburger toggle link)
The API reference tests require generated content pages that are
gitignored. Add a before() hook that detects missing content and
runs the generation pipeline, then waits for Hugo to rebuild.
Hugo-native templates for API
reference documentation. Operations render as server-side HTML instead
of client-side Redoc, providing faster page loads, full SEO
indexability, and consistent styling.
Architecture:
- Tag-based navigation: operations grouped by OpenAPI tag, accessed
via tag pages only (no individual operation URLs)
- Generation script auto-discovers products from .config.yml files,
deriving Hugo paths and menu keys from directory structure
- Per-tag JSON/YAML chunks for fast Hugo template rendering
- Inline curl examples generated from OpenAPI specs at build time
Templates (layouts/api/, layouts/partials/api/):
- tag-renderer.html: renders all operations for a tag
- operation.html: individual operation with parameters, request body,
responses, and schema rendering
- code-sample.html: curl examples with Ask AI integration
- section-children.html: tag listing on section index pages
- all-endpoints-list.html: all operations sorted by path
Generation (api-docs/scripts/generate-openapi-articles.ts):
- Auto-discovery from .config.yml replaces hardcoded productConfigs
- Each API section generates independently (no cross-spec merging)
- Frontmatter-driven template data (specDownloadPath, articleDataKey)
- Link transformation: /influxdb/version/ placeholders resolved to
product-specific paths
Removed:
- Redoc renderer, JavaScript components, and CSS
- Shadow DOM test infrastructure (~160 lines)
- Operation page generation (dead generatePathPages function)
- mergeArticleData() and slugifyDisplayName()
Styles (assets/styles/layouts/_api-*.scss):
- 3-column layout: sidebar, content, sticky TOC
- Theme-aware code blocks for curl examples
- Method badges (GET/POST/PUT/DELETE) with color coding
- Collapsible schema sections with depth tracking
Tests (cypress/e2e/content/api-reference.cy.js):
- Tag page rendering with operation structure
- Download button verification per section
- All-endpoints page with operation cards
- Related links from x-related OpenAPI extension
- Code sample and Ask AI link validation
- Fix broken links reported by the e2e link checker.
- Add an e2e test for checking internal and external links in API reference docs. Low effort, big win.
- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.
Jason Stirnaman
Jason Stirnaman