Feat api uplift #6622

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%

Remove ~230 lines of inline JavaScript and use the new api-rapidoc TypeScript component via data-component attribute instead.

Remove unused Scalar API documentation renderer: - Delete layouts/partials/api/scalar.html - Delete assets/js/components/api-scalar.ts - Simplify renderer.html to only use RapiDoc - Remove ApiScalar from main.js component registry - Remove apiRenderer config option from hugo.yml

Remove unused tabs component and partials: - Delete assets/js/components/api-tabs.ts - Delete layouts/partials/api/tabs.html - Delete layouts/partials/api/tab-panels.html - Remove ApiTabs from main.js component registry The new architecture renders content directly without tabs.

Remove tests for tabs and 3-column layout that no longer exist. Keep basic API reference tests and RapiDoc Mini component tests.

EXPERIMENTAL FINDINGS (Task 4): Tested RapiDoc's allow-authentication attribute with both render-style options to determine if it can show credential input on operation pages. Results: 1. render-style='read' + allow-authentication='true': - Auth section (#auth) exists in shadow DOM with input fields - BUT filtered out by match-paths (not visible to users) - Only matched operation shown, not full spec 2. render-style='focused' + allow-authentication='true': - Auth section completely removed from shadow DOM - Shows broken links to non-existent #auth section - Lists security schemes but no input fields CONCLUSION: RapiDoc's built-in auth UI is incompatible with match-paths filtering. When filtering to single operations, the auth section is either hidden or removed entirely. RECOMMENDATION: Implement custom auth input component (Task 5) using: - Custom TypeScript component above RapiDoc - sessionStorage for credential persistence - Integration with RapiDoc's Try it feature Code includes detailed inline documentation of findings for future reference when implementing Task 5.

- Create api-auth-input.ts TypeScript component - Store credentials in sessionStorage (secure, cleared on tab close) - Register component in main.js - Add auth form styling with dark theme support - Add component wrapper to rapidoc-mini.html template - Fix SCSS dark theme (use CSS selectors, not non-existent mixin)

- Set global security to BearerAuthentication only (best practice) - Add per-operation security to v1 endpoints (all 4 auth schemes) - Add per-operation security to v2 endpoint (Bearer + Token) - Add no-auth option for initial token creation endpoint - Fix TOC sidebar to include security scheme headings (move id to h3) - Update Authentication tag table to accurately describe endpoint support

