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-03-08 05:27 UTC

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

PR Preview

Status	Details
Preview	View preview
Pages	50 page(s) deployed
Build time	62s
Last updated	2026-03-08 05:27:34 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/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/
/influxdb/v2/reference/internals/metrics/
... 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%

# Conflicts: # .github/copilot-instructions.md # layouts/shortcodes/latest-patch.html

- 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.

The server-rendered TOC path returned early without setting up the IntersectionObserver, so the is-active class was never applied to TOC links during scroll. Extract entry IDs from pre-rendered links and pass them to setupScrollHighlighting.

…ion design Covers 4 phases: inline curl examples from OpenAPI specs, response body schema rendering, Ask AI on code blocks, and client library integration with tabbed language samples for write/query operations. https://claude.ai/code/session_01P1FJ4g1aQmSmQAH9BCmKZr

…QO' into docs-v2-pr6622

Generate curl examples at Hugo template time from OpenAPI specs, with server URL variable resolution, $ref handling, and JSON body generation from schema properties. Add "Ask AI about this example" links using existing Kapa integration. Add client library related link to all InfluxDB 3 API tag pages. Improve visual separation between operations with distinct badge colors and response body indentation.

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

Position the Ask AI link in a footer bar below the code sample instead of overlaying it on the code block. Use site theme colors instead of hardcoded values.

- Move Ask AI link to header bar alongside Example request title - Use theme-aware variables for code block backgrounds and colors - Fix schema example blocks: separate header bar from code content - Normalize description font sizes to inherit page base size - Keep inline code font-size proportional with font-size: inherit - Widen API content wrapper to match regular article width (~850px) - Remove TOC border-left at compressed viewport widths (1281-1535px)

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

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 2 commits February 18, 2026 19:54

docs(api): update script header with new flags

237630f

build(api): rebuild compiled generation scripts

ff8a63a

jstirnaman mentioned this pull request Feb 25, 2026

fix (influxdb3): broken API reference and processing engine documentation paths #6862

Draft

docs(plan): mark Task 7 (clean regeneration) as completed

91a7299

jstirnaman requested a review from a team as a code owner February 27, 2026 05:15

jstirnaman requested review from sanderson and removed request for a team February 27, 2026 05:15

jstirnaman removed ui labels Mar 4, 2026

sanderson approved these changes Mar 6, 2026

View reviewed changes

jstirnaman and others added 6 commits March 6, 2026 12:12

Merge remote-tracking branch 'origin/master' into docs-v2-pr6622

f58abb6

# Conflicts: # .github/copilot-instructions.md # layouts/shortcodes/latest-patch.html

Merge remote-tracking branch 'origin/claude/api-code-samples-plan-MEk…

895d560

…QO' into docs-v2-pr6622

jstirnaman requested a review from Copilot March 8, 2026 05:26

Copilot AI reviewed Mar 8, 2026

View reviewed changes

jstirnaman added 3 commits March 9, 2026 21:47

task(plans): organize

32b64f3

style(api): move Ask AI link below code block with theme-aware styling

f061004

Position the Ask AI link in a footer bar below the code sample instead of overlaying it on the code block. Use site theme colors instead of hardcoded values.

jstirnaman changed the title ~~Feat api uplift~~ Migrate API reference docs to Hugo-native for improved site integration Mar 16, 2026

This was referenced Mar 16, 2026

feat(api-docs): add externalDocs, strip absolute URLs, fix link pipeline #6953

Closed

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

Closed

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

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

Open

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 152 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!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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