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
* Initial plan
* fix(vale): add missing Google.Units=NO to product-specific .vale.ini files
Duration literals like 7d, 24h, 30d were being flagged as errors when
running Vale with product-specific configs because those configs were
missing Google.Units = NO. Also adds Vale.Terms = NO,
write-good.TooWordy = NO, and TokenIgnores to match the root .vale.ini.
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>
* 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>
* chore(deps): update yarn dependencies
Run yarn to update lockfile with latest compatible versions.
* fix(influxdb3): correct Quix Streams guide for Cloud Dedicated
Extract downsample-quix content to shared file and fix product-specific
terminology, links, and prerequisites for Cloud Dedicated and Clustered.
- Use "database" terminology for Cloud Dedicated/Clustered
- Remove Docker from prerequisites (not used in guide)
- Add alt_links for cross-product navigation
- Fix broken TOC anchor links
- Add links to admin pages for tokens and databases
- Remove incorrect /reference/regions link for Cloud Dedicated
- Add lint rules for deprecated code-placeholders and py fence
Closes#6825
* Apply suggestions from code review
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix(influxdb3): fix broken code blocks in Quix Streams guide
Code blocks inside show-in shortcodes were missing closing fences,
causing the markdown to render incorrectly. Added proper fence
boundaries and placeholder key documentation for each code section.
Also adds TODO to content-editing skill about improving automation
for code-placeholder-key workflow.
* Docs v2 docs v2 pr6828 (#6829)
* fix(influxdb): Rename to match other pages. Remove alt_links
* chore(deps): bump ESLint to 10.0.0
* Update content/shared/v3-process-data/downsample/quix.md
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix(shortcodes): latest-patch CLI version for cloud-serverless
Add cloud-serverless to the condition that handles cloud products,
and use influxdb.latest directly for CLI version lookups.
Root cause: The shortcode only checked for "cloud" version when
deciding to use the influxdb CLI version. Cloud Serverless pages
have $product="influxdb3" which doesn't exist in products.yml,
causing $latestVersion to be empty.
Fix: Calculate $influxdbLatest directly from products.influxdb.latest
within the CLI block, ensuring cloud products always use the correct
lookup key (v2) for the influx CLI version.
Includes Cypress test covering v2, Cloud, and Cloud Serverless.
Closes#6646
* Restore latest-patch shortcode for cloud-serverless. Revert "hotfix: influxdb (v2) CLI version (#6644)"
This reverts commit 5f792bd47a.
* chore(link-checker): update configs for v1.3.0 severity classification (#6688)
Remove exclusions for sites that return 403/429 (bot protection) and
5xx (server errors) - these are now handled by severity classification:
- 403/401/429 → info (shown but don't fail CI)
- 5xx/timeout → warning (shown but don't fail CI)
- 404/410/DNS → error (fail CI)
Removed exclusions:
- GitHub, Slack, Reddit, StackOverflow
- Docker Hub, Grafana, Microsoft Learn
- Claude.ai, Dremio, Scarf, InfluxData support
Kept exclusions:
- Localhost/local network URLs
- Example/placeholder URLs
- CI-specific workarounds (canonical URLs, file fragments)
Added [severity] configuration section with default thresholds.
- Fix broken link to parameterized queries in time-and-timezone.md
- Remove draft: true from Core and Enterprise InfluxQL parameterized queries
- Add HTTP API examples for Core/Enterprise using /api/v3/query_sql and
/api/v3/query_influxql endpoints
- Simplify list_code_example frontmatter to use query-only format across
all SQL and InfluxQL parameterized queries pages
- Fix api-endpoint shortcode arguments to use correct method, endpoint,
and api-ref parameters
Note: PR preview URLs show broken /version/ links but they render
correctly in local Hugo testing. The link replacement logic in
layouts/partials/article/content.html processes these correctly.
Closes#6672
* docs(influxdb3): document duplicate point write ordering and workarounds
Expand duplicate points documentation for Cloud Dedicated and Clustered
to address non-deterministic write ordering when duplicate points are
flushed together.
Changes:
- Add warning callout explaining duplicate point overwrites are non-deterministic
- Add recommended patterns section with append-only approaches
- Add SQL and InfluxQL query examples for getting latest state
- Add anti-patterns section with common mistakes to avoid
- Add retention guidance for last-value tables (Cloud Dedicated only)
- Add performance considerations for append-only patterns
- Add cross-links from schema-design and optimize-writes pages
closesinfluxdata/DAR#560
* Apply suggestions from code review
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* Apply suggestion from @jstirnaman
* fix(influxdb3): broken links and aliases:
The link in the cloud-serverless schema-design page was pointing to /influxdb3/cloud-serverless/reference/line-protocol/#duplicate-points, but the actual file is located at /influxdb3/cloud-serverless/reference/syntax/line-protocol/
Core/Ent3 aliases were missing trailing slash, preventing navigating directly from other product line protocol docs
* chore: cleanup
---------
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* chore(sql): add LAG examples for time-based value comparisons
Enhance window function documentation with practical examples for
calculating differences between current and previous values (e.g., 1h ago).
- Add 3 LAG examples to window functions reference with tested queries
- Create new 'Compare values' query guide covering common time-based
comparison patterns (differences, percentage changes, exact intervals)
- Add guide frontmatter for all InfluxDB 3 products
All queries validated against InfluxDB 3 Core.
Refs: Kapa.ai conversation https://app.kapa.ai/720100f9-ce93-4305-88fd-5fcf71effad7/conversations/4536b79e-3930-4359-87f5-2ad9ccc1917d
Starting from: https://docs.influxdata.com/influxdb3/cloud-serverless/reference/sql/functions/window/
* chore(sql): add counter metrics examples to compare-values guide
Enhance time-based value comparisons with counter metrics patterns
using LAG and GREATEST to handle counter resets.
- Add counter metrics section with 3 examples (rate, cumulative, intervals)
- Include tested queries for non-negative differences and aggregation
- Document workarounds for Flux increase() and InfluxQL NON_NEGATIVE_DIFFERENCE()
All queries validated against InfluxDB 3 Core.
Refs: Kapa.ai conversation https://app.kapa.ai/720100f9-ce93-4305-88fd-5fcf71effad7/conversations/16b13679-0ced-4780-ab58-3d9cacb2d899
Starting from: https://docs.influxdata.com/influxdb3/enterprise/
* Update content/shared/influxdb3-query-guides/sql/compare-values.md
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
---------
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* Initial plan
* Fix Edit this page link duplication
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
* feat(askai): add Kapa.ai source group filtering for InfluxDB v3
- Add ai_source_group_ids field to all InfluxDB v3 products in data/products.yml
- Add getProductSourceGroupIds() function to retrieve source group IDs from product data
- Enables filtered AI responses using Kapa source groups for documentation pages
- Follows existing pattern for dynamic product configuration
- Implement version-specific config support (__v1, __v2 suffixes)
- Append version hints to example questions for InfluxDB database products only
- Make example questions generic (remove product-specific names)
- Tools (Telegraf, Chronograf, Kapacitor, Flux, Explorer) display questions without version hints
- Pre-fills chat input with [version: /path/] for InfluxDB database products
- Users can easily edit or remove the pre-filled text
- Works for manual opens (Cmd+K) and programmatic opens
- Converts module to TypeScript
* refactor(ask-ai): change version format to 'My version: <product name>'
Use human-readable product names instead of URL paths for better UX.
Example: 'My version: InfluxDB 3 Core' instead of '[version: /influxdb3/core/]'
* fix(ask-ai): restore working Kapa.open() pre-fill implementation
- Replace textarea detection with direct Kapa.open() call
- Add Kapa preinitialization code
- Use click handler on .ask-ai-open button with capture phase
- Handle conversation reset event to re-fill version context
- Remove console logging for cleaner production code
* fix(ask-ai): remove parentheses from example questions for consistency
Make example question format match the pre-fill format:
- Before: 'question (My version: product)'
- After: 'question My version: product'
This ensures users don't think there's a difference between the two formats.
* fix(askai): add Explorer product mapping for Ask AI widget
- Add influxdb3_explorer mapping to getCurrentProductData()
- Add explorer context to getContext() function
- Ensures Explorer pages use correct ai_sample_questions from products.yml
- Reorder Explorer questions with 'install and run' first
This fixes the issue where Explorer Ask AI widget was showing wrong
example questions by properly loading the influxdb3_explorer config.
* test(page-context): add comprehensive e2e tests for product mappings
Add Cypress tests to validate page-context.js correctly identifies:
- Product context values for all InfluxDB products
- Product data from products.yml configuration
- Version information
- AI sample questions and source group IDs
- Placeholder host values
Tests cover:
- InfluxDB 3 (Core, Enterprise, Explorer, Cloud variants, Clustered)
- InfluxDB v2 and v1
- InfluxDB Cloud (TSM)
- Tools (Telegraf, Chronograf, Kapacitor, Flux)
Validates the fix for Explorer Ask AI showing correct example questions.
Related to #jts-askai-group-filters branch work.
* feat(test): add --no-mapping flag to e2e test runner
Allow running functionality tests without requiring content file paths.
The --no-mapping flag skips content-to-URL mapping, making it easier
to run tests that don't depend on specific content files.
Usage:
# With content mapping (for content-specific tests)
node run-e2e-specs.js content/influxdb3/core/_index.md
# Without content mapping (for functionality tests)
node run-e2e-specs.js --spec cypress/e2e/page-context.cy.js --no-mapping
Benefits:
- Simplifies running functionality tests like page-context.cy.js
- Reduces test startup time by skipping unnecessary file mapping
- Makes test commands clearer about their purpose
The page-context test was updated to work correctly with this flag.
* deps: update caniuse and related hook files
* test: Add a `--no-mapping` flag to run tests without specific content files (i.e., test contains all the URLs it needs)
* chore(ask-ai): Format example questions
* test(page-context): add comprehensive e2e tests for all products in products.yml
- Expanded test suite from 6 to 27 tests covering all products
- Added tests for InfluxDB 3 products (Explorer, Core, Enterprise, Cloud Serverless, Cloud Dedicated, Clustered)
- Added tests for InfluxDB v2 and Cloud (TSM)
- Added tests for InfluxDB v1 and Enterprise v1
- Added tests for other products (Telegraf, Chronograf, Kapacitor, Flux)
- Validates page mappings in page-context.js
- Validates AI sample questions configuration in products.yml
- All 27 tests passing
* fix(page-context): correct enterprise_influxdb URL pattern matching
- Changed pattern from /enterprise_v1/ to /enterprise_influxdb/
- Fixes Ask AI example questions not showing correctly for Enterprise v1
- Pattern now matches actual URL structure /enterprise_influxdb/v1/
- All 27 e2e tests passing
* test(page-context): add UI validation for Ask AI widget configuration
- Added 4 tests checking Kapa widget script data attributes
- Tests verify data-modal-example-questions contains correct product-specific questions
- Validates Explorer, Core, Enterprise, and Enterprise v1 configurations
- All 31 tests passing (27 existing + 4 new UI tests)
* feat(ask-ai): add help in Ask AI widget placeholder
- InfluxDB placeholder recommends specifying product and version
- Fix page-context.js to use products.influxdb_cloud instead of products.cloud
- Add UI tests verifying version-specific naming in Kapa widget script tags
* feat(ask-ai): Tailors placeholder for each version/product. Disables "Viewing <product>" in disclaimer note.
- Migrate comprehensive ODBC driver installation instructions to Power BI guide
- Add Windows (PowerShell and Manual) installation steps with verification
- Add macOS and Linux installation steps with configuration details
- Include platform-specific verification procedures
- Enhance Power BI troubleshooting section with ODBC-specific guidance
- Add driver not found troubleshooting for all platforms
- Expand connection, authentication, and query error troubleshooting
- Add query performance optimization recommendations
- Restructure Power BI documentation for clarity
- Elevate ODBC driver installation to top-level section
- Add explicit sequencing: install driver before connector
- Improve section flow and subheading descriptiveness
- Remove standalone ODBC documentation pages
- Delete shared ODBC guide and product-specific ODBC pages
- Add aliases in Power BI frontmatter to redirect old ODBC URLs
- Apply changes across all InfluxDB 3 products:
core, enterprise, cloud-dedicated, cloud-serverless, clustered
- Add /influxdb3/<version>/visualize-data/<tool>/ aliases to visualize files
- Ensures backward compatibility across cloud-serverless, cloud-dedicated, and clustered
- Matches URL structure used in core and enterprise versions
- Affects: grafana, superset, and tableau documentation
- Add ODBC driver installation and configuration docs
- Add Power BI Desktop custom connector setup docs
- Configure host, port, and token conditionals for all InfluxDB 3 products
- Set frontmatter with proper metadata and related content
The shared content files (content/shared/influxdb3-query-guides/execute-queries/odbc.md
and content/shared/influxdb3-visualize/powerbi.md) contain product-specific conditionals
for server URLs, ports, and tokens. Each product version sources these shared files.
Next steps: Edit the content/shared files to update any remaining product-specific
instructions in the step-by-step procedures if needed. Server, port, and token
conditionals are already configured throughout the documentation.
- Migrates Cloud Dedicated durability page to shared for Dedicated and Clustered.\
- Adds diagram (also used in storage-engine) to illustrate data flow.
- Fixes typo in Serverless
Address reidkaufmann's review comments on query timeout documentation:
Technical accuracy fixes:
- Replace "node/nodes" terminology with "querier/queriers" throughout
- Remove AI hallucination: "query result caching" (doesn't exist in IOx)
- Replace with proper cache recommendations for Enterprise/Core users
- Remove vague "background maintenance" references
- Add specific compaction performance variation cause
- Fix "round-robin or load-balanced" → "round-robin query routing"
Content improvements:
- Enhance checkout line analogy with explanation of noisy neighbors
- Add experimental query guidance for reducing impact on other users
- Replace unactionable solutions with customer-controllable actions
- Restore missing flexibility recommendations and link to the code sample
Technical updates:
- Update code blocks to use new placeholder syntax
- Add related links between cache documentation and timeout strategies
- Fix numbering consistency in Solutions sections
Add 'partial writes' tag to frontmatter for better content discoverability:
- content/influxdb3/cloud-dedicated/write-data/troubleshoot.md
- content/influxdb3/cloud-serverless/write-data/troubleshoot.md
- content/influxdb3/clustered/write-data/troubleshoot.md
This helps users find information about partial write scenarios across InfluxDB 3 distributed editions.
- Update clustered, cloud-dedicated, and cloud-serverless to share enhanced troubleshooting content
- Add comprehensive error capturing instructions with curl examples
- Include client library debug logging samples (Python, Go, Java, JavaScript)
- Provide detailed guidelines for reporting persistent write issues to support
- Split HTTP status code tables by product type for clarity
This standardizes troubleshooting across all InfluxDB 3 distributed editions.
Closesinfluxdata/DAR#522
chore(monolith): Recommend API over CLI for writing data (Closes#5957). Fix client library references
fix(monolith): Add tool comparison table (linked from client libs), fix and cleanup write data sections, link to client libraries.
fix(monolith): Remove redundant content.
Closes#5957
* replaced all oss- and cloud-only shortcodes
* removed duplicate oss calls and replaced with shared source
* base changes for shared v2 content
* restored shared grafana content
* removed frontmatter from shared v2 content
* WIP fixing lists with show-in shortcode
* fix lists that use show-in shortcode
* updated all v2 files to remove duplicate-oss and use source sharing
* update prepend and append frontmatter to just use string input
* fixed broken menu keys
- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.
Jason Stirnaman
Copilot
Daniel Campbell
Scott Anderson
mdevy-influxdata
Jason Stirnaman
Scott Anderson