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
* chore(spell-check): improve Vale spell checking for code comments
- Enable spell checking in code blocks by removing ~code exclusion from InfluxDataDocs Spelling rule
- Add comprehensive filters to avoid false positives from:
- camelCase and snake_case identifiers
- hexadecimal values and version numbers
- URL paths and URLs
- shortcode attributes
- code punctuation and symbols
- Fix spelling errors in code comments:
- "includimng" → "including" in 3 files
- "continously" → "continuously" in 5 files
This allows Vale to catch typos and spelling mistakes in code comments and documentation strings while avoiding false positives on actual code syntax and identifiers.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* chore(spell-check): add codespell configuration
- Add .codespellrc with 'clear' builtin dictionary to catch unambiguous spelling errors
- Add .codespellignore for technical terms and product names
- Configuration prevents false positives while enabling comprehensive spell checking for code comments
This enables codespell for automated spell checking via CI/CD, complementing the Vale configuration.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* fix(reference): correct 6 spelling errors across reference pages
Fixes identified through codespell analysis of reference documentation:
- influxdb/v2/config-options: useable → usable
- influxdb3/clustered/release-notes: provid → provide, certficate → certificate, memeory → memory, Geting → Getting
- kapacitor/v1/release-notes: auotmatically → automatically
Note: "invokable" is excluded as a branding term; "fpr" in GPG code is a legitimate field name.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* docs(spell-check): improve validation rules and documentation
Core improvements to spell-checking rules:
CODESPELL CONFIGURATION (.codespellrc):
- Use only 'clear' dictionary (removes 'rare', 'code' for fewer false positives)
- Add 'api-docs' to skip list (avoids false positives in generated specs)
- Add 'invokable' to ignore list (product branding term)
- Remove unclear 'tage' term
- Add documentation explaining each setting
VALE CONFIGURATION (Spelling.yml):
- Expand scope documentation explaining why code blocks are included
- Add comprehensive comments for each filter pattern
- Include examples for each regex pattern
- Document limitations and edge cases
- Organize filters by category (branding, URLs, code, literals)
NEW DOCUMENTATION (SPELL-CHECK.md):
- Tool comparison and use cases
- Detailed explanation of each filter pattern
- Troubleshooting guide
- Running instructions for both tools
- Contribution guidelines
- References and related files
These changes ensure:
✅ Minimal false positives (8.5-9/10)
✅ Strong true positive detection (8.5-9.5/10)
✅ Clear, maintainable rules
✅ Easy to extend and modify
✅ Well-documented for team use
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* refactor(spell-check): consolidate ignore words to single source
Consolidate duplicate ignored words configuration:
BEFORE:
- .codespellignore: AKS, aks, invokable, tagE
- .codespellrc: inline ignore-words-list = aks,invokable
- Problem: Maintenance duplication and confusion
AFTER:
- .codespellignore: authoritative list (aks, AKS, invokable with docs)
- .codespellrc: references .codespellignore via 'ignore-words' config
- Benefit: Single source of truth, cleaner configuration
Also removed:
- 'tagE' from ignore list (unclear, possibly a typo)
- Inline word list from .codespellrc (now external)
This follows codespell best practices and reduces maintenance burden.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* docs(spell-check): correct version number regex documentation
Fix incorrect limitation note in SPELL-CHECK.md:
The regex pattern \d+\.\d+(?:\.\d+)* actually DOES match
4-part versions like 1.2.3.4 (and any number of parts).
The (?:\.\d+)* part is a repeating group that matches
zero or more additional dot-separated version components.
Updated documentation to clarify that the pattern handles
any number of version parts, not just 2-3 part versions.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* Update SPELL-CHECK.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix(spell-check): tighten camelCase regex to prevent false negatives
The original camelCase regex pattern was too permissive and would match
any word starting with lowercase (e.g., 'provide', 'database', 'variable'),
causing Vale to skip spell-checking normal prose words.
Improved pattern now requires:
- camelCase: at least one uppercase letter (myVariable ✓, provide ✗)
- snake_case: at least one underscore (my_variable ✓, variable ✗)
This prevents common prose words from being silently excluded from
spell-checking while still properly handling code identifiers.
Combined pattern: (?:_*[a-z]+(?:[A-Z][a-z0-9]*)+(?:[A-Z][a-zA-Z0-9]*)*|[a-z_][a-z0-9]*_[a-z0-9_]*)
Updated files:
- SPELL-CHECK.md: Added detailed explanation and test cases
- .ci/vale/styles/InfluxDataDocs/Spelling.yml: Updated filter pattern
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
* fix(spell-check): expand URL scheme pattern to match documentation comment
The comment said the URL filter ignores 'http, https, ftp, etc.' but the
regex only matched http and https. Expanded the pattern to match:
- http/https (as before)
- ftp/ftps (file transfer protocols)
- ssh (secure shell)
- file (local file URLs)
Updated pattern: (?:https?|ftp|ftps|ssh|file)://[^\s\)\]>"]+
This ensures the filter matches the documented behavior.
https://claude.ai/code/session_01TYWR7wb5MUkzjVsK4mtNjA
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Jason Stirnaman