Replace the 110-line productConfigs map with auto-discovery from
.config.yml files. The generation script now derives Hugo paths,
menu keys, and static file names from directory structure and
existing frontmatter.
Key changes:
- discoverProducts() scans api-docs/ for .config.yml files
- Each API entry generates independently (no mergeArticleData)
- New frontmatter params: specDownloadPath, articleDataKey, articleSection
- Templates use frontmatter lookup instead of hardcoded URL-to-key maps
- list.html download button simplified from 50 lines to 5
- Cypress tests updated for Hugo-native-only URLs
- Switch operation anchors from {method}-{path} to
operation/{operationId} (PascalCase), matching Redocly convention
and existing content links like #operation/PutPluginFile.
Updated in Hugo templates, all-endpoints list, and JS TOC.
- Remove nested bordered containers from API operations. Operations
separated by top-border dividers instead of card wrappers. Param
lists, schema properties, and responses no longer wrapped in
bordered boxes.
- Replace CSS custom properties (var(--article-text, ...)) with SCSS
theme variables ($article-text, $article-heading, $nav-border, etc).
The CSS vars were never defined in this theme, so all text fell back
to hardcoded dark-gray values invisible in dark mode.
- Delete entire dark mode override section — now handled automatically
by Hugo's per-theme SCSS compilation.
- Add border-bottom divider to operation endpoint line for visual
separation from the operation heading.
- Update PLAN.md to mark Task 7 as completed.
Complete Tasks 1-5 of the Hugo-native API migration:
- Promote Hugo-native templates from POC to production location
- Remove RapiDoc templates (rapidoc.html, rapidoc-tag.html, rapidoc-mini.html)
- Remove RapiDoc JS components (api-rapidoc.ts, rapidoc-mini.ts)
- Clean up generation scripts (~200 lines of dead code removed)
- Rewrite Cypress tests for standard HTML (no shadow DOM)
Templates moved from layouts/partials/api/hugo-native/ to parent.
All verifications pass (Hugo build, TypeScript compilation).
Add Hugo-native rendering as alternative to RapiDoc for API documentation.
Renders operations, parameters, request bodies, schemas, and responses
using Hugo templates styled after docusaurus-openapi aesthetic.
New partials:
- tag-renderer.html: Main renderer that loads OpenAPI spec
- operation.html: Operation block with header and sections
- parameters.html: Groups query/path/header parameters
- parameter-row.html: Individual parameter rendering
- request-body.html: Request body with schema
- schema.html: Recursive JSON schema rendering
- responses.html: Response status codes with schemas
Features:
- Parses OpenAPI YAML at build time (no JS required)
- Resolves $ref references for parameters and schemas
- Displays JSON examples from spec
- Color-coded status badges (2xx green, 4xx red)
- x-influxdata-related links rendered at page bottom
- Dark mode support
- Responsive design
Enable with `useHugoNative: true` in page frontmatter.
Replace unreliable findRE regex with split-based path extraction for
version detection in API section index pages. The previous regex
"[^/]+.*?" was inconsistent and could fail to extract version correctly.
Changes:
- layouts/_default/api.html: Add dual-button logic for clustered/cloud-dedicated
section index pages using split-based URL path extraction
- layouts/api/list.html: Replace findRE with split for version extraction
- layouts/api/section.html: Add dual-button logic matching api.html
The split approach extracts path segments reliably:
/influxdb3/clustered/api/ → ["", "influxdb3", "clustered", "api", ""]
$version = index 2 = "clustered"
On the API section index pages for InfluxDB 3 Clustered and Cloud Dedicated, show two download buttons side-by-side: one for the Data API spec and one for the Management API spec.
The implementation extracts product/version from the URL using findRE pattern, detects Clustered or Cloud Dedicated from version segment, renders dual buttons only on section index pages (no tag param), uses flexbox layout that stacks on mobile, and includes dark mode styling consistent with existing UI.
- Add "All endpoints" page showing all operations grouped by API version
- Generate all-endpoints page automatically via TypeScript generation script
- Make "All endpoints" nav item a clickable link instead of just a toggle
- Fix duplicate menu entry warnings for cloud-v2 and oss-v2 products
by adding skipParentMenu: true to their configs
- Fix 404 errors for paths with curly braces (e.g., {request_path})
by removing braces in normalize-path.html partial
- Add Cypress tests for API section structure and all-endpoints page
- Update v2 product article data with tag-based generation
- Add normalize-path.html partial for consistent path normalization
- Strip /api prefix and add v1/ for paths without version
- Update generate-openapi-articles.ts with same normalization logic
- Update list.html and sidebar menu to use normalized paths
- Document AWS credentials in deploy-staging.sh
- Always show children after content (was showing either/or)
- Use children-links class for arrow indicator styling
- Truncate descriptions to first paragraph and 200 chars
- Apply markdownify filter for proper markdown rendering
Update Hugo templates to correctly display API children listing on
section index pages (/influxdb3/core/api/, /influxdb3/enterprise/api/)
instead of the RapiDoc renderer.
- Create layouts/api/section.html for API section pages
- Update layouts/_default/api.html to detect section pages and render
content directly instead of using RapiDoc
- Clean up layouts/api/list.html debug comment
The issue was that layouts/_default/api.html took precedence over
layouts/api/list.html for section pages due to Hugo's type-based
template lookup. The fix adds .IsSection check to delegate section
pages to appropriate rendering logic.
- Add api/section-children.html partial for API section index pages
- Update api/list.html to detect section index vs tag pages
- Add "All endpoints" nav item listing all operations sorted by method+path
- Remove {{< children >}} shortcode from API index pages (use data-driven list)
- Restore original RapiDoc match-paths format (method /path) for proper filtering
- Restrict operation tags to primary tag in tag-specific specs to prevent duplicates
- Rename Token tag to Auth token for clarity in Core and Enterprise specs
- Remove Table tag from cache operations (distinct_cache, last_cache)
- Add build script combining API docs, Hugo, and Markdown generation
- Skip summary rendering for conceptual pages
- Add isConceptual check to hide operations in nav for conceptual pages
The feature is shippable, but needs a few small fixes and we'll need to update or alias all API docs links for Core and Ent3.
- Add rapidoc-mini.ts TypeScript component with CDN loading and theme sync
- Add api-operation layout for standalone operation pages
- Add rapidoc-mini.html partial for reusable RapiDoc rendering
- Add rapidoc-custom.css for RapiDoc style overrides
- Register rapidoc-mini component in main.js
- Add article data for cloud-dedicated and clustered products
- Update API reference Cypress tests
- Header summary now shows only the first sentence from description
using regex extraction with fallback to first line for descriptions
without sentence-ending punctuation
- Added Overview section with full description after endpoints list
- Rewrite single.html for operation pages with RapiDoc integration
- Simplify rapidoc.html partial for tag-based rendering
- Add sidebar-nav include to sidebar.html for API navigation
- Add tab-panels.html and tabs.html for content organization
- Add CSS for operations list cards with method badges, paths, and summaries
- Remove duplicate Overview section from list.html (was duplicating summary)
- Split "Data Operations" into separate nav groups: Write data, Query data, Cache data
Replace legacy API documentation approach with modern Scalar-based rendering:
## Architecture Changes
- Add renderer abstraction (`layouts/partials/api/`) supporting Scalar and RapiDoc
- Create `api` layout type for API reference pages (single.html, list.html)
- Configure renderer via `site.Params.apiRenderer` (default: scalar)
## OpenAPI Processing Pipeline (TypeScript)
- `api-docs/scripts/generate-openapi-articles.ts` - Main generation script
- `api-docs/scripts/openapi-paths-to-hugo-data/` - OpenAPI to Hugo data converter
- Generates per-endpoint path fragments for AI agent access
- Creates Hugo content pages with `type: api` frontmatter
## AI Agent Accessibility
- Full specs at `/openapi/influxdb-{product}.yml` and `.json`
- Per-endpoint fragments at `/openapi/influxdb-{product}/paths/`
- `<link rel="alternate">` tags in HTML for machine discovery
## Scalar Features
- Dark/light theme support synchronized with site theme
- InfluxData brand colors
- Responsive layout
- Download link for OpenAPI spec
## Products Supported
- cloud-v2, oss-v2
- influxdb3-core, influxdb3-enterprise
- cloud-dedicated, cloud-serverless, clustered
Usage: node api-docs/scripts/dist/generate-openapi-articles.js [product]
Jason Stirnaman