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
- 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)
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.
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.
- 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.
* chore: add .worktrees to gitignore
* refactor: replace URL-parsing in shortcodes with cascade product data
Replace duplicated URL-parsing logic across 28 shortcodes with Hugo's
cascade frontmatter. Each product section's _index.md now cascades
`product` (data key) and `version` (URL segment) to all descendants.
Key changes:
- Add cascade frontmatter to 15 product _index.md files
- Create layouts/partials/product/get-data.html shared partial
- Refactor 28 shortcodes to use the partial instead of parsing URLs
- Add version_label, limits, and distributed_architecture metadata
to data/products.yml to eliminate hardcoded dicts in shortcodes
- Fix lefthook lint-markdown-instructions glob format (YAML array)
- Fix pre-existing Vale exclamation point errors in cloud and v2
* fix: prevent remark-lint from escaping Hugo template syntax in shortcodes
Lefthook's glob option only triggers whether a command runs — it does
not filter {staged_files}. This caused remark-lint to process .md
shortcode files in layouts/, escaping underscores, brackets, and
parentheses that are valid Hugo template syntax.
Add layouts/ exclusion to the existing content/ filter in the
lint-markdown-instructions run command. Also fix the 3 shortcode files
that were damaged by remark-lint in the previous commit.
* test: add E2E tests for cascade product shortcodes
Add Cypress tests validating all refactored shortcodes across 14
product/version combos (82 tests). Test expectations are derived
from products.yml at runtime via cy.task('getData').
Fix the product links test to iterate actual home page links
instead of all products.yml entries.
Create _test/shortcodes.md pages in each product section
exercising product-name, product-key, current-version,
influxdb/host, and InfluxDB3-specific shortcodes.
* test: expand E2E coverage to 27 of 28 cascade shortcodes
Add shortcode invocations to all 14 test pages and corresponding
Cypress assertions for version lookups, namespace URLs, product
name text, placeholder_host, version visibility, CTA links, and
site-level data.
Add shortcodes-real-pages.cy.js for 6 shortcodes that require real
page context (cli/mapped, children, flux/list-all-functions,
telegraf/plugins, html-diagram/sso-auth-flow, cli/influxd-flags).
Suppress Vale on test pages — they contain only shortcode syntax,
not prose.
163 tests total, all passing.
* refactor(test): rename _test dirs to __tests__ and add noindex
Rename test page directories from _test to __tests__ to align with
JS testing conventions. Add noindex: true to all 14 test page
frontmatter to prevent search engine indexing in production.
Update Cypress URL pattern to match new paths.
* Initial plan
* feat: add Documentation MCP server pages to chronograf, kapacitor, flux, and explorer
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix: update MCP page descriptions to include product names
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix: resolve product-name shortcode for v1/v0 versioned products
The shortcode previously only checked the second URL path segment to
identify products, which works for InfluxDB 3 (/influxdb3/core/) but
fails for older products where the second segment is a version number
(/chronograf/v1/, /flux/v0/).
Add namespace extraction (first path segment) and conditional logic to
look up products by namespace when the version is v1 or v0. This fixes
empty product names in meta descriptions for Chronograf, Telegraf,
Kapacitor, Flux, and InfluxDB Enterprise v1.
* feat: relocate v2/cloud MCP pages and add alt_links for cross-product navigation
- Move MCP server pages from reference/ to tools/ for InfluxDB v2 and Cloud
- Add alt_links frontmatter to all MCP pages for cross-product navigation
- Use product-name shortcode in descriptions for consistency
- Convert code-placeholders shortcode to fenced code block attributes
- Update shared content to use version-agnostic URLs
* Add multi-assistant installation instructions for documentation MCP server (#6836)
* Initial plan
* feat(mcp): add installation instructions for multiple AI assistants
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* refactor(mcp): replace Cline and Windsurf with GitHub Copilot and OpenCode
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
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).
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.
- 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
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"
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.
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(version-detector): use centralized getGrafanaLink for all Grafana URLs
Refactor handleAuthorizationHelp to use getGrafanaLink() instead of
hardcoded URLs, ensuring all Grafana links come from a single source.
Also fix incorrect URLs in getGrafanaLink mapping:
- InfluxDB OSS 2.x: /visualize-data/ → /tools/
- InfluxDB Enterprise: /influxdb/enterprise/ → /enterprise_influxdb/v1/
- InfluxDB Cloud (TSM): /visualize-data/ → /tools/
- InfluxDB Cloud v1: now links to Enterprise v1 docs (Cloud v1 is
Enterprise under the hood)
* refactor(version-detector): DRY up localhost:8086 references
Extract HOST_EXAMPLES to a class-level constant and add DEFAULT_HOST
and DEFAULT_HOST_PORT constants to eliminate duplicate localhost:8086
strings throughout the code.
- Move hostExamples from local variable to class constant
- Use DEFAULT_HOST for URL placeholder and comparison checks
- Use DEFAULT_HOST_PORT for docker curl command examples
* feat(ask-ai): Support source group IDs in Ask AI trigger links
* feat(version-detector): Present context-aware links
- Add ai_source_group_ids fields to ProductConfig interface
- Improve SCSS for doc and Ask AI links
- Update Grafana docs to add aliases and context param for detector
- Update modal partial to include AI source group IDs in config
- Remove custom Cypress commands for version detector
- Update E2E tests to use direct Cypress commands
* Initial plan
* fix(influxdb/v2): correct Windows download link to use _amd64 suffix
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix(shortcode): Add prPreviewPathOffset support to latest-patch shortcode
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
* docs(v2): Specify versions for v2 Cloud and OSS
* docs(v2): Use specific version for OSS v2, add ToC
* docs(v1): Use specific versions and names. Replace Enterprise v1 with 3
Ent.
* docs(v1): More detailed description for OSS v1 release notes. Repetition
fixes.
* docs(v1): Update Download instructions. Add version specificity
* docs(v1): OSS v1 specificity, fix config commands, cleanup lists
* docs(cloud1): Shared note shortcode to guide Cloud 1 users to Enterprise
documentation, Cloud 1 support, and v3 migration
* Provide Cloud 1.x in version detector and product selector menu,
simplify InfluxDB 1.x section
- Simplify InfluxDB 1.x section on platform page to product links and
migration guidance
- Remove detailed TICK stack and Enterprise feature descriptions
- Update all Cloud 1 links to point to /platform/#influxdb-cloud-1
- Keep Cloud 1 infrastructure intact:
- products.yml configuration
- Product selector entry (links to platform page section)
- Version detector for *.influxcloud.net service URLs
- Ask AI integration
Files changed:
- content/platform/_index.md (simplified, updated links)
- content/shared/identify-version.md (updated links)
- layouts/shortcodes/influxdb-cloud1-note.html (updated links)
- assets/js/utils/product-mappings.ts
- assets/js/influxdb-version-detector.ts
Closes /influxdata/dar/issues/563
* Delete content/influxcloud/v1/_index.md
* Update content/enterprise_influxdb/v1/_index.md
* Update content/influxdb/v1/introduction/install.md
* Fix PR Preview skipping when layout changes include wildcard URL patterns (#6725)
* Initial plan
* Fix: Strip wildcards from URL paths in PR Preview detection
- Update normalizeUrlPath() to remove asterisk wildcards
- Collapse multiple consecutive slashes after wildcard removal
- Add backtick as valid URL delimiter for code-wrapped URLs
- Add comprehensive test cases for wildcard handling
- Update backtick test to reflect safer truncation behavior
Fixes issue where PR descriptions with wildcard patterns like
`/influxdb3/enterprise/*` were not properly extracted, causing
PR Preview to skip even when URLs were provided.
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* docs: Clarify backtick handling in URL validation
Add comment explaining that backticks act as delimiters in regex
extraction, preventing them from appearing in extracted paths even
though they're in the rejection pattern.
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* docs: Improve comments explaining normalization and regex logic
- Clarify why wildcards are removed before slash collapsing
- Document the defense-in-depth backtick handling
- Add examples of the normalization process
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* Update content/platform/_index.md
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* refactor: organize cloud1-note shortcode into influxdb directory (#6734)
Move the Cloud 1 note shortcode from influxdb-cloud1-note.html
to influxdb/cloud1-note.html to follow the existing organizational
pattern in layouts/shortcodes/influxdb/.
This change also applies the Cloud 1 content updates from PR #6729
using the new organized shortcode path: {{< influxdb/cloud1-note >}}
closesinfluxdata/docs-v2#6729
Co-authored-by: Claude <noreply@anthropic.com>
---------
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
- 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
- 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
- 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
* 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>
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.
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
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).
- 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)
- 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
- 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)
Jason Stirnaman
Copilot
Scott Anderson