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: link resource terms
* chore(aagents): Allow use of yq and htmlq for parsing.
* chore(deps): yarn upgrade
* chore(deps): remove unused @vvago/vale npm package
Vale linting uses Docker (jdkato/vale:latest) via .ci/vale/vale.sh,
not the npm package. Update VS Code setup docs to use system Vale.
* docs(skill): update content-editing skill for hosted MCP server
Replace local InfluxData MCP server references with the hosted kapa.ai
documentation MCP server (https://influxdb-docs.mcp.kapa.ai).
Changes:
- Update MCP configuration from local stdio server to hosted URL
- Replace kapa_query() examples with natural language prompts
- Add rate limit info (40/hour, 200/day per Google OAuth user)
- Standardize Hugo commands to use yarn (yarn hugo --quiet)
- Fix E2E test command (node cypress/support/run-e2e-specs.js)
- Use .ci/vale/vale.sh consistently for Vale linting
- Remove VS Code-specific instructions for agent focus
- Move TODOs to GitHub issue #6853
* chore(deps): yarn upgrade
* Apply suggestions from code review
* Update .claude/skills/content-editing/SKILL.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update .claude/skills/content-editing/SKILL.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix(ci): fix Vale linting setup and add dependency update checks
The vale Compose service was removed in 922e4818 but docs still
referenced `docker compose run -T vale`, which fails.
Vale linting now works as follows:
- If vale is installed locally (v3+), .ci/vale/vale.sh uses it directly.
Contributors can install via `brew install vale` for faster linting
without Docker.
- Otherwise, the script falls back to Docker with a pinned image tag
(jdkato/vale:v3.13.1) instead of :latest.
- If the local version is incompatible (pre-v3), the script warns and
falls back to Docker.
Docker is no longer required for pre-commit hooks that only run Vale.
Also adds a weekly GitHub Actions workflow (check-pinned-deps.yml) that
compares pinned dependency versions against upstream releases and opens
a PR when updates are available.
* Update .ci/vale/vale.sh
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update .github/workflows/check-pinned-deps.yml
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix: resolve code review findings for PR #6885
- vale.sh: make version-detection grep non-fatal so Docker fallback works
- check-pinned-deps: add set -euo pipefail, auth header, and null guards
- DOCS-CONTRIBUTING: fix broken links to DOCS-TESTING.md
- DOCS-TESTING: rename VS Code section heading per review suggestion
* Apply suggestions from code review
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* chore: Standard exclude comment format to denote flags, options, etc. that shouldn't be promoted in docs
* chore: exclude internal flags
* chore: Add docs:exclude comments for internal CLI flags, fix linting
- Note internal options that should be ignored by `docs audit` and authors.
- Remove character escaping from GitHub callouts and placeholders
Lint config changes:
- Add explicit exclude for content/**/*.md in lint-markdown-instructions
- Exclude all markdown files from Prettier formatting
Fixes issue where remark-lint was auto-formatting content files and
escaping special characters like [!Note] callouts and underscores.
* fix: cleanup escaping
* feat(ci): improve linting configuration for instruction files
- Add GitHub-flavored Markdown support with remark-gfm
- Create generic Vale config (.vale-instructions.ini) for instruction files
- Use pattern-based file inclusion instead of explicit file lists
- Mount repository to /workdir in remark-lint container to preserve node_modules
Changes:
- Add remark-gfm to .ci/remark-lint/package.json
- Create .remarkrc.yaml at repository root for instruction files
- Update content/.remarkrc.yaml to include remark-gfm
- Create .vale-instructions.ini for generic writing rules
- Update compose.yaml: mount repo to /workdir (preserves /app/node_modules)
- Update lefthook.yml: use glob patterns for uppercase .md files and .github/**/*.md
- Update DOCS-CONTRIBUTING.md: remove empty CONTRIBUTING.md directory reference
Benefits:
- Automatic inclusion of new instruction files without config updates
- Pattern matching for uppercase .md files (DOCS-*.md, CLAUDE.md, etc.)
- Coverage for .github/, .claude/, api-docs/ directories
- GFM features: tables, task lists, strikethrough, autolinks, footnotes
- Separate linting rules for instruction files vs product documentation
feat(lint): separate remark-lint auto-fix for instructions vs report-only for content
- Split lint-markdown into two hooks:
- lint-markdown-instructions: Auto-fixes README, DOCS-*.md, .github/**, .claude/**
- lint-markdown-content: Reports issues in content/**, api-docs/** without modifying
- Changed remark-lint volume mount from read_only: true to read_only: false
- Instruction files now behave like Prettier (auto-fix + stage)
- Content files report errors and block commits until manually fixed
* chore(instructions): Add content/shared details, husky/lefthook updates
Jason Stirnaman