Commit Graph

481 Commits (feat-api-uplift)

Author SHA1 Message Date
Jason Stirnaman 313fca7294 style(api): refine code samples, schema examples, and layout width
- Move Ask AI link to header bar alongside Example request title
- Use theme-aware variables for code block backgrounds and colors
- Fix schema example blocks: separate header bar from code content
- Normalize description font sizes to inherit page base size
- Keep inline code font-size proportional with font-size: inherit
- Widen API content wrapper to match regular article width (~850px)
- Remove TOC border-left at compressed viewport widths (1281-1535px)
2026-03-10 14:16:55 -05:00
Jason Stirnaman f061004c50 style(api): move Ask AI link below code block with theme-aware styling
Position the Ask AI link in a footer bar below the code sample instead
of overlaying it on the code block. Use site theme colors instead of
hardcoded values.
2026-03-09 22:12:53 -05:00
Jason Stirnaman df9c9977cf feat(api): add inline curl examples and Ask AI links to API operations
Generate curl examples at Hugo template time from OpenAPI specs, with
server URL variable resolution, $ref handling, and JSON body generation
from schema properties. Add "Ask AI about this example" links using
existing Kapa integration. Add client library related link to all
InfluxDB 3 API tag pages. Improve visual separation between operations
with distinct badge colors and response body indentation.
2026-03-07 23:00:22 -06:00
Jason Stirnaman 00f0578677 fix(api): add scroll highlighting to server-rendered TOC
The server-rendered TOC path returned early without setting up the
IntersectionObserver, so the is-active class was never applied to
TOC links during scroll. Extract entry IDs from pre-rendered links
and pass them to setupScrollHighlighting.
2026-03-06 16:18:11 -06:00
Jason Stirnaman fc1f93680b style(api): use Redocly anchor format and flatten operation layout
- Switch operation anchors from {method}-{path} to
  operation/{operationId} (PascalCase), matching Redocly convention
  and existing content links like #operation/PutPluginFile.
  Updated in Hugo templates, all-endpoints list, and JS TOC.

- Remove nested bordered containers from API operations. Operations
  separated by top-border dividers instead of card wrappers. Param
  lists, schema properties, and responses no longer wrapped in
  bordered boxes.

- Replace CSS custom properties (var(--article-text, ...)) with SCSS
  theme variables ($article-text, $article-heading, $nav-border, etc).
  The CSS vars were never defined in this theme, so all text fell back
  to hardcoded dark-gray values invisible in dark mode.

- Delete entire dark mode override section — now handled automatically
  by Hugo's per-theme SCSS compilation.

- Add border-bottom divider to operation endpoint line for visual
  separation from the operation heading.

