Migrate API reference docs to Hugo-native for improved site integration by jstirnaman · Pull Request #6622 · influxdata/docs-v2

jstirnaman · 2025-12-11T23:45:28Z

API reference uplift

Replace Redoc with Hugo-native templates for API reference documentation. Operations render as standard HTML — no shadow DOM, no client-side rendering.

Hugo-native layout

Server-rendered HTML from OpenAPI specs via Hugo templates (layouts/partials/api/)
Tag-based navigation — operations grouped by tag on dedicated tag pages (e.g., /influxdb3/core/api/database/)
No individual operation pages — operations accessed only through tag pages
"All endpoints" page with operation cards linking to tag pages
Right sidebar TOC with scroll-tracking highlights
Faster page loads, full SEO indexability, consistent site styling

Inline curl examples

Generated at Hugo template time from the OpenAPI spec — no build script changes
Server URL variable resolution ({baseurl} → default from spec.servers[0].variables)
$ref resolution for parameters, request bodies, and schemas
Required query parameters included automatically
JSON request bodies built from schema properties (fallback chain: example → default → enum[0] → type placeholder)
Line protocol bodies for text/plain content types
Existing influxdb-url.js automatically personalizes placeholder hosts

Ask AI integration

"Ask AI about this example" link on each curl example
Uses existing Kapa widget integration (ask-ai-open class + data-query attribute)
Zero new JavaScript — leverages existing ask-ai-trigger.js

Visual improvements

