Skip to content

Conversation

@jstirnaman
Copy link
Contributor

API reference uplift:

  • Improved integration with site, metadata, navigation
  • Improved look and feel
  • Improved performance
  • New right sidebar with in-page nav

Latest screenshot:
image

Replace legacy API documentation approach with modern Scalar-based rendering:

## Architecture Changes
- Add renderer abstraction (`layouts/partials/api/`) supporting Scalar and RapiDoc
- Create `api` layout type for API reference pages (single.html, list.html)
- Configure renderer via `site.Params.apiRenderer` (default: scalar)

## OpenAPI Processing Pipeline (TypeScript)
- `api-docs/scripts/generate-openapi-articles.ts` - Main generation script
- `api-docs/scripts/openapi-paths-to-hugo-data/` - OpenAPI to Hugo data converter
- Generates per-endpoint path fragments for AI agent access
- Creates Hugo content pages with `type: api` frontmatter

## AI Agent Accessibility
- Full specs at `/openapi/influxdb-{product}.yml` and `.json`
- Per-endpoint fragments at `/openapi/influxdb-{product}/paths/`
- `<link rel="alternate">` tags in HTML for machine discovery

## Scalar Features
- Dark/light theme support synchronized with site theme
- InfluxData brand colors
- Responsive layout
- Download link for OpenAPI spec

## Products Supported
- cloud-v2, oss-v2
- influxdb3-core, influxdb3-enterprise
- cloud-dedicated, cloud-serverless, clustered

Usage: node api-docs/scripts/dist/generate-openapi-articles.js [product]
- latest-patch.html: Replace deprecated .Store with local variable
  assignment. The .Store method was removed from shortcode context
  in newer Hugo versions.

- api-endpoint.html: Add nil check for productRef lookup to prevent
  index errors when productKey is not in productAliases dictionary.
  Falls back to "influxdb" as default product reference.
- yarn build:api-docs: Generate API docs for all products
- yarn build:api-docs cloud-v2: Generate for specific product
- yarn build:api-docs:compile: Recompile TypeScript if modified
…. Split ui-dev subagent into hugo-, ts-, and testing-specific agents.
- Add CSS for operations list cards with method badges, paths, and summaries
- Remove duplicate Overview section from list.html (was duplicating summary)
- Split "Data Operations" into separate nav groups: Write data, Query data, Cache data
- Add support for tag-based article generation with operations metadata
- Generate articles.yml data files with tag, menuName, and isConceptual fields
- Include operations array in frontmatter for tag pages
- Rewrite single.html for operation pages with RapiDoc integration
- Simplify rapidoc.html partial for tag-based rendering
- Add sidebar-nav include to sidebar.html for API navigation
- Add tab-panels.html and tabs.html for content organization
- Add api-nav.ts for sidebar navigation collapse/expand
- Add api-scalar.ts for Scalar API renderer integration
- Add api-tabs.ts for tab switching functionality
- Add api-toc.ts for table of contents generation
- Register components in main.js
- Add YAML article data files for all InfluxDB products
- Add sidebar-nav.html partial for API navigation rendering
- Rename data directory from article-data to article_data for Hugo compatibility
- Remove obsolete JSON articles file
- Update hugo.yml config for API docs settings
- Simplify _api-overrides.scss (removed hardcoded content styles)
- Import _api-layout.scss in styles-default.scss
- Update API landing pages for Core and Enterprise with redirects
- Update OpenAPI spec files
- Update dependencies
- Update tests for new tag-based API page structure
- Add tests for operations list rendering
- Add tests for sidebar navigation groups
…tion

- Header summary now shows only the first sentence from description
  using regex extraction with fallback to first line for descriptions
  without sentence-ending punctuation
- Added Overview section with full description after endpoints list
- Sidebar nav now shows operations with method badges and paths instead
  of duplicating tag names when groups are expanded
- Added background color to nav group items to match sidebar
- Increased max-height for expanded groups to accommodate all operations
- Added styles for operation items in sidebar nav (.api-nav-operation)
- Fixed summary paragraph width by setting flex-basis to 100%
- Changed operation link font-size from 0.85rem to 0.95rem to match sidebar
- Changed path code font-size from 0.75rem to 0.85rem for consistency
- Adjusted method badge font-size from 0.55rem to 0.6rem for readability
…size

- Add button reset styles to .api-nav-group-header for dark mode
  compatibility (background: none, border: none, width: 100%)
- Increase operation link font-size from 0.95rem to 1rem to match
  sidebar nav-item font size (18px base)
- Increase api-path code font-size from 0.85rem to 0.9rem
Add API nav items as children of "InfluxDB HTTP API" menu item:
- New api-menu-items.html partial generates nav from data/articles.yml
- Modified nested-menu.html to inject API nav for API parent menu item
- Updated api_nav_groups.yml to add url for Administration group
- Created Administration landing pages for Core and Enterprise
- Updated .gitignore to allow hand-crafted API conceptual pages

The Administration page uses layout: list and isConceptual: true to render
content directly without RapiDoc wrapper.
Now that API navigation is integrated into Hugo's menu system:
- Remove api-nav.ts component (no longer needed)
- Remove api/sidebar-nav.html partial (replaced by api-menu-items.html)
- Remove api-nav component registration from main.js
- Update sidebar.html to pass siteData to nested-menu for API nav
- Fix anchor ID handling for special characters (like / in operation IDs)
Remove multi-tag groups (Administration, Concepts) and flatten to
single-tag groups for direct linking. Each API tag now renders as
a direct nav item instead of being nested under a parent group.