- Convert collapsible auth panel to popover UI triggered by "Set credentials" button positioned above RapiDoc - Filter auth schemes based on API path: - /api/v3/* endpoints: Bearer only - /api/v2/* endpoints: Bearer + Token - /write, /query (v1): All 4 schemes - Fix "Authentication Not Required" bug by adding global security field to path-specific OpenAPI specs - Change RapiDoc --blue CSS variable to green so status text and type links don't look like clickable links - Add explicit button styling for Apply/Clear in popover - Hide RapiDoc's built-in auth section (use custom popover instead)

#6614) * chore(claude): Add claude skill for Hugo development/testing workflow. Split ui-dev subagent into hugo-, ts-, and testing-specific agents. * chore(claude): Update ui-testing agent and hugo-template-dev skill * docs(plans): add docs-cli-workflow skill design Design for a Claude Code skill that guides when to use docs create/edit CLI tools versus direct file editing. * feat(claude): add docs-cli-workflow skill Guides Claude to suggest docs create/edit CLI tools when appropriate: - Keyword-triggered activation (new page, edit URL, etc.) - Decision matrix for create vs edit vs direct editing - Suggestion templates with user confirmation - Edge case handling Addresses under-utilization of CLI scaffolding tools. * chore(claude): add console error testing pattern to hugo-template-dev skill Add Cypress pattern for catching JavaScript console errors during component testing - useful for runtime errors, JSON parsing failures, and template data binding issues.

When PR preview builds use a subdirectory baseURL like /docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink to detect product context fail because the path has extra segments. This fix: - Adds config/pr-preview/params.yml with prPreviewPathOffset: 3 - Updates workflow to use -e pr-preview environment - Updates api-endpoint, influxdb/host, and children shortcodes to use the offset when indexing path segments - Adds nil-safety with default fallback for placeholder_host Normal builds are unaffected (offset defaults to 0).

Design for transforming /influxdb/version/ placeholders in OpenAPI spec descriptions to product-specific paths at build time.

Transform /influxdb/version/ placeholders in OpenAPI spec description and summary fields to product-specific paths at build time. - Add deriveProductPath() to extract product path from spec location - Add transformDocLinks() to recursively transform markdown links - Add validateDocLinks() with --validate-links CLI flag for checking - Integrate transformation into processProduct() workflow - Add placeholder links to Authorization header descriptions The product path is derived from the spec file location, so api-docs/influxdb3/core/v3/ref.yml produces /influxdb3/core paths.

Add showSecuritySchemes field to Article interface and automatically set it to true for Authentication tag pages. This ensures the Security Schemes section renders on authentication pages after API docs are regenerated.

Add showSecuritySchemes field handling to generate-openapi-articles.ts to ensure the flag is written to content frontmatter. Regenerate API docs for cloud-dedicated and clustered products.

Auth credentials: - Switch from in-memory to sessionStorage for credentials - Credentials persist across page navigations within browser tab - Auto-clear when tab closes (no long-term storage) - Pre-fill form fields with saved credentials on page load - Update status text and button based on credential state Styling fixes: - Add right padding to code blocks so Copy button doesn't overlap content - Make long URLs wrap instead of requiring horizontal scroll - Hide TOC sidebar when no headings exist (e.g., quick-start page) - Remove "Use RapiDoc's navigation..." message from TOC API docs: - Remove x-codeSamples from write_lp endpoints (Core and Enterprise) - Add schema descriptions for line protocol request body

Fixed two issues causing Hugo warnings about duplicate menu entries: 1. Path generation bug: apiPathToSlug returns 'api/v3/...' for paths starting with '/api/', but the generator always prepended 'api/', creating 'api/api/v3/...' paths. Fix: Only add 'api/' prefix if path doesn't already start with it. 2. Config inconsistency: cloud-dedicated, cloud-serverless, and clustered had '/api' in pagesDir while core/enterprise didn't. The function always adds '/api', causing double prefixes for some products. Fix: Removed '/api' from pagesDir for affected products to match core/enterprise pattern.

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.

* fix(api): refine .IsSection check to prevent breaking endpoint pages The previous commit added an .IsSection check that correctly fixed section index pages but inadvertently broke endpoint pages that Hugo classifies as sections. This commit refines the conditional to check for the absence of the staticFilePath parameter, which distinguishes true section index pages from endpoint pages that need the RapiDoc renderer: - Section pages (no staticFilePath): Show children listing - Endpoint pages (with staticFilePath): Use RapiDoc renderer Fixes the regression introduced in commit 59daf17. * chore: update Scalar references to RapiDoc in comments Update code comments and documentation to accurately reflect that the API documentation uses RapiDoc, not Scalar: - api-docs/scripts/generate-openapi-articles.ts: Update JSDoc comments - api-docs/scripts/dist/generate-openapi-articles.js: Update compiled version - assets/js/components/api-toc.ts: Update implementation comment - .claude/agents/ts-component-dev.md: Update component reference - .claude/skills/hugo-template-dev/SKILL.md: Update component reference The implementation uses RapiDoc throughout, so these comments needed to be corrected for accuracy. --------- Co-authored-by: Claude <noreply@anthropic.com>

- 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

- 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

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 and others added 29 commits January 2, 2026 16:42

feat(api): Register api-rapidoc component in main.js

dcddc05

refactor(api): Replace inline JS with data-component in rapidoc.html

f882370

Remove ~230 lines of inline JavaScript and use the new api-rapidoc TypeScript component via data-component attribute instead.

test(api): Remove deprecated tab-related tests

efcae76

Remove tests for tabs and 3-column layout that no longer exist. Keep basic API reference tests and RapiDoc Mini component tests.

feat(api): Add security-schemes partial for OpenAPI spec rendering

f074d22

feat(api): Display security schemes on conceptual API pages

82ec8ef

style(api): Add security schemes section styling

3e6ce64

docs(api): add OpenAPI link processing design

4369a86

Design for transforming /influxdb/version/ placeholders in OpenAPI spec descriptions to product-specific paths at build time.

fix(api): Remove duplicated Authentication section

d258fa5

chore: remove openapi-link-processing design doc from tracking

31d9bfc

fix(api): add showSecuritySchemes to Authentication pages

a392b95

Add showSecuritySchemes field to Article interface and automatically set it to true for Authentication tag pages. This ensures the Security Schemes section renders on authentication pages after API docs are regenerated.

fix(api): propagate showSecuritySchemes to content generation

64c3d7b

Add showSecuritySchemes field handling to generate-openapi-articles.ts to ensure the flag is written to content frontmatter. Regenerate API docs for cloud-dedicated and clustered products.

feat(api): improve parent index pages with intro and children listing

e841ae1

chore: remove design files

ed65fb4

fix(api): improve API section index children display

149b9c0

- 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

jstirnaman force-pushed the feat-api-uplift branch from e128c61 to 216795f Compare January 2, 2026 22:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat api uplift #6622

Feat api uplift #6622

Uh oh!

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!

2 participants

Feat api uplift #6622

Are you sure you want to change the base?

Feat api uplift #6622

Uh oh!

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!

2 participants

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