- Update PLAN.md to mark Task 7 as completed.
2026-03-06 14:35:54 -06:00
Jason Stirnaman f58abb6971 Merge remote-tracking branch 'origin/master' into docs-v2-pr6622
# Conflicts:
#	.github/copilot-instructions.md
#	layouts/shortcodes/latest-patch.html
2026-03-06 12:12:58 -06:00
Jason Stirnaman 61161cc280
feat(ent3): add experimental badge for --use-pacha-tree (#6857)
* fix(ent3): Add link target and experimental caution for PachaTree option.

* feat(ent3): add experimental badge for --use-pacha-tree

Document the experimental PachaTree storage engine option with a
styled badge and caution callout. Add reusable .badge.experimental
class using the existing caution color palette for light/dark modes.

- Add experimental badge to serve options table and config-options
- Add badge theme variables referencing $article-caution-* colors
- Use custom heading ID to preserve #use-pacha-tree anchor
2026-02-23 14:58:35 -06:00
Jason Stirnaman b4a0eea0a3
feat: add InfluxDB documentation MCP server integration (#6830)
* chore(deps): update yarn dependencies

Run yarn to update lockfile with latest compatible versions.

* feat: add InfluxDB documentation MCP server integration

- Enable MCP widget in Ask AI (data-mcp-enabled, data-mcp-server-url)
- Restructure mcp-server.md with anchor TOC for database and docs MCP
- Add documentation MCP server page for products without database MCP:
  - cloud-serverless, clustered, v2, cloud (TSM), telegraf
  - Place in Reference section (or telegraf_v1_ref menu)
- Add shared content file for docs-only MCP server
- Add "Connect to documentation MCP" link in format-selector dropdown
- Add related MCP links to all get-started/setup pages

* fix: correct JSON syntax and product-aware MCP docs URL

- Fix JSON syntax errors in Cloud Dedicated config examples (= → :)
- Add missing comma in Docker args array for local server config
- Make format-selector MCP docs URL product-aware using Hugo path detection

* docs: add MCP pages for v1 products, fix menu, add screenshot

- Fix cloud-serverless identify-version menu parent to "Administer InfluxDB Cloud"
- Add MCP server pages for influxdb/v1 and enterprise_influxdb/v1 in Tools menu
- Update format-selector with v1 and enterprise_influxdb/v1 MCP docs paths
- Add MCP tool search screenshot showing search_influxdb_knowledge_sources

* Update content/influxdb3/cloud-serverless/get-started/setup.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update content/telegraf/v1/mcp-server.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2026-02-17 20:42:56 -06:00
Jason Stirnaman 3a56561cfa style(api): remove RapiDoc styles and rename hugo-native to operations
Remove all RapiDoc-specific code from styles and JavaScript:
- Delete rapi-doc::part() CSS selectors from _api-layout.scss
- Delete dead auth modal styles from _api-security-schemes.scss
- Delete api-auth-input.ts component (RapiDoc "Try it" integration)
- Delete static/css/rapidoc-custom.css (unused)
- Remove setupRapiDocNavigation() from api-toc.ts
- Update comments to remove RapiDoc references

Rename _api-hugo-native.scss to _api-operations.scss since
Hugo-native is now the standard (not a POC).
2026-02-13 22:35:22 -06:00
Jason Stirnaman 2b3ed56218 refactor(api): complete Hugo-native migration, remove RapiDoc
Complete Tasks 1-5 of the Hugo-native API migration:

- Promote Hugo-native templates from POC to production location
- Remove RapiDoc templates (rapidoc.html, rapidoc-tag.html, rapidoc-mini.html)
- Remove RapiDoc JS components (api-rapidoc.ts, rapidoc-mini.ts)
- Clean up generation scripts (~200 lines of dead code removed)
- Rewrite Cypress tests for standard HTML (no shadow DOM)

Templates moved from layouts/partials/api/hugo-native/ to parent.
All verifications pass (Hugo build, TypeScript compilation).
2026-02-13 15:07:02 -06:00
Jason Stirnaman 4959d93c26 feat(api): add Hugo-native API rendering POC
Add Hugo-native rendering as alternative to RapiDoc for API documentation.
Renders operations, parameters, request bodies, schemas, and responses
using Hugo templates styled after docusaurus-openapi aesthetic.

New partials:
- tag-renderer.html: Main renderer that loads OpenAPI spec
- operation.html: Operation block with header and sections
- parameters.html: Groups query/path/header parameters
- parameter-row.html: Individual parameter rendering
- request-body.html: Request body with schema
- schema.html: Recursive JSON schema rendering
- responses.html: Response status codes with schemas

Features:
- Parses OpenAPI YAML at build time (no JS required)
- Resolves $ref references for parameters and schemas
- Displays JSON examples from spec
- Color-coded status badges (2xx green, 4xx red)
- x-influxdata-related links rendered at page bottom
- Dark mode support
- Responsive design

Enable with `useHugoNative: true` in page frontmatter.
2026-02-13 00:07:18 -06:00
Jason Stirnaman f740f29dd9 feat(api): update API layouts and UI components
- Enhance section-children partial for tag-based article display
- Update all-endpoints-list with improved operation linking
- Refine security-schemes partial layout
- Update api-toc.ts for better navigation handling
- Improve api-menu-items sidebar rendering
- Update security schemes SCSS styling
- Remove outdated LLMS-TXT-README.md
2026-02-03 20:11:42 -06:00
Scott Anderson 39508ff6f1
feat(feature-boards): embed product feature boards in the docs (#6767)
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
2026-01-30 12:41:02 -07:00
Jason Stirnaman 727a9befb7 feat(api): consolidate API docs to tag pages with inline operations
Migrate API documentation from individual operation pages to tag pages
where all operations for a tag are rendered inline using RapiDoc.

Key changes:
- Remove operation links from left sidebar (tags only, no children)
- Generate server-side TOC from frontmatter operations array
- Show method badge + human-readable summary in TOC (not paths)
- Support hash-based navigation (#post-/api/v3/configure/distinct_cache)
- RapiDoc scrollToPath() handles TOC clicks to shadow DOM elements
- goto-path attribute initializes to operation from URL hash
- update-route attribute updates URL hash as user navigates

Files created:
- layouts/partials/api/rapidoc-tag.html

Files removed:
- layouts/api-path/path.html (path page layout)
- layouts/partials/api/rapidoc-path.html (path page partial)
- Old design documents superseded by 2026-01-21 version

Files modified:
- layouts/api/list.html (embed RapiDoc, server-side TOC)
- layouts/api/section.html (simplified section layout)
- layouts/_default/api.html (fallback layout cleanup)
- layouts/partials/sidebar/api-menu-items.html (remove op children)
- assets/js/components/rapidoc-mini.ts (tag page support)
- assets/js/components/api-toc.ts (RapiDoc navigation)
- api-docs/scripts/generate-openapi-articles.ts (disable path pages)
2026-01-29 23:46:09 -06:00
Jason Stirnaman 68f00e6805
fix(version-detector): centralize Grafana links and DRY up host examples (#6693)
* fix(version-detector): use centralized getGrafanaLink for all Grafana URLs

Refactor handleAuthorizationHelp to use getGrafanaLink() instead of
hardcoded URLs, ensuring all Grafana links come from a single source.

Also fix incorrect URLs in getGrafanaLink mapping:
- InfluxDB OSS 2.x: /visualize-data/ → /tools/
- InfluxDB Enterprise: /influxdb/enterprise/ → /enterprise_influxdb/v1/
- InfluxDB Cloud (TSM): /visualize-data/ → /tools/
- InfluxDB Cloud v1: now links to Enterprise v1 docs (Cloud v1 is
  Enterprise under the hood)

* refactor(version-detector): DRY up localhost:8086 references

Extract HOST_EXAMPLES to a class-level constant and add DEFAULT_HOST
and DEFAULT_HOST_PORT constants to eliminate duplicate localhost:8086
strings throughout the code.

- Move hostExamples from local variable to class constant
- Use DEFAULT_HOST for URL placeholder and comparison checks
- Use DEFAULT_HOST_PORT for docker curl command examples

* feat(ask-ai): Support source group IDs in Ask AI trigger links

* feat(version-detector): Present context-aware links

- Add ai_source_group_ids fields to ProductConfig interface
- Improve SCSS for doc and Ask AI links
- Update Grafana docs to add aliases and context param for detector
- Update modal partial to include AI source group IDs in config
- Remove custom Cypress commands for version detector
- Update E2E tests to use direct Cypress commands
2026-01-26 18:42:09 -06:00
Scott Anderson 5ade5e0178
fix(telegraf): link to plugins docs in the docs, update plugin cards (#6761) 2026-01-22 12:45:55 -07:00
Jason Stirnaman 2b226150ea feat(api): add match-type support to RapiDoc Mini component
Enables path-based filtering with match-type='includes' to show
all HTTP methods for an API path on a single page.
2026-01-20 14:48:29 -06:00
Jason Stirnaman 2374e17e89 fix(api): improve RapiDoc mobile responsive layout
Fix button cutoff on mobile screens by applying CSS fixes to RapiDoc's
nested shadow DOMs. Changes:

- Add getAllShadowRoots() to recursively find nested shadow roots
  (RapiDoc contains api-request elements with their own shadow DOMs)
- Apply button fixes to all shadow roots, not just the top-level one
- Add responsive CSS for endpoint cards to prevent horizontal overflow
- Remove debug console.log statements

Tested at viewport sizes 400x770 and 430x932.
2026-01-07 12:01:03 -06:00
Jason Stirnaman 9693417fd8 feat(api): Fix API reference tag-based section template (#6686)
* fix(api): refine .IsSection check to prevent breaking endpoint pages

The previous commit added an .IsSection check that correctly fixed
section index pages but inadvertently broke endpoint pages that Hugo
classifies as sections.

This commit refines the conditional to check for the absence of the
staticFilePath parameter, which distinguishes true section index pages
from endpoint pages that need the RapiDoc renderer:

- Section pages (no staticFilePath): Show children listing
- Endpoint pages (with staticFilePath): Use RapiDoc renderer

Fixes the regression introduced in commit 59daf17.

* chore: update Scalar references to RapiDoc in comments

Update code comments and documentation to accurately reflect that
the API documentation uses RapiDoc, not Scalar:

- api-docs/scripts/generate-openapi-articles.ts: Update JSDoc comments
- api-docs/scripts/dist/generate-openapi-articles.js: Update compiled version
- assets/js/components/api-toc.ts: Update implementation comment
- .claude/agents/ts-component-dev.md: Update component reference
- .claude/skills/hugo-template-dev/SKILL.md: Update component reference

The implementation uses RapiDoc throughout, so these comments needed
to be corrected for accuracy.

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-02 16:42:30 -06:00
Jason Stirnaman c57011df0e feat(api): improve auth UX with sessionStorage and fix styling issues
Auth credentials:
- Switch from in-memory to sessionStorage for credentials
- Credentials persist across page navigations within browser tab
- Auto-clear when tab closes (no long-term storage)
- Pre-fill form fields with saved credentials on page load
- Update status text and button based on credential state

Styling fixes:
- Add right padding to code blocks so Copy button doesn't overlap content
- Make long URLs wrap instead of requiring horizontal scroll
- Hide TOC sidebar when no headings exist (e.g., quick-start page)
- Remove "Use RapiDoc's navigation..." message from TOC

API docs:
- Remove x-codeSamples from write_lp endpoints (Core and Enterprise)
- Add schema descriptions for line protocol request body
2026-01-02 16:42:30 -06:00
Jason Stirnaman d258fa52cf fix(api): Remove duplicated Authentication section 2026-01-02 16:42:29 -06:00
Jason Stirnaman 6c25072ed3 feat(api): Convert auth input to popover with filtered schemes
- Convert collapsible auth panel to popover UI triggered by
  "Set credentials" button positioned above RapiDoc
- Filter auth schemes based on API path:
  - /api/v3/* endpoints: Bearer only
  - /api/v2/* endpoints: Bearer + Token
  - /write, /query (v1): All 4 schemes
- Fix "Authentication Not Required" bug by adding global security
  field to path-specific OpenAPI specs
- Change RapiDoc --blue CSS variable to green so status text and
  type links don't look like clickable links
- Add explicit button styling for Apply/Clear in popover
- Hide RapiDoc's built-in auth section (use custom popover instead)
2026-01-02 16:42:29 -06:00
Jason Stirnaman 1c8a2d3fa0 feat(api): Add custom auth input component for operation pages
- Create api-auth-input.ts TypeScript component
- Store credentials in sessionStorage (secure, cleared on tab close)
- Register component in main.js
- Add auth form styling with dark theme support
- Add component wrapper to rapidoc-mini.html template
- Fix SCSS dark theme (use CSS selectors, not non-existent mixin)
2026-01-02 16:42:28 -06:00
Jason Stirnaman 4ee1311e37 feat(api): Experiment with auth input visibility on operation pages
EXPERIMENTAL FINDINGS (Task 4):

Tested RapiDoc's allow-authentication attribute with both render-style
options to determine if it can show credential input on operation pages.

Results:
1. render-style='read' + allow-authentication='true':
   - Auth section (#auth) exists in shadow DOM with input fields
   - BUT filtered out by match-paths (not visible to users)
   - Only matched operation shown, not full spec

2. render-style='focused' + allow-authentication='true':
   - Auth section completely removed from shadow DOM
   - Shows broken links to non-existent #auth section
   - Lists security schemes but no input fields

CONCLUSION:
RapiDoc's built-in auth UI is incompatible with match-paths filtering.
When filtering to single operations, the auth section is either hidden
or removed entirely.

RECOMMENDATION:
Implement custom auth input component (Task 5) using:
- Custom TypeScript component above RapiDoc
- sessionStorage for credential persistence
- Integration with RapiDoc's Try it feature

Code includes detailed inline documentation of findings for future
reference when implementing Task 5.
2026-01-02 16:42:28 -06:00
Jason Stirnaman 3e6ce64fe1 style(api): Add security schemes section styling 2026-01-02 16:42:28 -06:00
Jason Stirnaman e38e6eb891 refactor(api): Remove deprecated api-tabs component
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.
2026-01-02 16:42:28 -06:00
Jason Stirnaman e2939dc715 refactor(api): Remove Scalar renderer and related code
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
2026-01-02 16:42:28 -06:00
Jason Stirnaman dcddc05f05 feat(api): Register api-rapidoc component in main.js 2026-01-02 16:42:28 -06:00
Jason Stirnaman 44bf81a5d8 feat(api): Create api-rapidoc TypeScript component
Extract inline JavaScript from rapidoc.html into a proper TypeScript
component following the established component pattern.
2026-01-02 16:42:27 -06:00
Jason Stirnaman a8a96feae1 style(api): Adjust All endpoints path font size to 0.9rem
Increase font size from 0.55rem to 0.9rem for better readability
while keeping the standard sans font for space efficiency.
2026-01-02 16:42:27 -06:00
Jason Stirnaman beb8088417 feat(api): Add section index and All endpoints nav item
- 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)
2026-01-02 16:42:27 -06:00
Jason Stirnaman 2fa00a36d2 fix(api): Fix RapiDoc operation filtering and improve API reference quality
- 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
2026-01-02 16:42:27 -06:00
Jason Stirnaman a1132142ff feat(api): Add RapiDoc Mini component for API operation pages
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
2026-01-02 16:42:27 -06:00
Jason Stirnaman 0328f539c0 feat(api): Add compatibility version badges for v1/v2 endpoints
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
2026-01-02 16:42:27 -06:00
Jason Stirnaman 31ab8776e9 refactor(api): Flatten API nav groups to single-tag items
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
2026-01-02 16:42:26 -06:00
Jason Stirnaman eb1ee7edbc refactor(api): Remove unused separate API nav code
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)
2026-01-02 16:42:26 -06:00
Jason Stirnaman c9b3e01554 fix(api): Reset button styles for dark mode, increase operation font 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
2026-01-02 16:42:26 -06:00
Jason Stirnaman 023e7495d4 fix(api): Match sidebar nav font sizes for operation items
- 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
2026-01-02 16:42:26 -06:00
Jason Stirnaman a0a4a16b39 fix(api): Show operations in sidebar nav, fix CSS for menu and summary
- 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%
2026-01-02 16:42:26 -06:00
Jason Stirnaman 54fc853c69 feat(api): Update config, styles, and content for API docs uplift
- 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
2026-01-02 16:42:25 -06:00
Jason Stirnaman 6a8562216e feat(api): Add TypeScript components for API UI interactions
- 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
2026-01-02 16:42:25 -06:00
Jason Stirnaman 802f7fac1e fix(api): Add operations list styling and regroup sidebar navigation
- 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
2026-01-02 16:42:24 -06:00
Scott Anderson dc62d0d011
Telegraf Controller (alpha) Documentation (#6685)
* feat: telegraf-controller scaffolding (#6625)

* feat: telegraf-ui scaffolding

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

* chore: add agent management docs for telegraf controller (#6635)

* chore: add agent management docs for telegraf controller

* fix: apply suggestions from copilot PR review

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

* chore(controller): italicize required callout

* fix(controller): fixed bad shortcode syntax

---------

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

* Install Telegraf Controller (#6676)

* feat(telegraf-controller): install telegraf controller

* 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>

* Manage configs with Telegraf Controller (#6681)

* chore(telegraf-controller): WIP manage configs docs

* feat(telegraf-controller): WIP manage configs

* feat(telegraf-controller): add dynamic value syntax highlighting

* feat(telegraf-controller): finish config management docs

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore(telegraf-controller): add info about updating config name and description

* chore(telegraf-controller): fix type in update config

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

* chore(telegraf-controller): add content to telegraf controller landing page (#6684)

* chore: update search for telegraf controller

* fix(links): ignore influxdata slack links

* fix(links): skip nssm download in link checks

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
2025-12-31 14:49:32 -07:00
Jason Stirnaman c2093c8212
Feature: Generate documentation in LLM-friendly Markdown (#6555)
* feat(llms): LLM-friendly Markdown, ChatGPT and Claude links.

This enables LLM-friendly documentation for entire sections,
allowing users to copy complete documentation sections with a single click.

Lambda@Edge now generates .md files on-demand with:
- Evaluated Hugo shortcodes
- Proper YAML frontmatter with product metadata
- Clean markdown without UI elements
- Section aggregation (parent + children in single file)

The llms.txt files are now generated automatically during build from
content structure and product metadata in data/products.yml, eliminating
the need for hardcoded files and ensuring maintainability.

**Testing**:
- Automated markdown generation in test setup via cy.exec()
- Implement dynamic content validation that extracts HTML content and
  verifies it appears in markdown version

**Documentation**:
Documents LLM-friendly markdown generation

**Details**:
Add gzip decompression for S3 HTML files in Lambda markdown generator

HTML files stored in S3 are gzip-compressed but the Lambda was attempting
to parse compressed data as UTF-8, causing JSDOM to fail to find article
elements. This resulted in 404 errors for .md and .section.md requests.

- Add zlib gunzip decompression in s3-utils.js fetchHtmlFromS3()
- Detect gzip via ContentEncoding header or magic bytes (0x1f 0x8b)
- Add configurable DEBUG constant for verbose logging
- Add debug logging for buffer sizes and decompression in both files

The decompression adds ~1-5ms per request but is necessary to parse
HTML correctly. CloudFront caching minimizes Lambda invocations.

Await async markdown conversion functions

The convertToMarkdown and convertSectionToMarkdown functions are async
but weren't being awaited, causing the Lambda to return a Promise object
instead of a string. This resulted in CloudFront validation errors:
"The body is not a string, is not an object, or exceeds the maximum size"

**Troubleshooting**:

- Set DEBUG for troubleshooting in lambda

* feat(llms): Add build-time LLM-friendly Markdown generation

Implements static Markdown generation during Hugo build.

**Key Features:**
- Two-phase generation: HTML→MD (memory-bounded), MD→sections (fast)
- Automatic redirect detection via file size check (skips Hugo aliases)
- Product detection using compiled TypeScript product-mappings module
- Token estimation for LLM context planning (4 chars/token heuristic)
- YAML serialization with description sanitization

**Performance:**
- ~105 seconds for 5,000 pages + 500 sections
- ~300MB peak memory (safe for 2GB CircleCI environment)
- 23 files/sec conversion rate with controlled concurrency

**Configuration Parameters:**
- MIN_HTML_SIZE_BYTES (default: 1024) - Skip files below threshold
- CHARS_PER_TOKEN (default: 4) - Token estimation ratio
- Concurrency: 10 workers (CI), 20 workers (local)

**Output:**
- Single pages: public/*/index.md (with frontmatter + content)
- Section bundles: public/*/index.section.md (aggregated child pages)

**Files Changed:**
- scripts/build-llm-markdown.js (new) - Main build script
- scripts/lib/markdown-converter.cjs (renamed from .js) - Core conversion
- scripts/html-to-markdown.js - Updated import path
- package.json - Updated exports for .cjs module

Related: Replaces Lambda@Edge on-demand generation (5s response time)
with build-time static generation for production deployment.

feat(deploy): Add staging deployment workflow and update CI

Integrates LLM markdown generation into deployment workflows with
a complete staging deployment solution.

**CircleCI Updates:**
- Switch from legacy html-to-markdown.js to optimized build:md
- 2x performance improvement (105s vs 200s+ for 5000 pages)
- Better memory management (300MB vs variable)
- Enables section bundle generation (index.section.md files)

**Staging Deployment:**
- New scripts/deploy-staging.sh for local staging deploys
- Complete workflow: Hugo build → markdown gen → S3 upload
- Environment variable driven configuration
- Optional step skipping for faster iteration
- CloudFront cache invalidation support

**NPM Scripts:**
- Added deploy:staging command for convenience
- Wraps deploy-staging.sh script

**Documentation:**
- Updated DOCS-DEPLOYING.md with comprehensive guide
- Merged staging/production workflows with Lambda@Edge docs
- Build-time generation now primary, Lambda@Edge fallback
- Troubleshooting section with common issues
- Environment variable reference
- Performance metrics and optimization tips

**Benefits:**
- Manual staging validation before production
- Consistent markdown generation across environments
- Faster CI builds with optimized script
- Better error handling and progress reporting
- Section aggregation for improved LLM context

**Usage:**
```bash
export STAGING_BUCKET="test2.docs.influxdata.com"
export AWS_REGION="us-east-1"
export STAGING_CF_DISTRIBUTION_ID="E1XXXXXXXXXX"

yarn deploy:staging
```

Related: Completes build-time markdown generation implementation

refactor: Remove Lambda@Edge implementation

Build-time markdown generation has replaced Lambda@Edge on-demand
generation as the primary method. Removed Lambda code and updated
documentation to focus on build-time generation and testing.

Removed:
- deploy/llm-markdown/ directory (Lambda@Edge code)
- Lambda@Edge section from DOCS-DEPLOYING.md

Added:
- Testing and Validation section in DOCS-DEPLOYING.md
- Focus on build-time generation workflow

* feat: Add Rust HTML-to-Markdown prototype

Implements core markdown-converter.cjs functions in Rust for performance comparison.

Performance results:
- Rust: ~257 files/sec (10× faster)
- JavaScript: ~25 files/sec average

Recommendation: Keep JavaScript for now, implement incremental builds first.
Rust migration provides 10× speedup but requires 3-4 weeks integration effort.

Files:
- Cargo.toml: Rust dependencies (html2md, scraper, serde_yaml, clap)
- src/main.rs: Core conversion logic + CLI benchmark tool
- benchmark-comparison.js: Side-by-side performance testing
- README.md: Comprehensive findings and recommendations

* fix(ui): improve dropdown positioning on viewport resize

- Ensure dropdown stays within viewport bounds (min 8px padding)
- Reposition dropdown on window resize and scroll events
- Clean up event listeners when dropdown closes

* chore(deps): add remark and unified packages for markdown processing

Add remark-parse, remark-frontmatter, remark-gfm, and unified for
enhanced markdown processing capabilities.

* fix(edge): add return to prevent trailing-slash redirect for valid extensions

Without the return statement, the Lambda@Edge function would continue
executing after the callback, eventually hitting the trailing-slash
redirect logic. This caused .md files to redirect to URLs with trailing
slashes, which returned 404 from S3.

* fix(md): add built-in product mappings and full URL support

- Add URL_PATTERN_MAP and PRODUCT_NAME_MAP constants directly in the
  CommonJS module (ESM product-mappings.js cannot be require()'d)
- Update generateFrontmatter() to accept baseUrl parameter and construct
  full URLs for the frontmatter url field
- Update generateSectionFrontmatter() similarly for section pages
- Update all call sites to pass baseUrl parameter

This fixes empty product fields and relative URLs in generated markdown
frontmatter when served via Lambda@Edge.

* feat(md): add environment flag for base URL control

Add -e, --env flag to html-to-markdown.js to control the base URL
in generated markdown frontmatter. This matches Hugo's -e flag behavior
and allows generating markdown with staging or production URLs.

Also update build-llm-markdown.js with similar environment support.

* feat(md): add Rust markdown converter and improve validation

- Add Rust-based HTML-to-Markdown converter with NAPI-RS bindings
- Update Cypress markdown validation tests
- Update deploy-staging.sh with force upload flag

* deploy-staging.sh:
  - Defaults STAGING_URL to https://test2.docs.influxdata.com
  if not set
  - Exports it so yarn build:md -e staging can use it
  - Displays it in the summary

* Delete scripts/prototypes/rust-markdown/benchmark-comparison.js

* Delete scripts/prototypes directory

* fix(llms): Include full URL for section page Markdown and list of child pages

* feat(llms): clarify format selector text for AI use case

Update button and dropdown text to make the AI/LLM purpose clearer:
- Button: "Copy page for AI" / "Copy section for AI"
- Sublabel: "Clean Markdown optimized for AI assistants"
- Section sublabel: "{N} pages combined as clean Markdown for AI assistants"

Cypress tests updated and passing (13/13).

---------

Co-authored-by: Scott Anderson <scott@influxdata.com>
2025-12-01 12:32:28 -06:00
Jason Stirnaman f084fe3a31
Ask AI group filters (#6529)
* feat(askai): add Kapa.ai source group filtering for InfluxDB v3

- Add ai_source_group_ids field to all InfluxDB v3 products in data/products.yml
- Add getProductSourceGroupIds() function to retrieve source group IDs from product data
- Enables filtered AI responses using Kapa source groups for documentation pages
- Follows existing pattern for dynamic product configuration
- Implement version-specific config support (__v1, __v2 suffixes)
- Append version hints to example questions for InfluxDB database products only
- Make example questions generic (remove product-specific names)
- Tools (Telegraf, Chronograf, Kapacitor, Flux, Explorer) display questions without version hints
- Pre-fills chat input with [version: /path/] for InfluxDB database products
- Users can easily edit or remove the pre-filled text
- Works for manual opens (Cmd+K) and programmatic opens
- Converts module to TypeScript

* refactor(ask-ai): change version format to 'My version: <product name>'

Use human-readable product names instead of URL paths for better UX.
Example: 'My version: InfluxDB 3 Core' instead of '[version: /influxdb3/core/]'

* fix(ask-ai): restore working Kapa.open() pre-fill implementation

- Replace textarea detection with direct Kapa.open() call
- Add Kapa preinitialization code
- Use click handler on .ask-ai-open button with capture phase
- Handle conversation reset event to re-fill version context
- Remove console logging for cleaner production code

* fix(ask-ai): remove parentheses from example questions for consistency

Make example question format match the pre-fill format:
- Before: 'question (My version: product)'
- After: 'question My version: product'

This ensures users don't think there's a difference between the two formats.

* fix(askai): add Explorer product mapping for Ask AI widget

- Add influxdb3_explorer mapping to getCurrentProductData()
- Add explorer context to getContext() function
- Ensures Explorer pages use correct ai_sample_questions from products.yml
- Reorder Explorer questions with 'install and run' first

This fixes the issue where Explorer Ask AI widget was showing wrong
example questions by properly loading the influxdb3_explorer config.

* test(page-context): add comprehensive e2e tests for product mappings

Add Cypress tests to validate page-context.js correctly identifies:
- Product context values for all InfluxDB products
- Product data from products.yml configuration
- Version information
- AI sample questions and source group IDs
- Placeholder host values

Tests cover:
- InfluxDB 3 (Core, Enterprise, Explorer, Cloud variants, Clustered)
- InfluxDB v2 and v1
- InfluxDB Cloud (TSM)
- Tools (Telegraf, Chronograf, Kapacitor, Flux)

Validates the fix for Explorer Ask AI showing correct example questions.

Related to #jts-askai-group-filters branch work.

* feat(test): add --no-mapping flag to e2e test runner

Allow running functionality tests without requiring content file paths.
The --no-mapping flag skips content-to-URL mapping, making it easier
to run tests that don't depend on specific content files.

Usage:
  # With content mapping (for content-specific tests)
  node run-e2e-specs.js content/influxdb3/core/_index.md

  # Without content mapping (for functionality tests)
  node run-e2e-specs.js --spec cypress/e2e/page-context.cy.js --no-mapping

Benefits:
- Simplifies running functionality tests like page-context.cy.js
- Reduces test startup time by skipping unnecessary file mapping
- Makes test commands clearer about their purpose

The page-context test was updated to work correctly with this flag.

* deps: update caniuse and related hook files

* test: Add a `--no-mapping` flag to run tests without specific content files (i.e., test contains all the URLs it needs)

* chore(ask-ai): Format example questions

* test(page-context): add comprehensive e2e tests for all products in products.yml

- Expanded test suite from 6 to 27 tests covering all products
- Added tests for InfluxDB 3 products (Explorer, Core, Enterprise, Cloud Serverless, Cloud Dedicated, Clustered)
- Added tests for InfluxDB v2 and Cloud (TSM)
- Added tests for InfluxDB v1 and Enterprise v1
- Added tests for other products (Telegraf, Chronograf, Kapacitor, Flux)
- Validates page mappings in page-context.js
- Validates AI sample questions configuration in products.yml
- All 27 tests passing

* fix(page-context): correct enterprise_influxdb URL pattern matching

- Changed pattern from /enterprise_v1/ to /enterprise_influxdb/
- Fixes Ask AI example questions not showing correctly for Enterprise v1
- Pattern now matches actual URL structure /enterprise_influxdb/v1/
- All 27 e2e tests passing

* test(page-context): add UI validation for Ask AI widget configuration

- Added 4 tests checking Kapa widget script data attributes
- Tests verify data-modal-example-questions contains correct product-specific questions
- Validates Explorer, Core, Enterprise, and Enterprise v1 configurations
- All 31 tests passing (27 existing + 4 new UI tests)

* feat(ask-ai): add help in Ask AI widget placeholder

- InfluxDB placeholder recommends specifying product and version
- Fix page-context.js to use products.influxdb_cloud instead of products.cloud
- Add UI tests verifying version-specific naming in Kapa widget script tags

* feat(ask-ai): Tailors placeholder for each version/product. Disables "Viewing <product>" in disclaimer note.
2025-11-18 16:43:02 -06:00
Jason Stirnaman 26ca68d405
Merge branch 'master' into update-grafana-docs 2025-10-06 17:34:12 -05:00
Scott Anderson c3468f667d
feat(sample-data): add new wind sample dataset (#6440)
* feat(sample-data): add new wind sample dataset

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

* fix(js): fix syntax error and lint

---------

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
2025-10-06 12:08:35 -06:00
Jason Stirnaman 9833b9bf90
Merge pull request #6399 from influxdata/feature/influxdb-version-detector
Feature/influxdb version detector
2025-10-04 16:03:53 -05:00
Scott Anderson 5735f5f704
feat(caches): update explorer docs with information about querying LVCs and DVCs (#6437) 2025-10-01 09:43:16 -06:00
Jason Stirnaman 2690de8a72
Merge branch 'master' into feature/influxdb-version-detector 2025-10-01 10:38:32 -05:00