- Update api_nav_groups.yml to use single-tag groups only
- Delete Administration landing pages (not needed without nesting)
- Improve SCSS styling for API nav visibility and active states
Add visual badges to distinguish v1-compatible and v2-compatible API
endpoints in the sidebar navigation. This helps users migrating from
InfluxDB v1 or v2 quickly identify which compatibility layer each
endpoint belongs to.

Changes:
- Add x-compatibility-version extension to compatibility operations
- Add externalDocs links to reduce verbose descriptions in specs
- Update generator to extract compatVersion and externalDocs fields
- Display colored badges (purple for v1, cyan for v2) in sidebar nav
- Strip redundant "(v1-compatible)" text when badge is shown
- Add hover tooltips explaining compatibility context
The feature is shippable, but needs a few small fixes and we'll need to update or alias all API docs links for Core and Ent3.

- Add rapidoc-mini.ts TypeScript component with CDN loading and theme sync
- Add api-operation layout for standalone operation pages
- Add rapidoc-mini.html partial for reusable RapiDoc rendering
- Add rapidoc-custom.css for RapiDoc style overrides
- Register rapidoc-mini component in main.js
- Add article data for cloud-dedicated and clustered products
- Update API reference Cypress tests
@jstirnaman jstirnaman marked this pull request as draft December 11, 2025 23:45
@jstirnaman jstirnaman added Feature-WIP Feature is still a work in progress and is not yet merged. API ui labels Dec 11, 2025
@jstirnaman jstirnaman added this to the API reference uplift milestone Dec 11, 2025
…uality

- Restore original RapiDoc match-paths format (method /path) for proper filtering
- Restrict operation tags to primary tag in tag-specific specs to prevent duplicates
- Rename Token tag to Auth token for clarity in Core and Enterprise specs
- Remove Table tag from cache operations (distinct_cache, last_cache)
- Add build script combining API docs, Hugo, and Markdown generation
- Skip summary rendering for conceptual pages
- Add isConceptual check to hide operations in nav for conceptual pages
- Update api_nav_groups.yml to use "Auth token" instead of "Token"
- Remove x-tagGroups from Core and Enterprise specs (Redoc-specific, not needed for RapiDoc)
- Add migration notes to plan document for future product migrations
…habetically

- Remove api_nav_groups.yml config file (no longer needed)
- Update api-menu-items.html to derive order from article data
- Sort: conceptual tags (traitTags) first, then other tags alphabetically
- Reduces template from 255 to 152 lines
- Add api/section-children.html partial for API section index pages
- Update api/list.html to detect section index vs tag pages
- Add "All endpoints" nav item listing all operations sorted by method+path
- Remove {{< children >}} shortcode from API index pages (use data-driven list)
Increase font size from 0.55rem to 0.9rem for better readability
while keeping the standard sans font for space efficiency.
@jstirnaman jstirnaman marked this pull request as ready for review December 12, 2025 17:41
@jstirnaman
Copy link
Contributor Author

Code review

Found 1 issue:

  1. Inline JavaScript in rapidoc.html violates the documented JavaScript component pattern (DOCS-CONTRIBUTING.md says: "The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and assets/js/main.js as the entry point to import modules from assets/js. Only assets/js/main.js should be imported in HTML files.")

    The file contains ~310 lines of inline JavaScript (lines 97-408) for theme detection, DOM manipulation, and event handling. This should be refactored into a TypeScript component in assets/js/components/ and registered in main.js, similar to how scalar.html uses the api-scalar.ts component.

<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
<script>
(function() {
'use strict';
console.log('[RapiDoc] Script loaded');
// Detect current theme by checking which theme stylesheet is enabled
function isDarkTheme() {
// Check for enabled dark-theme stylesheet
const darkStylesheet = document.querySelector('link[rel*="stylesheet"][title="dark-theme"]:not([disabled])');
if (darkStylesheet && !darkStylesheet.disabled) {
return true;
}

🤖 Generated with Claude Code

- If this code review was useful, please react with 👍. Otherwise, react with 👎.

Extract inline JavaScript from rapidoc.html into a proper TypeScript
component following the established component pattern.
Remove ~230 lines of inline JavaScript and use the new api-rapidoc
TypeScript component via data-component attribute instead.
Remove unused Scalar API documentation renderer:
- Delete layouts/partials/api/scalar.html
- Delete assets/js/components/api-scalar.ts
- Simplify renderer.html to only use RapiDoc
- Remove ApiScalar from main.js component registry
- Remove apiRenderer config option from hugo.yml
Remove unused tabs component and partials:
- Delete assets/js/components/api-tabs.ts
- Delete layouts/partials/api/tabs.html
- Delete layouts/partials/api/tab-panels.html
- Remove ApiTabs from main.js component registry

The new architecture renders content directly without tabs.
Remove tests for tabs and 3-column layout that no longer exist.
Keep basic API reference tests and RapiDoc Mini component tests.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API Feature-WIP Feature is still a work in progress and is not yet merged. ui

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants