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.
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.
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
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.
* Revert "InfluxDB 1.12.3 release (#6872)"
This reverts commit 14e021aa26.
* fix(v1): split v1.12.3 release — publish OSS, defer Enterprise pending GA
Revert the combined InfluxDB 1.12.3 release commit and re-add only
OSS v1.12.3 documentation. Enterprise v1.12.3 docs will be published
in a separate PR once the release artifact is GA in the portal.
Also adds FUTURE/PAST LIMIT ordering caution for users on versions
prior to v1.12.3 (from copilot/restore-ordering-warning-influxql).
* chore: document separate OSS/Enterprise PR workflow for v1 releases
Update the influxdb1-tech-writer agent, v1 release PR template, and
prepare-release-notes command to enforce the practice of always creating
separate PRs for OSS v1 and Enterprise v1 releases. Enterprise must wait
for GA in the portal before merging.
* fix(enterprise): restore FUTURE/PAST LIMIT grammar productions in InfluxQL spec
The revert of the combined v1.12.3 commit removed grammar production
definitions (retention_future_limit, retention_past_limit) that document
existing InfluxQL syntax, not v1.12.3-specific features. Restore them
so the grammar is complete.
* Revert "fix(enterprise): restore FUTURE/PAST LIMIT grammar productions in InfluxQL spec"
This reverts commit c497f136a1.
* fix(v1): remove incorrect FUTURE/PAST LIMIT ordering caution from OSS spec
The caution stated that prior to v1.12.3, PAST LIMIT must appear before
FUTURE LIMIT. This is incorrect — the correct syntax has always been
FUTURE LIMIT before PAST LIMIT. The v1.12.3 fix addresses Enterprise
meta-node recording of limits, not parser syntax order.
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.
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.
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.
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.
- 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>
The packages-audit pre-push hook now detects the current branch and only
blocks pushes on the default branch. On feature branches, vulnerabilities
are reported as warnings with a link to create a GitHub issue.
* feat: [meta] https-insecure-certificate configuration (#6850)
Add documentation for meta node's `[meta] https-insecure-certificate` configuration.
This configuration is available in >= 1.12.3.
* feat: https-insecure-certificate configuration (#6847)
Add documentation for `https-insecure-certificate` configuration in `[cluster]` and `[http]` sections.
* feat: [tls] advanced-expiration configuration (#6849)
Add `[tls] advanced-expiration` setting for data nodes.
* feat: add compression options to influxd-ctl backup (#6717)
* feat: add compression options to influxd-ctl backup
Added new flags for backup compression and performance tuning.
* feat: Update backup.md
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
* Update content/enterprise_influxdb/v1/tools/influxd-ctl/backup.md
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>
---------
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* fix(enterprise): correct typos and inconsistencies in v1.12.3 release docs
Fix grammar, formatting, and accuracy issues across the new v1.12.3
configuration and backup compression documentation.
* fix(influxdb-v1): correct FUTURE LIMIT and PAST LIMIT clause order and add to ALTER RETENTION POLICY (#6591)
* fix(influxdb-v1): correct FUTURE LIMIT and PAST LIMIT clause order and add to ALTER RETENTION POLICY
- Fix clause order: FUTURE LIMIT must appear before PAST LIMIT (parser requirement)
- Add FUTURE LIMIT and PAST LIMIT clauses to ALTER RETENTION POLICY syntax
- Add grammar definitions for retention_future_limit and retention_past_limit
- Add explicit note clarifying the required clause order
- Fix "There are" style issue in spec.md
closes#6590
* style(influxdb-v1): clean up InfluxQL spec formatting
influxdb/v1:
- Simplify introduction and use relative anchor links
- Convert notes to GitHub-style callout syntax
- Fix heading hierarchy (Letters/digits, Identifiers, Keywords, Literals as h3)
- Standardize Duration units table heading
- Fix "keywords" typo
- Reword "See FAQ" to "For more information, see"
- Simplify KILL QUERY section
- Fix SHOW MEASUREMENT CARDINALITY heading level
- Replace "There are" with active voice
enterprise_influxdb/v1:
- Add related links to frontmatter
- Simplify introduction and use relative anchor links
- Convert notes to GitHub-style callout syntax
- Add Characters and Letters/digits to TOC
- Standardize Duration units table heading
- Fix "keywords" typo
- Reword "See FAQ" to "For more information, see"
- Simplify KILL QUERY section for Enterprise clusters
- Update SHOW TAG KEYS grammar to include with_key_clause
- Remove backticks from SHOW STATS headings
* fix(influxdb-v1): address review issues in InfluxQL spec pages (#6931)
* fix(influxdb-v1): address review issues in InfluxQL spec pages
- Fix Enterprise KILL QUERY: restore proper EBNF grammar with optional
ON clause and include both local and cluster examples
- Fix duplicate "Durations" heading in both spec files
- Fix list item spacing in Enterprise spec
- Revert OSS heading level changes to maintain consistency with Enterprise
- Restore Comments section to original location under Other in OSS spec
* fix(influxdb-v1): move Comments section outside Other in OSS spec
Match Enterprise spec structure: Comments is a top-level section
before Other, not nested inside it.
* fix(influxdb-v1): restore Comments link in OSS spec TOC
* fix(influxdb-v1): rewrite KILL QUERY with clear Syntax and Examples sections
Use text-typed code block for syntax notation and Syntax heading.
Keep both local and cluster examples in sql-typed block.
* feat(enterprise,v1): add v1.12.3 release notes and missing OSS config options
Add release notes for InfluxDB v1.12.3 (OSS and Enterprise) with links
to documented features. Add missing https-insecure-certificate and
advanced-expiration config options to OSS docs. Fix backup example
gzipBlockSize typo (10048576 → 10485760) and document the default.
* fix(enterprise,v1): fix broken links in release notes and spec pages
Fix 30+ broken links across v1 release notes and InfluxQL spec pages:
- Correct config paths (configuration/ → configure/)
- Fix fragment anchors (remove default values from anchors)
- Update relocated pages (cluster-commands → tools/influxd-ctl)
- Fix cross-product links (Enterprise → OSS for shared content)
- Remove dead links (flux/v0.36, whats_new)
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* fix(enterprise,v1): move FUTURE/PAST LIMIT fix from Features to Bug fixes
The clause order correction is a bug fix, not a new feature.
* fix(v1): correct spec typos and KILL QUERY placeholder in v1.12.3 docs (#6932)
* Initial plan
* fix(v1): correct typos, grammar references, and example inconsistencies in spec and backup docs
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* revert(enterprise/v1): restore gzipBlockSize and gzipBlockCount in backup example
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* revert(v1): restore with_key_clause in spec grammar for show_tag_keys, show_tag_values_cardinality, and exact_cardinality statements
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>
* fix(influxdb-v1): fix broken cross-references in meta-nodes config and OSS config
- Fix meta-internal-shared-secret links in config-meta-nodes.md to point
to config-data-nodes where the heading exists
- Update MDN security headers URL to current location
* chore(influxdb-v1): bump OSS and Enterprise latest patch to 1.12.3
* docs: tag v1.12.3-only config and backup updates (#6936)
* Initial plan
* docs(metadata): mark v1.12.3 additions
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: Geoffrey Wossum <gwossum@influxdata.com>
Co-authored-by: WeblWabl <devandbenz@gmail.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
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.
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.
* Initial plan
* fix: include docs home page in PR preview and Copilot visual review when layouts/index.html changes
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix: improve detect-preview-pages to avoid false needs-author-input when home page auto-detected
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>
- 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)
- 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
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.
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.
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".
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.
- 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
- Upgrade glob from ^10.3.10 to ^13.0.6 to resolve dependency
vulnerability warnings. API is unchanged, no code changes needed.
- Add dompurify >=3.3.2 to resolutions to prevent regression.
The prior lockfile-only fix (8dd60bf) regressed when yarn add
regenerated the lockfile.
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
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
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.
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.
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.
* chore: add hosted influxdb-docs MCP server to .mcp.json
Add the hosted InfluxDB documentation search MCP server
(influxdb-docs.mcp.kapa.ai) as the primary MCP server using SSE transport.
Keep the local server with a note that it uses deprecated endpoints.
https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc
* chore: add API key auth option for hosted influxdb-docs MCP server
Make the API key-authenticated server the primary entry (influxdb-docs)
using Bearer token from DOCS_KAPA_API_KEY env var. Keep the OAuth
fallback as influxdb-docs-oauth for users without an API key.
https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc
* chore: rename env vars to INFLUXDATA_DOCS_ namespace
Rename DOCS_KAPA_API_KEY, DOCS_API_KEY_FILE, DOCS_MODE, and
MCP_LOG_LEVEL to use the INFLUXDATA_DOCS_ prefix for consistency.
https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc
* docs: add MCP server setup docs for contributors and AI agents
Update CLAUDE.md, AGENTS.md, and content-editing SKILL.md with
concise documentation for the hosted influxdb-docs MCP server,
covering both API key and OAuth authentication options.
https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc
* fix: remove cross-agent references from .claude files and AGENTS.md
Keep .claude/ files focused on Claude Code. Link AGENTS.md to the
published MCP server docs page instead of mentioning tool-specific setup.
https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc
---------
Co-authored-by: Claude <noreply@anthropic.com>
* 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>
* Initial plan
* fix: use correct API to request Copilot code review in doc-review workflow
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>
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.
Jason Stirnaman
Copilot
Scott Anderson
peterbarnett03
Sven Rebhan
dependabot[bot]