* fix(ci): add path offset for PR preview subdirectory baseURL
When PR preview builds use a subdirectory baseURL like
/docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink
to detect product context fail because the path has extra segments.
This fix:
- Adds config/pr-preview/params.yml with prPreviewPathOffset: 3
- Updates workflow to use -e pr-preview environment
- Updates api-endpoint, influxdb/host, and children shortcodes to
use the offset when indexing path segments
- Adds nil-safety with default fallback for placeholder_host
Normal builds are unaffected (offset defaults to 0).
* fix(ci): add path offset to product-name and sidebar for PR previews
Apply the same prPreviewPathOffset fix to product-name.html and
sidebar.html that was applied in the initial PR #6665.
These templates parse RelPermalink to detect product context, but when
baseURL includes a subdirectory path (e.g., /docs-v2/pr-preview/pr-XXXX/),
the path indices shift. This fix uses the configurable offset to skip
extra path segments in PR preview builds.
* fix(ci): skip PR preview for fork PRs and add notice comment
Fork PRs cannot deploy to gh-pages because GITHUB_TOKEN has read-only
access to the base repository. This is a GitHub security feature.
Changes:
- Add condition to skip preview job for fork PRs
- Add fork-notice job to post helpful comment explaining limitation
- Include local preview instructions for contributors
When PR preview builds use a subdirectory baseURL like
/docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink
to detect product context fail because the path has extra segments.
This fix:
- Adds config/pr-preview/params.yml with prPreviewPathOffset: 3
- Updates workflow to use -e pr-preview environment
- Updates api-endpoint, influxdb/host, and children shortcodes to
use the offset when indexing path segments
- Adds nil-safety with default fallback for placeholder_host
Normal builds are unaffected (offset defaults to 0).
* 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>
* 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.
* chore(enterprise_influxdb): specify Enterprise v1 and remove new signup notes:
- Removes instructions for new signups at portal.influxdata (at Marketing's request)
- Uses Enterprise v1 in titles and descriptions
- Updates title metadata template to use InfluxDB Enterprise v1
- Updates products.yml to use InfluxDB Enterprise v1
- Removes unused enterprise-name/-link shortcodes
I chose InfluxDB Enterprise v1 over InfluxDB v1 Enterprise due to recent usage patterns and because it's compatible with uses like "InfluxDB Enterprise 1.11.x" without being redundant.
* Apply suggestion from @jstirnaman
* Apply suggestion from @jstirnaman
* Apply suggestion from @jstirnaman
Creates an interactive InfluxDB version detector component in TypeScript and a shortcode that generates a button to trigger
the version detector modal.
The shortcode takes a parameter that displays a predefined set of links for results.
- Support URL pattern matching and ping header analysis
- Add questionnaire-based product identification logic
- Adds the shortcode in a note in /influxdb3/core/visualize-data/grafana/
- Set up TypeScript configuration for the project
- Configure automatic TypeScript compilation in pre-commit hooks
- Add to Grafana documentation pages
- Remove last remnants of old Cypress link checker
- Add Cypress tests, but many are still broken
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Apply suggestions from code review
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Update layouts/shortcodes/influxdb-version-detector.html
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Update assets/js/influxdb-version-detector.ts
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Update assets/styles/components/_influxdb-version-detector.scss
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Fixes:
- Fix Hugo template to include product names in detector config
- Change elimination scores from -100 to -1000 for proper filtering
- Add scoring logic for generic "InfluxDB" product (OSS v2.x)
- Exclude generic "InfluxDB" from results (too vague)
- Add comprehensive test scenario checklist to Cypress tests
- Free license now correctly excludes Enterprise, Clustered, Dedicated
- Self-hosted now correctly excludes all Cloud products
- SQL language now correctly excludes v1 and v2 products
- Results now show only specific products (OSS 1.x, OSS 2.x, etc.)
Changes:
- When users answer "I'm not sure" to all questions, show a helpful
message directing them to the reference table instead of showing
a weak ranking with low confidence.
- Detect when all questionnaire answers are "unknown"
- Display custom message explaining lack of information
- Auto-expand reference table for easy product identification
- Hide ranked results when insufficient information provided
- Make product names clickable in the quick reference table to allow
users to quickly navigate to product documentation after identifying
their InfluxDB version.
* feat(html): resursive lef nav
* Update layouts/partials/sidebar/nested-menu.html
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* add depth to left nav template to assign category or item class
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Build resources if not cached
- Ensure node_modules dependencies are available for asset processing
- Be more precise in the template when building assets in production mode and avoid conflicts with SCSS and CSS processing.
- Ignore node_modules when loading source maps
- Add .vscode/launch.json with debugging configuration for localhost:1313. In VSCode, go to Run and select the site to launch Chrome, connect to Developer Tools, and start debugging.
- Add support for debugging in VS Code without using source maps. Adds a debug helpers module for developers to use in IDE debugging and interact with the browser console. This is a workaround for lack of good source map support with js.Build and the Hugo asset pipeline.
Background:
Hugo and js.Build don't have good support for external source maps.
Internal source mapping is also unreliable; the base64 in the source map reference for some files is too long for the browser console to keep on 1 line--remaining characters are printed on the next line, resulting in a syntax error.
1. Refactor JavaScript from search.html into a new DocSearch Component Module. The component needs to include: - Asynchronous loading of Algolia docsearch.min.js - Proper Algolia search facets:
- Nested arrays for AND conditions: In Algolia, filters in the same array are combined with OR, while arrays in an array are combined with AND
- Space after colon: Algolia's parser expects this specific format
2. Update Search HTML Template: refactor the search.html to use the new component:
3. Register the Component in main.js: update main.js to import and register our new DocSearch component:
Improve SearchInteractions event handler coordination with DocSearch:
- Improve SearchInteractions to dynamically detect the dropdown added by Algolia DocSearch and ensure that blur and focus event handlers are registered after the dropdown loads.
Benefits of This Approach:
Asynchronous Loading: DocSearch.js is now loaded asynchronously, improving page load performance
Search functionality is encapsulated as a component
Clean Separation: HTML template only contains configuration data, not implementation
Event Communication: Components can react to DocSearch initialization via events
SearchInteractions dynamically detects dropdown: Instead of waiting for an event or using setTimeout, we actively observe DOM changes to detect when the dropdown is created.
Nested Observation: A second observer monitors changes to the dropdown itself, allowing code to respond to style changes.
Better Event Handling: The blur handler checks if the related target is inside the search components, preventing unwanted dropdown closing.
Resource Cleanup: The cleanup function disconnects all observers, preventing memory leaks.
Additional Interaction Control: Adds an event listener to the dropdown to prevent unwanted blur events when interacting with search results.
* update: start explorer docs
* fix(explorer): Add Explorer to products.yml, move to version folder, add get-started step nav, cleanup
* Updated explorer directory structure, homepage, and beta styling (#6108)
* updated explorer dirctory struction, homepage, and beta styling
* clean up homepage state tags
* Add InfluxDB 3 Explorer installation documentation (#6111)
* InfluxDB 3 Explorer installation instructions
* fixed broken links
* Apply suggestions from code review
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* update: add getting started video
* updated to address PR feedback
* adjust page weights for explorer docs
* other minor updates
* more minor updates
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Peter Barnett <peter.barnett03@gmail.com>
---------
Co-authored-by: Jason Stirnaman <stirnamanj@gmail.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Fixed logic to maintain current product context while using successor for version info
- Added appropriate successor product display in callout warning
- Fixed conditions for when callout should appear
- Fixed potential `isset <nil>` problems with proper nil checks before accessing properties
- **Added comprehensive Cypress tests for successor relationship**
- Created `stable-version-callout.cy.js` for testing successor behavior
- Tests that `/influxdb/v1/` and `/influxdb/v2/` pages show successor callout
- Verifies "InfluxDB 3 Core" appears in callout with correct links
- Checks product data configuration in `products.yml`
- Includes JavaScript error detection
- **Configured environment-specific Hugo settings**
- Added `/config/testing/config.yml` for test environment
- Configured port 1315 for test environment
- Added build parameters specific to testing context
- Separated test environment from development environment
- **Updated Docker configuration**
- Added new package.json script for building Docker image
- Improved Docker-based testing commands
- **Environment variable formatting** - Updated environment variable configuration from array format to object format to comply with Lefthook schema validation requirements.
- **Unified link testing** - Consolidated multiple product-specific link testing commands into a single `e2e-links` command that processes all staged Markdown and HTML files across content directories.
- **Package script integration** - Modified commands to use centralized yarn scripts instead of direct execution, improving maintainability and consistency.
- **Source information extraction** - Enhanced to correctly extract and report source information from frontmatter.
- **URL and source mapping** - Improved handling of URL to source path mapping for better reporting.
- **Ignored anchor links configuration** - Added proper exclusion of behavior-triggering anchor links (like tab navigation) to prevent false positives.
- **Request options correction** - Fixed Cypress request options to ensure `failOnStatusCode` is properly set when `retryOnStatusCodeFailure` is enabled.
- **Improved error reporting** - Enhanced error reporting with more context about broken links.
- **New test scripts added** - Added centralized testing scripts for link checking and codeblock validation.
- **Product-specific test commands** - Added commands for each product version (InfluxDB v2, v3 Core, Enterprise, Cloud, etc.).
- **API docs testing** - Added specialized commands for testing API documentation links.
- **Comprehensive test runners** - Added commands to run all tests of a specific type (`test:links:all`, `test:codeblocks:all`).
- Fix Docker build command and update CONTRIBUTING.
chore(js): JavaScript QoL improvements:
- Refactor main.js with a componentRegistry object and clear initialization of components and globals
- Add a standard index.js with all necessary exports.
- Update javascript.html to use the index.js
- Remove jQuery script tag from header javascript.html (remains in footer)
- Update package file to improve module discovery.
- Improve Hugo and ESLint config for module discovery and ES6 syntax
- Add a frontmatter test-only attribute for files like example.md. Don't use draft: true for these files.
- Add support in index.html for the attribute so that the files are only rendered when running in the testing environment.
- e2e smoke test using example.md, ensure it renders without JavaScript errors.
- Assigns the match expression to a data attribute (data-id) to use in eleement selection. Previously, it assigned the regex expression to input.id and used the ID to select the element when updating the placeholder value. A regex that starts with a slash causes an error; input#/path/to/match isn't a valid id.
- Supports placeholders like '\/path\/to\/file.parquet'
- Refactors code-placeholders to the component pattern.
Scott Anderson
Jason Stirnaman
Bill O'Connell
Bill OConnell
peterbarnett03
Scott Anderson
Jason Stirnaman
Jamie Strandboge
Sven Rebhan
Gary Fowler