Feat api uplift by jstirnaman · Pull Request #6622 · influxdata/docs-v2

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

API reference uplift:

Improved integration with site, metadata, navigation
Improved look and feel
Improved performance
New right sidebar with in-page nav

Latest screenshot:

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-01-02 22:46 UTC

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

PR Preview

Status	Details
Preview	View preview
Pages	2 page(s) deployed
Build time	72s
Last updated	2026-01-02 22:46:30 UTC

Pages included in this preview

/influxdb3/core/reference/api/
/influxdb3/enterprise/reference/api/

_{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%

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.

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"

- Update Authentication tag to cover both token types (management + database) - Update Quick start to cover complete workflow (setup → write → query) - Add dual download buttons on API landing pages - Add context-aware download buttons on tag pages - Remove old v2 HTML pages and duplicate auth directories - Clean up management API specs (remove duplicate auth tags) Part of API reference migration from Redoc to RapiDoc.

- Replace /api/management/ links with appropriate alternatives - Link to Database tokens API for token creation - Use "Management operations" text instead of broken links - Update Quick start to link to Databases API

- Add x-influxdatadocs-related support in TypeScript for tags and operations - Remove inline "Related guides" sections from OpenAPI descriptions - Move related links to structured x-influxdatadocs-related arrays - Add weight support for Quick start pages (weight: 1) to appear first in nav - Update clustered and cloud-dedicated v2/ref.yml specs

- Replace #operation/OperationId links with page-based URLs (e.g., #operation/GetLegacyQuery → /influxdb3/clustered/api/query-data/) - Fix Quick start menu ordering by sorting nav items by weight - Add default weight (100) to all articles for consistent sorting - Quick start gets weight 1 to appear first in navigation

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.

…che last value

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

Remove all RapiDoc-specific code from styles and JavaScript: - Delete rapi-doc::part() CSS selectors from _api-layout.scss - Delete dead auth modal styles from _api-security-schemes.scss - Delete api-auth-input.ts component (RapiDoc "Try it" integration) - Delete static/css/rapidoc-custom.css (unused) - Remove setupRapiDocNavigation() from api-toc.ts - Update comments to remove RapiDoc references Rename _api-hugo-native.scss to _api-operations.scss since Hugo-native is now the standard (not a POC).

Design for --clean/--no-clean/--dry-run flags in generate-openapi-articles.ts to prevent stale files when tags are renamed or removed.

10 bite-sized tasks for implementing --no-clean and --dry-run flags in generate-openapi-articles.ts.

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 ui 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 25 commits February 6, 2026 10:59

fix(api): align dual download button SVGs and styles with single.html

41b23f5

fix(api): add context-aware download buttons for dual-API products

89c6281

fix(api): remove old management API links from Authentication

36ee286

- Replace /api/management/ links with appropriate alternatives - Link to Database tokens API for token creation - Use "Management operations" text instead of broken links - Update Quick start to link to Databases API

fix: openapi-paths-to-hugo-data

17301e0

refactor(api): split Cache data tag into Cache distinct values and Ca…

22cf3a7

…che last value

docs(plan): add Hugo-native API migration plan with workflow fixes

3c580d3

style(test): apply lint fixes to API reference tests

242989b

docs(plan): add API clean regeneration design

74e0de7

Design for --clean/--no-clean/--dry-run flags in generate-openapi-articles.ts to prevent stale files when tags are renamed or removed.

docs(plan): add API clean regeneration implementation plan

c37a47b

10 bite-sized tasks for implementing --no-clean and --dry-run flags in generate-openapi-articles.ts.

feat(api): add --no-clean and --dry-run CLI flags

91bdc16

feat(api): add getCleanupPaths function

ef97d21

feat(api): add cleanProductOutputs function

33705b8

feat(api): add showDryRunPreview function

70e9f18

feat(api): integrate cleanup into processProduct

299631e

feat(api): add dry-run mode to main function

f79e108

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 broken API and process 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat api uplift#6622

Feat api uplift#6622
jstirnaman wants to merge 142 commits intomasterfrom
feat-api-uplift

jstirnaman commented Dec 11, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jstirnaman commented Dec 11, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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