Distinct badge colors: DELETE (crimson #D63031) vs 4xx errors (warm orange #E17055)
Stronger operation separation (2px border, increased padding)
Response body indentation with left border for visual association with status codes
Dark code blocks with Catppuccin Mocha theme

Build and generation

yarn build:api-docs parses OpenAPI specs into Hugo data and generates content pages
--clean flag (default) removes stale files when tags are renamed or removed
--dry-run flag previews what would be deleted
Static JSON chunks for tag-page data

jstirnaman · 2025-12-12T18:53:56Z

Code review

Found 1 issue:

Inline JavaScript in rapidoc.html violates the documented JavaScript component pattern (DOCS-CONTRIBUTING.md says: "The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and assets/js/main.js as the entry point to import modules from assets/js. Only assets/js/main.js should be imported in HTML files.")

The file contains ~310 lines of inline JavaScript (lines 97-408) for theme detection, DOM manipulation, and event handling. This should be refactored into a TypeScript component in assets/js/components/ and registered in main.js, similar to how scalar.html uses the api-scalar.ts component.

docs-v2/layouts/partials/api/rapidoc.html

Lines 95 to 110 in 90044bd

    
           <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script> 
        
           <script> 
        
           (function() { 
        
             'use strict'; 
        
             console.log('[RapiDoc] Script loaded'); 
        
             // Detect current theme by checking which theme stylesheet is enabled 
        
             function isDarkTheme() { 
        
               // Check for enabled dark-theme stylesheet 
        
               const darkStylesheet = document.querySelector('link[rel*="stylesheet"][title="dark-theme"]:not([disabled])'); 
        
               if (darkStylesheet && !darkStylesheet.disabled) { 
        
                 return true; 
        
               }

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

github-actions · 2025-12-29T21:26:17Z

PR Preview Action v1.4.8
🚀 Deployed preview to https://influxdata.github.io/docs-v2/pr-preview/pr-6622/
on branch `gh-pages` at 2026-04-06 20:38 UTC

github-actions · 2025-12-29T21:26:18Z

📦 PR Preview — Preview Bot

Status	Details
Result	✅ DEPLOYED
Preview	View preview
Pages	50 page(s) deployed
Build time	69s
Last updated	2026-04-06 20:38:13 UTC

Pages included in this preview

/enterprise_influxdb/v1/tools/api/
/influxdb/cloud/admin/buckets/bucket-schema/
/influxdb/cloud/admin/buckets/create-bucket/
/influxdb/cloud/admin/buckets/update-bucket/
/influxdb/cloud/admin/buckets/view-buckets/
/influxdb/cloud/api-guide/api-invokable-scripts/
/influxdb/cloud/get-started/setup/
/influxdb/cloud/query-data/parameterized-queries/
/influxdb/cloud/reference/api/
/influxdb/cloud/reference/internals/ttbr/
/influxdb/cloud/reference/release-notes/cloud-updates/
/influxdb/cloud/tags/
/influxdb/cloud/write-data/developer-tools/api/
/influxdb/v1/tools/api/
/influxdb/v2/admin/buckets/create-bucket/
/influxdb/v2/get-started/setup/
/influxdb/v2/process-data/manage-tasks/run-task/
/influxdb/v2/process-data/manage-tasks/view-tasks/
/influxdb/v2/reference/api/
/influxdb/v2/reference/config-options/
... and 30 more

_{Preview auto-deploys on push. Will be cleaned up when PR closes.}

jstirnaman · 2025-12-31T21:16:35Z

Works with Core and Enterprise, currently. Deployed to staging.

jstirnaman · 2025-12-31T23:14:34Z

@claude The last commit fixed the children list in the /api/ section page template, but broke the endpoint page template. Analyze.

Screenshot:

jstirnaman · 2026-01-02T22:41:25Z

@claude The last commit fixed the children list in the /api/ section page template, but broke the endpoint page template. Analyze.

Screenshot:

✅

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]

- latest-patch.html: Replace deprecated .Store with local variable assignment. The .Store method was removed from shortcode context in newer Hugo versions. - api-endpoint.html: Add nil check for productRef lookup to prevent index errors when productKey is not in productAliases dictionary. Falls back to "influxdb" as default product reference.

- yarn build:api-docs: Generate API docs for all products - yarn build:api-docs cloud-v2: Generate for specific product - yarn build:api-docs:compile: Recompile TypeScript if modified

…. Split ui-dev subagent into hugo-, ts-, and testing-specific agents.

- 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

- Add support for tag-based article generation with operations metadata - Generate articles.yml data files with tag, menuName, and isConceptual fields - Include operations array in frontmatter for tag pages

- 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 api-nav.ts for sidebar navigation collapse/expand - Add api-scalar.ts for Scalar API renderer integration - Add api-tabs.ts for tab switching functionality - Add api-toc.ts for table of contents generation - Register components in main.js

- Add YAML article data files for all InfluxDB products - Add sidebar-nav.html partial for API navigation rendering - Rename data directory from article-data to article_data for Hugo compatibility - Remove obsolete JSON articles file

- Update hugo.yml config for API docs settings - Simplify _api-overrides.scss (removed hardcoded content styles) - Import _api-layout.scss in styles-default.scss - Update API landing pages for Core and Enterprise with redirects - Update OpenAPI spec files - Update dependencies

- Update tests for new tag-based API page structure - Add tests for operations list rendering - Add tests for sidebar navigation groups

…tion - 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

- Sidebar nav now shows operations with method badges and paths instead of duplicating tag names when groups are expanded - Added background color to nav group items to match sidebar - Increased max-height for expanded groups to accommodate all operations - Added styles for operation items in sidebar nav (.api-nav-operation) - Fixed summary paragraph width by setting flex-basis to 100%

Replace faint link with a small bordered button that has good contrast in both light and dark modes.

These v2/cloud tags pages use an old layout that causes Hugo to panic during live rebuilds when generated API content is present.

…line Remove dead Redoc HTML generation code (generateRedocHtml, template.hbs, redoc-static.html gitignore entry) and update all documentation and agent files to reflect the Hugo-native API rendering pipeline. Also fix pre-existing YAML frontmatter quoting in agent descriptions and remove unused eslint-disable directives in ask-ai.ts.

This reverts commit d2e9ba5.

…rverless Restructure API reference docs for consistency across all InfluxDB products: - Align Enterprise tags with Core (13 matching tags via rename/reassign) - Add nested Data API / Management API sidebar for Cloud Dedicated and Clustered - Drop 29 unsupported TSM-era tags from Cloud Serverless, add Note callout - Mirror data paths to content paths (remove articleDataKey indirection) - Fix specDownloadPath for single-spec products with displayName - Add reassign and drop features to post-process-specs.ts tags.yml config - Add data-driven Cypress tests for sidebar nav and conceptual page content - Fix response description markdown rendering

Brings in tag alignment, multi-spec sidebar, Cloud Serverless cleanup, data path restructuring, and data-driven Cypress tests.

# Conflicts: # .github/workflows/doc-review.yml # AGENTS.md # PLAN.md # assets/js/content-interactions.js # data/products.yml

Hugo 0.157.0 panics with "nil walk context" during fast render rebuild when generated API content pages are present. Use --disableFastRender for the Cypress test server to avoid this.

github-actions · 2026-03-30T03:08:40Z

Vale Style Check Results

Metric	Count
Errors	0
Warnings	79
Suggestions	104

Warnings (79)

File	Line	Rule	Message
`.claude/agents/analyze-api-specs.md`	8	write-good.Passive	'are documented' may be passive voice. Use active voice if you can.
`.claude/agents/analyze-api-specs.md`	97	write-good.TooWordy	'validate' is too wordy.
`.claude/agents/analyze-api-specs.md`	104	write-good.Passive	'be fixed' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb1-tech-writer.md`	27	write-good.Passive	'are deprecated' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb1-tech-writer.md`	49	write-good.TooWordy	'Validate' is too wordy.
`.claude/agents/influxdb1-tech-writer.md`	57	write-good.TooWordy	'Implement' is too wordy.
`.claude/agents/influxdb1-tech-writer.md`	83	write-good.Passive	'be structured' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb1-tech-writer.md`	89	write-good.TooWordy	'prioritize' is too wordy.
`.claude/agents/influxdb3-tech-writer.md`	69	write-good.Passive	'be shared' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb3-tech-writer.md`	75	write-good.TooWordy	'Validate' is too wordy.
`.claude/agents/influxdb3-tech-writer.md`	88	write-good.TooWordy	'Implement' is too wordy.
`.claude/agents/influxdb3-tech-writer.md`	97	write-good.Passive	'be shared' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb3-tech-writer.md`	103	write-good.TooWordy	'multiple' is too wordy.
`.claude/agents/influxdb3-tech-writer.md`	120	write-good.Passive	'be structured' may be passive voice. Use active voice if you can.
`.claude/agents/influxdb3-tech-writer.md`	139	write-good.TooWordy	'prioritize' is too wordy.
`.claude/agents/ts-component-dev.md`	20	write-good.TooWordy	'Implement' is too wordy.
`.claude/agents/ts-component-dev.md`	231	write-good.TooWordy	'Implement' is too wordy.
`.claude/agents/ts-component-dev.md`	235	write-good.TooWordy	'requirement' is too wordy.
`.claude/agents/ts-component-dev.md`	386	write-good.Passive	'is required' may be passive voice. Use active voice if you can.
`.claude/skills/content-editing/SKILL.md`	18	write-good.TooWordy	'multiple' is too wordy.

Showing first 20 of 79 warnings.

✅ Check passed

…dd HEAD badge - Drop 29 unsupported TSM-era tags from Cloud Serverless via tags.yml drop config - Add Note callout on Cloud Serverless landing page directing to Cloud (TSM) reference - Fix Cloud Serverless terminology (databases → buckets, organizations) - Widen right-side TOC (200px → 260px) for readable operation summaries - Add HEAD method badge color (#00897B teal) - Update api-docs/README.md: remove outdated Redoc plugin/decorator docs, add overlay table - Update .github/instructions: fix Redocly → @redocly/cli - Rename and slim analyze-api-source agent → analyze-api-specs (remove README duplication) - Update PLAN.md: clarify @redocly/cli is bundling only, not rendering

…ildren extraction - Add article/feedback.html partial to all 5 API layouts (was missing) - Add ESLint config block for api-docs/scripts with Node globals and correct tsconfig - Disable no-undef for api-docs scripts (TypeScript handles it) - Fix unused vars (prefix with _) - Fix section-children description extraction for single-newline descriptions (Enterprise v1 Write tag had heading/bullets in one block)

… Bearer scheme name - Sort tag page operations: /api/v3 first, /api/v2 second, legacy paths last - Render x-compatibility-version badges (v1/v2) on operation headers - Fix BearerAuthentication displaying as raw identifier on v3 auth pages

…cation display - Fix hugo-template-dev skill: remove nonexistent api-rapidoc.ts, add _api-operations.scss, add api-docs/README.md reference - Fix content-editing skill: correct API test sentinel path (reference/api → api) - Fix security-schemes.html: add BearerAuthentication display name mapping

Configure Hugo dev server (port 1313) and test server (port 1315) for Claude Preview integration.

…pi-uplift # Conflicts: # PLAN.md # PLATFORM_REFERENCE.md # api-docs/influxdb3/core/influxdb3-core-openapi.yaml # api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml

jstirnaman marked this pull request as draft December 11, 2025 23:45

jstirnaman added Feature-WIP Feature is still a work in progress and is not yet merged. API labels Dec 11, 2025

jstirnaman added this to the API reference uplift milestone Dec 11, 2025

jstirnaman marked this pull request as ready for review December 12, 2025 17:41

jstirnaman mentioned this pull request Dec 12, 2025

chore(api-ref): Uplift API reference docs: #5595

Closed

jstirnaman force-pushed the feat-api-uplift branch from 3c7ad96 to 4fccddc Compare December 29, 2025 21:24

jstirnaman pushed a commit that referenced this pull request Jan 1, 2026

Merge PR #6622 changes to fix API template issue

24843d8

jstirnaman added 15 commits January 2, 2026 16:41

chore: Update build:api-docs script to use new generator

29bfeb5

- yarn build:api-docs: Generate API docs for all products - yarn build:api-docs cloud-v2: Generate for specific product - yarn build:api-docs:compile: Recompile TypeScript if modified

chore(claude): Add claude skill for Hugo development/testing workflow…

e282e03

…. Split ui-dev subagent into hugo-, ts-, and testing-specific agents.

chore(claude): Update ui-testing agent and hugo-template-dev skill

a7dff61

feat(api): Update OpenAPI article generators for tag-based structure

eb33772

- Add support for tag-based article generation with operations metadata - Generate articles.yml data files with tag, menuName, and isConceptual fields - Include operations array in frontmatter for tag pages

test(api): Update Cypress tests for API reference pages

9c2e276

- Update tests for new tag-based API page structure - Add tests for operations list rendering - Add tests for sidebar navigation groups

chore: Rebuild API generator scripts and update tests

f5fba5a

jstirnaman added 4 commits March 16, 2026 18:07

fix(api-docs): restyle Ask AI as a button for better contrast

d2e9ba5

Replace faint link with a small bordered button that has good contrast in both light and dark modes.

fix(api-docs): remove stale tags-landing pages that crash Hugo rebuild

b7c21a3

These v2/cloud tags pages use an old layout that causes Hugo to panic during live rebuilds when generated API content is present.

Revert "fix(api-docs): restyle Ask AI as a button for better contrast"

47c4e8a

This reverts commit d2e9ba5.

jstirnaman mentioned this pull request Mar 17, 2026

Complete Task 8: Split Cache data tags in InfluxDB 3 Enterprise #6909

Closed

3 tasks

github-actions bot mentioned this pull request Mar 19, 2026

[repo-status] 📊 Daily Repo Status - March 19, 2026 #6966

Closed

jstirnaman mentioned this pull request Mar 22, 2026

feat(influxdb3): update scripts to reference renamed API spec files #6907

Closed

jstirnaman added 4 commits March 29, 2026 21:16

Merge branch 'clean-squash' into feat-api-uplift

118a1c3

Brings in tag alignment, multi-spec sidebar, Cloud Serverless cleanup, data path restructuring, and data-driven Cypress tests.

Merge remote-tracking branch 'origin/master' into feat-api-uplift

ced1db3

# Conflicts: # .github/workflows/doc-review.yml # AGENTS.md # PLAN.md # assets/js/content-interactions.js # data/products.yml

fix(test): disable Hugo fast render to avoid nil walk context panic

374f4c1

Hugo 0.157.0 panics with "nil walk context" during fast render rebuild when generated API content pages are present. Use --disableFastRender for the Cypress test server to avoid this.

This was referenced Mar 30, 2026

feat(api): implement shared OpenAPI schemas for Core and Enterprise #6687

Closed

refactor(api-docs): consolidate v1 and Enterprise v1 API reference with Hugo-native spec-based pages #7009

Open

jstirnaman added 8 commits March 30, 2026 09:17

chore: add Claude Preview launch.json for dev servers

d6e5a56

Configure Hugo dev server (port 1313) and test server (port 1315) for Claude Preview integration.

Merge branch 'master' into add-dev-launch-json

0114e10

Merge remote-tracking branch 'origin/add-dev-launch-json' into feat-a…

1575a85

…pi-uplift # Conflicts: # PLAN.md # PLATFORM_REFERENCE.md # api-docs/influxdb3/core/influxdb3-core-openapi.yaml # api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml

Merge branch 'master' into feat-api-uplift

aad192f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate API reference docs to Hugo-native for improved site integration#6622

Migrate API reference docs to Hugo-native for improved site integration#6622
jstirnaman wants to merge 220 commits intomasterfrom
feat-api-uplift

jstirnaman commented Dec 11, 2025 •

edited

Loading

Uh oh!

jstirnaman commented Dec 12, 2025

Uh oh!

github-actions bot commented Dec 29, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Dec 29, 2025 •

edited

Loading

Uh oh!

jstirnaman commented Dec 31, 2025

Uh oh!

jstirnaman commented Dec 31, 2025 •

edited

Loading

Uh oh!

jstirnaman commented Jan 2, 2026

Uh oh!

github-actions bot commented Mar 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

jstirnaman commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API reference uplift

Hugo-native layout

Inline curl examples

Ask AI integration

Related links

Visual improvements

Build and generation

Uh oh!

jstirnaman commented Dec 12, 2025

Code review

Uh oh!

github-actions bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 PR Preview — Preview Bot

Uh oh!

jstirnaman commented Dec 31, 2025

Uh oh!

jstirnaman commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jstirnaman commented Jan 2, 2026

Uh oh!

github-actions bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Style Check Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jstirnaman commented Dec 11, 2025 •

edited

Loading

github-actions bot commented Dec 29, 2025 •

edited

Loading

github-actions bot commented Dec 29, 2025 •

edited

Loading

jstirnaman commented Dec 31, 2025 •

edited

Loading

github-actions bot commented Mar 30, 2026 •

edited

Loading