fix(ci): add path offset for PR preview subdirectory baseURL#6665
Merged
jstirnaman merged 3 commits intomasterfrom Dec 22, 2025
Merged
fix(ci): add path offset for PR preview subdirectory baseURL#6665jstirnaman merged 3 commits intomasterfrom
jstirnaman merged 3 commits intomasterfrom
Conversation
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).
Contributor
PR PreviewPreview skippedNo pages to preview (content removed) Checked: 2025-12-22 16:13:52 UTC |
jstirnaman
added a commit
that referenced
this pull request
Dec 22, 2025
Apply the same prPreviewPathOffset fix to product-name.html and sidebar.html that was applied in the initial PR #6665. These templates parse RelPermalink to detect product context, but when baseURL includes a subdirectory path (e.g., /docs-v2/pr-preview/pr-XXXX/), the path indices shift. This fix uses the configurable offset to skip extra path segments in PR preview builds.
3 tasks
jstirnaman
added a commit
that referenced
this pull request
Dec 22, 2025
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).
jstirnaman
added a commit
that referenced
this pull request
Dec 22, 2025
* fix(ci): add path offset for PR preview subdirectory baseURL 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). * fix(ci): add path offset to product-name and sidebar for PR previews Apply the same prPreviewPathOffset fix to product-name.html and sidebar.html that was applied in the initial PR #6665. These templates parse RelPermalink to detect product context, but when baseURL includes a subdirectory path (e.g., /docs-v2/pr-preview/pr-XXXX/), the path indices shift. This fix uses the configurable offset to skip extra path segments in PR preview builds. * fix(ci): skip PR preview for fork PRs and add notice comment Fork PRs cannot deploy to gh-pages because GITHUB_TOKEN has read-only access to the base repository. This is a GitHub security feature. Changes: - Add condition to skip preview job for fork PRs - Add fork-notice job to post helpful comment explaining limitation - Include local preview instructions for contributors
jstirnaman
added a commit
that referenced
this pull request
Dec 29, 2025
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).
jstirnaman
added a commit
that referenced
this pull request
Jan 2, 2026
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).
jstirnaman
added a commit
that referenced
this pull request
Apr 20, 2026
…on (#6622) * feat(api): Uplift API reference docs with Scalar renderer 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] * fix(shortcodes): Fix Hugo 0.134 compatibility issues - 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. * chore: Update build:api-docs script to use new generator - 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. Split ui-dev subagent into hugo-, ts-, and testing-specific agents. * fix(api): Add operations list styling and regroup sidebar navigation - 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 * chore(claude): Update ui-testing agent and hugo-template-dev skill * feat(api): Update OpenAPI article generators for tag-based structure - 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 * feat(api): Update Hugo layouts for tag-based API documentation - 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 * feat(api): Add TypeScript components for API UI interactions - 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 * feat(api): Add article data files and sidebar navigation partial - 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 * feat(api): Update config, styles, and content for API docs uplift - 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 * test(api): Update Cypress tests for API reference pages - 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 * fix(api): Extract first sentence for header summary, add Overview section - 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 * fix(api): Show operations in sidebar nav, fix CSS for menu and summary - 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% * fix(api): Match sidebar nav font sizes for operation items - Changed operation link font-size from 0.85rem to 0.95rem to match sidebar - Changed path code font-size from 0.75rem to 0.85rem for consistency - Adjusted method badge font-size from 0.55rem to 0.6rem for readability * fix(api): Reset button styles for dark mode, increase operation font size - Add button reset styles to .api-nav-group-header for dark mode compatibility (background: none, border: none, width: 100%) - Increase operation link font-size from 0.95rem to 1rem to match sidebar nav-item font size (18px base) - Increase api-path code font-size from 0.85rem to 0.9rem * feat(api): Integrate API navigation into Hugo menu system Add API nav items as children of "InfluxDB HTTP API" menu item: - New api-menu-items.html partial generates nav from data/articles.yml - Modified nested-menu.html to inject API nav for API parent menu item - Updated api_nav_groups.yml to add url for Administration group - Created Administration landing pages for Core and Enterprise - Updated .gitignore to allow hand-crafted API conceptual pages The Administration page uses layout: list and isConceptual: true to render content directly without RapiDoc wrapper. * refactor(api): Remove unused separate API nav code Now that API navigation is integrated into Hugo's menu system: - Remove api-nav.ts component (no longer needed) - Remove api/sidebar-nav.html partial (replaced by api-menu-items.html) - Remove api-nav component registration from main.js - Update sidebar.html to pass siteData to nested-menu for API nav - Fix anchor ID handling for special characters (like / in operation IDs) * refactor(api): Flatten API nav groups to single-tag items Remove multi-tag groups (Administration, Concepts) and flatten to single-tag groups for direct linking. Each API tag now renders as a direct nav item instead of being nested under a parent group. - Update api_nav_groups.yml to use single-tag groups only - Delete Administration landing pages (not needed without nesting) - Improve SCSS styling for API nav visibility and active states * feat(api): Add compatibility version badges for v1/v2 endpoints Add visual badges to distinguish v1-compatible and v2-compatible API endpoints in the sidebar navigation. This helps users migrating from InfluxDB v1 or v2 quickly identify which compatibility layer each endpoint belongs to. Changes: - Add x-compatibility-version extension to compatibility operations - Add externalDocs links to reduce verbose descriptions in specs - Update generator to extract compatVersion and externalDocs fields - Display colored badges (purple for v1, cyan for v2) in sidebar nav - Strip redundant "(v1-compatible)" text when badge is shown - Add hover tooltips explaining compatibility context * feat(api): Add RapiDoc Mini component for API operation 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 * fix(api): Fix RapiDoc operation filtering and improve API reference quality - 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 * fix(api): Complete Auth token rename and remove Redoc x-tagGroups - Update api_nav_groups.yml to use "Auth token" instead of "Token" - Remove x-tagGroups from Core and Enterprise specs (Redoc-specific, not needed for RapiDoc) - Add migration notes to plan document for future product migrations * refactor(api): Simplify sidebar nav to sort by isConceptual, then alphabetically - Remove api_nav_groups.yml config file (no longer needed) - Update api-menu-items.html to derive order from article data - Sort: conceptual tags (traitTags) first, then other tags alphabetically - Reduces template from 255 to 152 lines * feat(api): Add section index and All endpoints nav item - 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) * style(api): Adjust All endpoints path font size to 0.9rem Increase font size from 0.55rem to 0.9rem for better readability while keeping the standard sans font for space efficiency. * feat(api): Create api-rapidoc TypeScript component Extract inline JavaScript from rapidoc.html into a proper TypeScript component following the established component pattern. * feat(api): Register api-rapidoc component in main.js * refactor(api): Replace inline JS with data-component in rapidoc.html Remove ~230 lines of inline JavaScript and use the new api-rapidoc TypeScript component via data-component attribute instead. * refactor(api): Remove Scalar renderer and related code 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 * refactor(api): Remove deprecated api-tabs component 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. * test(api): Remove deprecated tab-related tests 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 * feat(api): Display security schemes on conceptual API pages * style(api): Add security schemes section styling * feat(api): Experiment with auth input visibility on operation pages 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. * feat(api): Add custom auth input component for operation pages - 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) * feat(api): Add per-operation security definitions to OpenAPI specs - 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 * feat(api): Convert auth input to popover with filtered schemes - 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) * feat(claude): add docs-cli-workflow skill and update hugo-template-dev (#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. * fix(ci): add path offset for PR preview subdirectory baseURL (#6662) 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). * fix(ci): add path offset for PR preview subdirectory baseURL (#6665) 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). * docs(api): add OpenAPI link processing design Design for transforming /influxdb/version/ placeholders in OpenAPI spec descriptions to product-specific paths at build time. * fix(api): Remove duplicated Authentication section * feat(api-docs): add link placeholder transformation for OpenAPI specs 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. * chore: remove openapi-link-processing design doc from tracking * fix(api): add showSecuritySchemes to Authentication pages 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 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 auth UX with sessionStorage and fix styling issues 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 * fix(api-docs): resolve duplicate api/api paths and menu warnings 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. * feat(api): improve parent index pages with intro and children listing * chore: remove design files * fix(api): render children listing on API section index pages 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. * feat(api): Fix API reference tag-based section template (#6686) * 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> * fix(api): improve API section index children display - 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 * feat(api): normalize API paths with version prefixes - 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 * fix(api): improve RapiDoc mobile responsive layout Fix button cutoff on mobile screens by applying CSS fixes to RapiDoc's nested shadow DOMs. Changes: - Add getAllShadowRoots() to recursively find nested shadow roots (RapiDoc contains api-request elements with their own shadow DOMs) - Apply button fixes to all shadow roots, not just the top-level one - Add responsive CSS for endpoint cards to prevent horizontal overflow - Remove debug console.log statements Tested at viewport sizes 400x770 and 430x932. * feat(api): enable tag-based generation for cloud-dedicated Cloud Dedicated's management API uses paths like /accounts/{accountId}/... which can't be used directly as Hugo URLs (curly braces get stripped). Enable useTagBasedGeneration to group operations by OpenAPI tags instead (Authentication, Databases, Database tokens, etc.) matching the pattern used by influxdb3-core and influxdb3-enterprise. * feat(api): configure cloud-serverless for tag-based API generation - Fix specFile path from non-existent management/openapi.yml to v2/ref.yml - Enable useTagBasedGeneration for consistency with other InfluxDB 3 products - Update comments to clarify that Cloud Serverless uses standard v2 API (not management API like Cloud Dedicated and Clustered) Cloud Serverless API docs now generate 29 tag-based pages and 125 operation pages from the v2 API spec. * feat(api): add cloud-serverless API reference content Generated from v2/ref.yml OpenAPI spec: - 29 tag-based pages (buckets, write, query, tasks, etc.) - 125 individual operation pages - Article data in data/article_data/influxdb/cloud-serverless/ * feat(api): enable tag-based generation for clustered Add useTagBasedGeneration: true to clustered config to properly generate tag-based API documentation pages for the management API, consistent with cloud-dedicated and cloud-serverless configurations. * fix(api): remove curly braces from URL paths and clean up section pages - Fix apiPathToSlug() to strip curly braces from path parameters (e.g., {db} → db) to avoid URL encoding issues in Hugo - Update Quick start tag description to include intro sentence: "Authenticate, write, and query with the API:" - Remove {{< children >}} shortcode from API section _index.md files (layout's section-children.html partial already handles tag listing) - Delete old cloud-serverless API pages with curly braces in paths - Regenerate article data for all products * feat(api): add All endpoints page and fix v2 menu warnings - 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 * style: apply prettier formatting to scripts and tests * chore: update package.json and yarn.lock from origin/master * docs: add API path pages design document Design for generating path-level API pages instead of operation-level pages. Key changes: - URLs like /api/v3/configure/token/admin/ show all HTTP methods - Uses RapiDoc match-type=includes for path filtering - Improves SEO, UX, and reduces nav clutter * docs: add API path pages implementation plan Detailed step-by-step plan for replacing operation-level pages with path-level pages that show all HTTP methods per endpoint. * feat(api): add match-type support to RapiDoc Mini component Enables path-based filtering with match-type='includes' to show all HTTP methods for an API path on a single page. * feat(api): add path page layout for multi-method endpoints New layout shows all HTTP methods for an API path on one page with a methods TOC in the right sidebar. * feat(api): add RapiDoc path partial for multi-method rendering Uses match-type='includes' to show all HTTP methods for a path. * feat(api): replace operation pages with path pages Groups operations by API path instead of creating one page per method. Each path page shows all HTTP methods using RapiDoc with match-type='includes'. - Renamed generateOperationPages to generatePathPages - Changed type from 'api-operation' to 'api-path' - Changed layout from 'operation' to 'path' - Groups multiple HTTP methods under same path into single page - Sorts operations by method order: GET, POST, PUT, PATCH, DELETE - Collects related links from all operations on the path * fix(api): update tag page links to use path URLs with anchors Links now point to /api/v3/path/#method instead of /api/v3/path/method/ * fix(api): update all-endpoints links to use path URLs with anchors * chore(api): remove operation layout (replaced by path layout) * chore(api): update compiled generation script * fix(api): correct all-endpoints links to use path URLs with anchors * test(api): update tests for path-based API pages - Update operation page URLs to path page URLs - Add test for data-match-type='includes' attribute - Update href pattern to match path URLs with method anchors * docs: add API tag pages design document * feat(api): consolidate API docs to tag pages with inline operations Migrate API documentation from individual operation pages to tag pages where all operations for a tag are rendered inline using RapiDoc. Key changes: - Remove operation links from left sidebar (tags only, no children) - Generate server-side TOC from frontmatter operations array - Show method badge + human-readable summary in TOC (not paths) - Support hash-based navigation (#post-/api/v3/configure/distinct_cache) - RapiDoc scrollToPath() handles TOC clicks to shadow DOM elements - goto-path attribute initializes to operation from URL hash - update-route attribute updates URL hash as user navigates Files created: - layouts/partials/api/rapidoc-tag.html Files removed: - layouts/api-path/path.html (path page layout) - layouts/partials/api/rapidoc-path.html (path page partial) - Old design documents superseded by 2026-01-21 version Files modified: - layouts/api/list.html (embed RapiDoc, server-side TOC) - layouts/api/section.html (simplified section layout) - layouts/_default/api.html (fallback layout cleanup) - layouts/partials/sidebar/api-menu-items.html (remove op children) - assets/js/components/rapidoc-mini.ts (tag page support) - assets/js/components/api-toc.ts (RapiDoc navigation) - api-docs/scripts/generate-openapi-articles.ts (disable path pages) * fix(api): fix sidebar HTML, rebuild compiled JS, update all-endpoints links Fixes: - Remove stray </li> tag in api-menu-items.html causing invalid HTML - Reformat minified sidebar template for maintainability - Rebuild compiled JS to sync generatePathPages disabled state - Update all-endpoints links to use tag page URLs with hash anchors (e.g., /api/cache-data/#post-/api/v3/configure/distinct_cache) instead of now-removed path pages * fix(api): improve tag descriptions and separate auth contexts - Add brief summary sentences to OpenAPI tag descriptions for better display in children lists (API compatibility, Authentication, Common parameters, Quick start) - Rename Management API "Authentication" to "Admin authentication (management operations)" to distinguish from data API authentication - Standardize "Quick start" tag naming (was "Quickstart" in some specs) - Regenerate article data for cloud-dedicated, clustered, cloud-serverless * fix(api): remove empty "Migrate from InfluxDB v1 or v2" tag page Remove the empty migrate tag page from Enterprise API docs. The tag had no operations and the migration content is covered by existing guides linked from other sections. * feat(api): add migration pages, remove Redoc links, standardize x-influxdata-related - Add get-started/migrate-from-influxdb-v1-v2.md pages for Core and Enterprise - Move migration link from info description to x-influxdata-related field - Remove all Redoc-style links (#operation/, #section/) from spec descriptions - Rename x-influxdata-guides to x-influxdata-related throughout - Update Core info description to match Enterprise format - Regenerate article data for both products * feat(api): enhance OpenAPI article generation scripts - Add tag-based article generation with operation grouping - Support x-influxdata-related field for related content links - Improve spec transformation with documentation link handling - Add JSON output alongside YAML for article data - Enhance path and tag spec generation for per-operation pages * feat(api): update API layouts and UI components - Enhance section-children partial for tag-based article display - Update all-endpoints-list with improved operation linking - Refine security-schemes partial layout - Update api-toc.ts for better navigation handling - Improve api-menu-items sidebar rendering - Update security schemes SCSS styling - Remove outdated LLMS-TXT-README.md * feat(api): add api_path and alt_link_key to products.yml Add new fields to product definitions for API documentation: - api_path: URL path to the API reference section - alt_link_key: Short key for cross-product linking * fix(api): normalize Quick start tag name across products - Standardize tag name to "Quick start" (two words) in tag-groups.yml - Update .config.yml for cloud-dedicated and clustered products * chore(api): update v2 products specs and article data - Update cloud-v2 and oss-v2 OpenAPI ref.yml specs - Regenerate article data for both v2 products * refactor(api): remove old reference/api index pages Remove legacy API reference index pages that have been superseded by the new tag-based API documentation structure. * style(api): apply prettier formatting to compiled JS * style(api): apply prettier formatting to TypeScript source * feat(api): add InfluxDB v1 API reference specs Add OpenAPI specs for InfluxDB v1 APIs: - api-docs/enterprise_influxdb/v1/v1/ref.yml - api-docs/influxdb/v1/v1/ref.yml * refactor(api): generate article_data at build time instead of tracking - Add data/article_data/ to .gitignore - Integrate generate-openapi-articles into generate-api-docs.sh - Remove tracked article_data files (now generated at build time) This avoids large data file diffs in PRs and ensures article data stays in sync with OpenAPI specs. * fix(docs): replace invalid page-link shortcode with markdown links * chore: add enterprise_influxdb API pages to gitignore * fix(api): Update product references to use full product names in API docs * docs(api): add API link migration design for RapiDoc anchors * docs(api): add API link migration implementation plan * feat(api): add migration script skeleton * feat(api): add operationId lookup table generation * feat(api): add content file scanner for operation links * feat(api): complete migration script with replacement logic * refactor(api): migrate operation links to RapiDoc anchor format Migrated 171 links across 83 files from #operation/{operationId} to #{method}-{path} format for RapiDoc compatibility. 71 links in shared content using /version/ placeholder require separate handling (expected - these use Hugo templating). * refactor(api): migrate shared content operation links to RapiDoc format - Updated migration script to handle /version/ placeholder URLs - Fixed GetQuerySql typo to GetExecuteQuerySQL in enterprise tables list - Migrated 71 links across 32 shared content files Total migration: 242 links across 115 files (171 + 71) * fix(v1): correct malformed API anchor link for bucket retrieval * fix(api): correct malformed RapiDoc anchor links with path parameters Fix anchors that were missing slashes around path parameters: - authorizationsID → authorizations/-authID- - runsIDRetry → runs/-runID-/retry - runsIDLogs → runs/-runID-/logs - scriptsIDInvoke → scripts/-scriptID-/invoke * feat(api): add v1 API overlay support and remove tag-groups Add Redocly overlay pattern for InfluxDB v1 OSS and Enterprise APIs, making them consistent with other products in the repository. Changes: - Create .config.yml and content overlays (info.yml, servers.yml) for both influxdb/v1 and enterprise_influxdb/v1 - Add updateOSSV1() and updateEnterpriseV1() functions to getswagger.sh - Remove set-tag-groups decorator and all tag-groups.yml files The tag-groups feature was a Redoc-specific workaround for navigation grouping that is no longer needed with the Hugo/RapiDoc architecture. * fix(api): use full product name in cloud-serverless API compatibility docs Replace generic "InfluxDB 3" references with "InfluxDB Cloud Serverless" for clarity and consistency with product naming conventions. * docs(api): add design for Clustered/Cloud Dedicated API structure Unified API documentation with: - Single nav combining Data API and Management API tags - Dual download buttons on landing page - Unified Authentication page covering both token types - Cleanup of old v2 HTML pages and duplicate auth directories * docs(api): update Authentication tags to cover both token types in Data API specs Add comprehensive authentication documentation that explains: - Token types table (Management token vs Database token) - Authentication schemes table with token type, endpoints, and header format - Links to Management API authentication for management token usage Updated in both Clustered and Cloud Dedicated Data API specs. * docs(api): update Quick start tag in Data API specs with complete workflow Update the Quick start section in Clustered and Cloud Dedicated Data API specs to cover the full getting started flow including: - Creating a management token via influxctl - Creating a database via Management API - Creating a database token via Management API - Writing data via Data API - Querying data via Flight or HTTP API * feat(api): add dual download buttons for Clustered/Cloud Dedicated 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. * fix(api): align dual download button SVGs and styles with single.html * fix(api): add context-aware download buttons for dual-API products * fix(api): use reliable path extraction for dual download buttons 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" * feat(api): unified API structure for Clustered and Cloud Dedicated - 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. * fix(api): remove old management API links from Authentication - 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 * refactor(api): move Related guides to x-influxdatadocs-related field - 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 * fix(api): replace Rapidoc links with page URLs, fix nav ordering - 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 * fix: openapi-paths-to-hugo-data * feat(api): add Hugo-native API rendering POC 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. * refactor(api): split Cache data tag into Cache distinct values and Cache last value * docs(plan): add Hugo-native API migration plan with workflow fixes * refactor(api): complete Hugo-native migration, remove RapiDoc 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). * style(test): apply lint fixes to API reference tests * style(api): remove RapiDoc styles and rename hugo-native to operations 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). * docs(plan): add API clean regeneration design 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 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 * feat(api): add getCleanupPaths function * feat(api): add cleanProductOutputs function * feat(api): add showDryRunPreview function * feat(api): integrate cleanup into processProduct * feat(api): add dry-run mode to main function * docs(api): update script header with new flags * build(api): rebuild compiled generation scripts * docs(plan): mark Task 7 (clean regeneration) as completed * style(api): use Redocly anchor format and flatten operation layout - 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. * fix(api): add scroll highlighting to server-rendered TOC 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. * docs(plan): add API code samples, Ask AI, and client library integration 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 * feat(api): add inline curl examples and Ask AI links to API operations 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. * feat(influxdb3): rename API specs and add download links Rename Core and Enterprise OpenAPI spec files from ref.yml to descriptive names (influxdb3-core-openapi.yaml, influxdb3-enterprise-openapi.yaml). Copy specs to static/openapi/ and add download links in the API description. * Initial plan * fix: run API docs build in PR preview workflow for /api pages - Add detectApiPages() to detect-preview-pages.js to auto-map changed api-docs/ files to their content URL paths via .config.yml - Add has-api-doc-changes output to detect-preview-pages.js - Fix needs-author-input logic to not request input when API pages are already auto-detected - Add Build API docs step to pr-preview.yml that runs yarn run build:api-docs before the Hugo build when api-doc changes detected Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> * feat(api-docs): extract api-docs changes from feat-api-uplift Extract all api-docs/ changes from feat-api-uplift into a standalone branch for independent testing and merging to master. Changes include: - Updated generation scripts (generate-openapi-articles.ts, openapi-paths-to-hugo-data/index.ts) for Hugo-native templates - Removed dead x-tagGroups infrastructure (decorator, config files) - Updated Core and Enterprise specs with tag descriptions, x-related links, and Cache Data tag split - Added v1 product configs and specs (OSS v1, Enterprise v1) - Updated getswagger.sh for renamed spec files - Updated generate-api-docs.sh with clean regeneration support * task(plans): organize * chore(api-docs): remove dead x-tagGroups from all spec files Remove the x-tagGroups vendor extension from 8 remaining OpenAPI spec files. This Redocly extension was used for navigation grouping in the old RapiDoc layout but is ignored by the Hugo-native API templates, which generate pages from operation tags[] arrays. * style(api): move Ask AI link below code block with theme-aware styling 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. * style(api): refine code samples, schema examples, and layout width - 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) * feat(api-docs): add tag post-processor and per-product tags.yml configs Add apply-tag-config.ts that reads colocated tags.yml files and patches OpenAPI spec tags in place (descriptions, x-related links, renames). Runs between getswagger.sh and generate-openapi-articles.ts in the build pipeline. Create tags.yml for all 11 product specs: - Core, Enterprise: extracted from existing spec tag metadata - v2-compat, v2, v1: new descriptions and x-related links Include test suite (16 assertions) covering description setting, tag rename propagation, x-related links, stale/uncovered tag warnings, silent skip when no config, and malformed YAML failure. * refactor(api-docs): flatten version subdirectories for v2-compat and v1 products Drop redundant version subdirectories and use self-documenting filenames for 5 products: v2-compat influxdb3: cloud-dedicated/v2/ref.yml → cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml cloud-serverless/v2/ref.yml → cloud-serverless/influxdb3-cloud-serverless-openapi.yaml clustered/v2/ref.yml → clustered/influxdb3-clustered-openapi.yaml v1: influxdb/v1/v1/ref.yml → influxdb/v1/influxdb-oss-v1-openapi.yaml enterprise_influxdb/v1/v1/ref.yml → enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml Update .config.yml, getswagger.sh, and generate-openapi-articles.ts to reference new paths. * fix(api-docs): let docs-tooling spec values pass through for Core/Enterprise Strip title, version, description, license, and contact from Core and Enterprise info.yml overlays so the values from docs-tooling generated specs are preserved. Keep only x-influxdata-* fields used for Hugo page metadata. Fix set-info.cjs decorator to not blank version or summary when the overlay omits them — the old else branches would clear spec values that should pass through. * refactor(api-docs): replace tag-only processor with unified post-process-specs Extends the tag post-processor into a unified spec post-processor that also applies info.yml and servers.yml content overlays. This replaces two Redocly decorators (set-info, set-servers) with a single TypeScript script, moving toward removing the Redocly dependency. - Rename apply-tag-config.ts → post-process-specs.ts - Add info overlay support (merges fields from content/info.yml) - Add servers overlay support (replaces spec.servers from content/servers.yml) - Use same discovery convention as Redocly docs-content.cjs (API-specific first, product-level fallback) - Load spec once, apply all transforms, write once if modified - Skip Redocly postProcess for management specs in getswagger.sh (prevents unwanted $ref chain collapsing) - Restore management@0 API entries in cloud-dedicated and clustered configs - 13 tests, 41 assertions, all passing * refactor(api-docs): unify v2 APIs, remove v1-compat specs, migrate mgmt links Flatten Cloud v2 and OSS v2 spec directories to product root with self-documenting filenames, matching the pattern used for influxdb3 products. Remove all 5 v1-compatibility directories — those endpoints are already included in the main spec (tagged as v1/v2 Compatibility). Old v1-compat URLs are preserved as Hugo aliases for redirects. Also includes: - Migrate inline markdown links from management API spec descriptions into tags.yml x-related fields (Cloud Dedicated + Clustered) - Wire post-process-specs.ts into generate-api-docs.sh build pipeline - Fix doubled static/openapi download filenames - Update project plan with design decisions * refactor(api-docs): flatten v3 dirs, rewrite build pipeline, add --static-only mode - Flatten Core/Enterprise v3/ subdirectories to product root - Rewrite generate-api-docs.sh as clean 3-step pipeline: post-process-specs → Redoc HTML → static spec downloads - Add --static-only flag to generate-openapi-articles.ts - Remove circular getswagger.sh call from generate-openapi-articles.ts - Remove dead execCommand function and --skip-fetch flag - Apply post-processed tag enrichments to all spec files * fix(api-docs): skip clean step in --static-only mode The clean step was deleting committed content directories (e.g., enterprise_influxdb/v1/api/) when running in --static-only mode. Static-only should only copy specs to static/openapi/, not touch content directories. * fix(api-docs): exclude root .config.yml from Redoc HTML generation The find command in generate-api-docs.sh matched the Redocly root config (api-docs/.config.yml) which has no apis key, causing yq to fail with "cannot get keys of \!\!null". * fix(api-docs): add x-traitTag support to post-processor and tags.yml Add x-traitTag to TagConfig interface so the post-processor propagates it from tags.yml into specs. Mark all supplementary documentation tags (Authentication, Quick start, Headers, Usage, etc.) with x-traitTag: true so Redoc renders them as documentation sections with descriptions rather than empty operation groups. Also exclude root .config.yml from the Redoc HTML generation find command. * fix(api-docs): restore Redoc security scheme injection in Authentication tags Add ReDoc-Inject: <security-definitions> directive and scheme links to the Authentication tag description in all 9 tags.yml files. This renders the security scheme definitions inline in the Redoc HTML, matching the pre-uplift behavior. Each product lists its actual security schemes with anchor links to the scheme definitions section. * fix(api-docs): enforce one-tag-per-operation, fix Enterprise v1 spec - Remove dual tags from v2-compat operations in both v1 specs, add x-compatibility-version: v2 for Hugo-native badge rendering - Fix Enterprise v1 spec version 1.11.6 → 1.12.2 (spec, examples) - Add GET /shard-status endpoint to Enterprise v1 spec (was only in the legacy content page) - Document one-tag-per-operation convention in api-docs/README.md - Update api-docs.instructions.md for current file layout and pipeline - Add analyze-api-source agent for cross-product API docs analysis * fix(api-docs): split v2 Compatibility tag, fix auth descriptions and info.yml - Split generic "v2 Compatibility" tag into "Buckets (v2 compatible)" and "Delete (v2 compatible)" in both v1 specs and tags.yml - Rewrite Authentication tag descriptions: explain that auth is disabled by default, move explanation before security definitions - Fix broken markdown link in auth descriptions ([enabled in the configuration] had no URL) - Fix x-related format in both v1 tags.yml (flat object → list) - Fix Enterprise v1 x-related href to correct page path - Fix Cloud Dedicated info.yml indentation (broke YAML parsing) * refactor(api-docs): write resolved specs to _build/ instead of mutating source Post-process-specs.ts now writes resolved specs (with info, servers, and tag overlays applied) to api-docs/_build/ instead of back to source files. Downstream consumers (Redoc HTML generation, static spec copy) read from _build/. Source specs in api-docs/ are never mutated by the pipeline. This makes the pipeline idempotent — running it twice produces identical output — and keeps source spec diffs free of YAML re-serialization noise. * style(api-docs): format generate-openapi-articles.ts line lengths * fix(ci): add TypeScript build step for API documentation scripts generate-api-docs.sh now calls post-process-specs.js and generate-openapi-articles.js from api-docs/scripts/dist/, which requires compiling TypeScript first. The dist/ directory is gitignored, so CI must run tsc before generating API docs. * test(api-docs): align post-process outputs (#6942) - read assertions from _build artifacts instead of source specs\n- capture issue 6939 plan for follow-up steps\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(api-docs): use actual spec path in post-processor log labels Replace invented {productDir}/{apiKey} labels with the real spec path (e.g., influxdb/v1/influxdb-oss-v1-openapi.yaml instead of influxdb/v1/v1@1). * fix(ci): replace HTTP polling with commit status signaling for preview coordination pr-preview.yml now emits a `preview/deploy` commit status (pending/success/failure) so doc-review.yml can detect failures instantly instead of polling an HTTP URL for 10 minutes. Also centralizes the api-docs TypeScript build command in package.json and adds a lefthook pre-commit hook for api-docs script changes. * fix(ci): resolve merge conflict markers in detect-preview-pages.js Unresolved conflict markers caused SyntaxError on Node.js parse, which made the preview workflow skip page detection entirely. * fix(ci): use bash instead of sh for generate-api-docs.sh The script uses bash-specific syntax (function, local, [[ ]]), but package.json invoked it with sh. On Ubuntu CI runners sh is dash, which rejects function keyword. Matches the script's #\!/bin/bash shebang. * fix(api-docs): remove Enterprise v1 content pages from api-docs-only branch These Hugo content files belong on feat-api-uplift where the Hugo-native layout changes live. They were accidentally included when the initial api-docs/ diff was extracted. * fix(ci): delete stale visual review comment when no content pages remain The visual review job only runs when url-count > 0, so when content files are removed from a PR, the old comment was left orphaned. Add a cleanup job on the inverse condition to delete both the visual review and timeout comments. * refactor(api): replace hardcoded product configs with auto-discovery 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 * style(api): apply prettier formatting to generation scripts * fix(api-docs): restore full tag descriptions in Core and Enterprise tags.yml The original v3 specs had multi-paragraph descriptions for trait tags (Quick start, Headers and parameters, Migrate) and operation tags (Cache, Processing engine, Write data) with tables, code blocks, and structured content. The tags.yml files replaced these with one-liner summaries, which post-process-specs.ts then applied over the rich spec descriptions. Restore all descriptions to match the original spec content. * fix(api-docs): restore full tag descriptions for API compatibility and Supported operations Replace truncated "Overview of..." one-liners in tags.yml with proper descriptions: - API compatibility (Cloud Dedicated, Cloud Serverless, Clustered): restore multi-paragraph descriptions from origin/master specs covering write endpoints, query protocols, and v1/v2 compatibility. Move external doc links to x-related. - Supported operations (Cloud v2, OSS v2, Cloud Serverless): replace with reference-style descriptions and HTTP method convention table. * feat(api): Hugo-native API reference rendering Hugo-native templates for API reference documentation. Operations render as server-side HTML instead of client-side Redoc, providing faster page loads, full SEO indexability, and consistent styling. Architecture: - Tag-based navigation: operations grouped by OpenAPI tag, accessed via tag pages only (no individual operation URLs) - Generation script auto-discovers products from .config.yml files, deriving Hugo paths and menu keys from directory structure - Per-tag JSON/YAML chunks for fast Hugo template rendering - Inline curl examples generated from OpenAPI specs at build time Templates (layouts/api/, layouts/partials/api/): - tag-renderer.html: renders all operations for a tag - operation.html: individual operation with parameters, request body, responses, and schema rendering - code-sample.html: curl examples with Ask AI integration - section-children.html: tag listing on section index pages - all-endpoints-list.html: all operations sorted by path Generation (api-docs/scripts/generate-openapi-articles.ts): - Auto-discovery from .config.yml replaces hardcoded productConfigs - Each API section generates independently (no cross-spec merging) - Frontmatter-driven template data (specDownloadPath, articleDataKey) - Link transformation: /influxdb/version/ placeholders resolved to product-specific paths Removed: - Redoc renderer, JavaScript components, and CSS - Shadow DOM test infrastructure (~160 lines) - Operation page generation (dead generatePathPages function) - mergeArticleData() and slugifyDisplayName() Styles (assets/styles/layouts/_api-*.scss): - 3-column layout: sidebar, content, sticky TOC - Theme-aware code blocks for curl examples - Method badges (GET/POST/PUT/DELETE) with color coding - Collapsible schema sections with depth tracking Tests (cypress/e2e/content/api-reference.cy.js): - Tag page rendering with operation structure - Download button verification per section - All-endpoints page with operation cards - Related links from x-related OpenAPI extension - Code sample and Ask AI link validation * fix(api-docs): ignore generated spec downloads and enterprise v1 API pages Broadens the content HTML ignore pattern from `/content/influxdb*/**/api/**/*.html` to `/content/**/api/**/*.html` to cover `enterprise_influxdb/`, and adds `/static/openapi/` for generated spec download files. * fix(api-docs): simplify Cypress API reference tests Remove fingerprint interception workaround and fake GTM stubs. Replace back-link navigation test with sidebar link assertion. * fix(api-docs): untrack generated API content pages Remove generated cloud-serverless, cloud-dedicated, and clustered API content from git tracking. Add management-api pattern to .gitignore. * fix(api-docs): auto-generate API content before Cypress tests The API reference tests require generated content pages that are gitignored. Add a before() hook that detects missing content and runs the generation pipeline, then waits for Hugo to rebuild. * fix(api-docs): scope Cloud Serverless spec to supported endpoints, absolutify download links - Rewrite info.yml description to list supported endpoints (write, query, authorizations, buckets, orgs) and disclaim unsupported Cloud (TSM) endpoints - Comment out unsupported Cloud (TSM) paths in spec, keeping 29 supported paths - Convert orphaned Cloud (TSM) tags to x-traitTag with disclaimer - Strip all Redoc-specific anchor links (#operation/, #tag/, #section/) from spec descriptions and tags.yml — these break in the Hugo-native layout - Fix product name: "InfluxDB 3 Serverless" → "InfluxDB Cloud Serverless" - Add absolutifyLinks() to generate-openapi-articles.ts so static/openapi downloads contain full URLs (https://docs.influxdata.com/...) while Hugo pages keep relative paths * fix(api-docs): fix orphaned parentheses from Redoc link stripping The regex that stripped Redoc anchor links didn't account for nested parentheses in tag names like Authorizations-(API-tokens)), leaving orphaned closing parens in descriptions and tag references. * Update api-docs/influxdb/v1/content/info.yml * feat(api-docs): add externalDocs to tags, strip absolute URLs, fix link pipeline - Add standard OpenAPI `externalDocs` field to all tags.yml files that have `x-related` entries (uses first link as the primary doc link) - Convert `externalDocs` to `{title, href}` objects in related links instead of bare URL strings - Strip `https://docs.influxdata.com` from description/summary fields in `transformDocLinks()` so Hugo pages use relative paths - Fix article generation reading from absolutified download spec instead of the Hugo spec with relative links (new `hugoSpecPath` output) - Add `externalDocs.url` support to `absolutifyLinks()` for downloads * refactor(api-docs): simplify getswagger.sh and generate-api-docs.sh Extract fetchAndProcess and fetchManagementSpec helpers to deduplicate nine near-identical update functions. Cache granite clone across calls to avoid redundant fetches. Replace if/elif dispatch with case, fix quoting, remove dead code (versionDirs, npx --version), update help text, and use subshells for cd safety. Passes shellcheck with zero warnings. * fix(api-docs): fix Hugo spec path, sidebar data, and test selectors - Move Hugo spec (relative links) to _build/ instead of static/ with -hugo- suffix, preserving original basenames for tag spec filenames - Add articleDataKey, articleSection, and specDownloadPath to generated section and tag page frontmatter for sidebar nav and download button - Fix sidebar link test to use #nav-tree instead of .sidebar (avoids matching the hamburger toggle link) * fix(api-docs): add menu entries for all API reference pages Replace skipParentMenu with menuParentName to control sidebar placement. All products now generate menu entries: - v1 and Enterprise v1: parent "Tools" - All others: parent "Reference" * fix(api-docs): restyle Ask AI as a button for better contrast 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 These v2/cloud tags pages use an old layout that causes Hugo to panic during live rebuilds when generated API content is present. * refactor(api-docs): remove Redoc UI, update docs for Hugo-native pipeline 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 file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes PR preview build failures caused by subdirectory baseURL breaking product detection in shortcodes.
Changes
config/pr-preview/params.yml- New Hugo environment config withprPreviewPathOffset: 3.github/workflows/pr-preview.yml- Added-e pr-previewto Hugo build commandFixes the preview failure in #6657.
Related: Broader architectural fix in draft PR #6664.