feat(api-docs): add externalDocs, strip absolute URLs, fix link pipeline#6953
Closed
jstirnaman wants to merge 7 commits intoapi-docs-upliftfrom
Closed
feat(api-docs): add externalDocs, strip absolute URLs, fix link pipeline#6953jstirnaman wants to merge 7 commits intoapi-docs-upliftfrom
jstirnaman wants to merge 7 commits intoapi-docs-upliftfrom
Conversation
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
# Conflicts: # .gitignore
Remove fingerprint interception workaround and fake GTM stubs. Replace back-link navigation test with sidebar link assertion.
Remove generated cloud-serverless, cloud-dedicated, and clustered API content from git tracking. Add management-api pattern to .gitignore.
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.
# Conflicts: # api-docs/scripts/generate-openapi-articles.ts
…nk pipeline
- Add standard OpenAPI `externalDocs` field to all tags.yml files that
have `x-related` entries (uses first link as the primary doc link)
- Convert `externalDocs` to `{title, href}` objects in related links
instead of bare URL strings
- Strip `https://docs.influxdata.com` from description/summary fields
in `transformDocLinks()` so Hugo pages use relative paths
- Fix article generation reading from absolutified download spec instead
of the Hugo spec with relative links (new `hugoSpecPath` output)
- Add `externalDocs.url` support to `absolutifyLinks()` for downloads
Contributor
Author
|
Opened in error — changes belong in #6622 |
Contributor
Visual Review SkippedReason: Preview deployment failed Visual review was skipped. The Copilot code review (Job 2) still ran. To trigger visual review manually, re-run this workflow after the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
externalDocsfield to alltags.ymlfiles that havex-relatedentries, using the first link as the primary doc link for spec consumersexternalDocsto{title, href}objects in related links instead of bare URL stringshttps://docs.influxdata.comhost fromdescription/summaryfields so Hugo pages use relative pathshugoSpecPathwith relative links for Hugo content pagesexternalDocs.urlsupport toabsolutifyLinks()for downloadable specsTest plan
yarn build:api-docs:scriptscompilesnode api-docs/scripts/dist/generate-openapi-articles.js --skip-fetchsucceedsrelatedhrefs (nodocs.influxdata.com)static/openapi/) have absolute URLsexternalDocspresent in download specs with absolute URLsnpx hugo --quietbuilds without errors