From 38b08ecc515d00ba5200975617e6339f58acce41 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 25 Jun 2025 14:38:23 -0500 Subject: [PATCH 1/4] chore(qol): Add claude instructions file for the project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLAUDE.md file successfully references 5 key files, all of which exist and are accessible: 1. @README → README.md - Project overview and setup 2. @package.json → package.json - NPM scripts and dependencies 3. @.github/copilot-instructions.md → Main style guidelines and product info 4. @.github/instructions/contributing.instructions.md → Detailed contributing guide 5. @.github/instructions/influxdb3-code-placeholders.instructions.md → InfluxDB 3 specific guidelines 📊 Current Structure Analysis The CLAUDE.md file acts as a minimal index that: - Delegates detailed instructions to other files - Uses Claude's @ symbol notation for file references - Provides a clear hierarchy of information 💡 Key Instructions Coverage Through the linked files, Claude has access to: - Product documentation paths for all InfluxDB versions - Style guidelines following Google Developer Documentation standards - Shortcode usage with extensive examples - Testing procedures including pytest-codeblocks - Development workflows with Docker and Node.js - Placeholder conventions for code examples - Frontmatter requirements for Hugo pages --- .github/copilot-instructions.md | 26 +++++++++++++++++---- CLAUDE.md | 25 ++++++++++++++++++++ build-scripts/build-copilot-instructions.js | 4 ++-- 3 files changed, 49 insertions(+), 6 deletions(-) create mode 100644 CLAUDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 505688122..a4c0b7aaa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,13 +1,16 @@ -# GitHub Copilot Instructions for InfluxData Documentation +# Instructions for InfluxData Documentation ## Purpose and scope -GitHub Copilot should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. +Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. ## Documentation structure - **Product version data**: `/data/products.yml` -- **Products**: +- **InfluxData products**: + - InfluxDB 3 Explorer + - Documentation source path: `/content/influxdb3/explorer` + - Published for the web: https://docs.influxdata.com/influxdb3/explorer/ - InfluxDB 3 Core - Documentation source path: `/content/influxdb3/core` - Published for the web: https://docs.influxdata.com/influxdb3/core/ @@ -92,7 +95,8 @@ GitHub Copilot should help document InfluxData products by creating clear, accur ## Markdown and shortcodes -- Include proper frontmatter for each page: +- Include proper frontmatter for Markdown pages in `content/**/*.md` (except for + shared content files in `content/shared/`): ```yaml title: # Page title (h1) @@ -180,3 +184,17 @@ Table: keys: [_start, _stop, _field, _measurement] ## Related repositories - **Internal documentation assistance requests**: https://github.com/influxdata/DAR/issues Documentation + +## Additional instruction files + +For specific workflows and content types, also refer to: + +- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md` - Guidelines for placeholder formatting, descriptions, and shortcode usage in InfluxDB 3 documentation +- **Contributing guidelines**: `.github/instructions/contributing.instructions.md` - Detailed style guidelines, shortcode usage, frontmatter requirements, and development workflows +- **Content-specific instructions**: Check `.github/instructions/` directory for specialized guidelines covering specific documentation patterns and requirements + +## Integration with specialized instructions + +When working on InfluxDB 3 documentation (Core/Enterprise), prioritize the placeholder guidelines from `influxdb3-code-placeholders.instructions.md`. + +For general documentation structure, shortcodes, and development workflows, follow the comprehensive guidelines in `contributing.instructions.md`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..97f250d72 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# Instructions for InfluxData Documentation + +## Purpose and scope + +Claude should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. + +## Project overview + +See @README.md + +## Available NPM commands + +@package.json + +## Instructions for contributing + +See @.github/copilot-instructions.md for style guidelines and +product-specific documentation paths and URLs managed in this project. + +See @.github/instructions/contributing.instructions.md for contributing +information including using shortcodes and running tests. + +See @.github/instructions/influxdb3-code-placeholders.instructions.md for using +placeholders in code samples and CLI commands. + diff --git a/build-scripts/build-copilot-instructions.js b/build-scripts/build-copilot-instructions.js index 0d089e2c1..490fc266c 100644 --- a/build-scripts/build-copilot-instructions.js +++ b/build-scripts/build-copilot-instructions.js @@ -46,11 +46,11 @@ function buildContributingInstructions() { applyTo: "content/**/*.md, layouts/**/*.html" --- -# GitHub Copilot Instructions for InfluxData Documentation +# Contributing instructions for InfluxData Documentation ## Purpose and scope -GitHub Copilot should help document InfluxData products +Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, shortcodes, and formatting. From d20492b6feff089f8a02e21e3b2218c368e76d13 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 25 Jun 2025 09:40:50 -0500 Subject: [PATCH 2/4] chore(analytics): Migrate to GA4 Google tag. If on the local server, use debug mode and prevent tracking. Add the www.influxdata.com Google tag script. Remove the conditional from header.html. Remove the old, unused GTM ID --- assets/js/code-controls.js | 155 +++++++++++++++++- config/staging/hugo.yml | 3 +- layouts/partials/header.html | 2 +- .../header/google-analytics-head.html | 35 +++- 4 files changed, 184 insertions(+), 11 deletions(-) diff --git a/assets/js/code-controls.js b/assets/js/code-controls.js index 17018a8e8..19ec0ef7c 100644 --- a/assets/js/code-controls.js +++ b/assets/js/code-controls.js @@ -1,4 +1,5 @@ import $ from 'jquery'; +import { context } from './page-context.js'; function initialize() { var codeBlockSelector = '.article--content pre'; @@ -68,9 +69,94 @@ function initialize() { // Trigger copy failure state lifecycle $('.copy-code').click(function () { - let text = $(this) + let codeElement = $(this) .closest('.code-controls') - .prevAll('pre:has(code)')[0].innerText; + .prevAll('pre:has(code)')[0]; + + let text = codeElement.innerText; + + // Extract additional code block information + const codeBlockInfo = extractCodeBlockInfo(codeElement); + + // Add Google Analytics event tracking + const currentUrl = new URL(window.location.href); + + // Determine which tracking parameter to add based on product context + switch (context) { + case 'cloud': + currentUrl.searchParams.set('dl', 'cloud'); + break; + case 'core': + /** Track using the same value used by www.influxdata.com pages */ + currentUrl.searchParams.set('dl', 'oss3'); + break; + case 'enterprise': + /** Track using the same value used by www.influxdata.com pages */ + currentUrl.searchParams.set('dl', 'enterprise'); + break; + case 'serverless': + currentUrl.searchParams.set('dl', 'serverless'); + break; + case 'dedicated': + currentUrl.searchParams.set('dl', 'dedicated'); + break; + case 'clustered': + currentUrl.searchParams.set('dl', 'clustered'); + break; + case 'oss/enterprise': + currentUrl.searchParams.set('dl', 'oss'); + break; + case 'other': + default: + // No tracking parameter for other/unknown products + break; + } + + // Add code block specific tracking parameters + if (codeBlockInfo.language) { + currentUrl.searchParams.set('code_lang', codeBlockInfo.language); + } + if (codeBlockInfo.lineCount) { + currentUrl.searchParams.set('code_lines', codeBlockInfo.lineCount); + } + if (codeBlockInfo.hasPlaceholders) { + currentUrl.searchParams.set('has_placeholders', 'true'); + } + if (codeBlockInfo.blockType) { + currentUrl.searchParams.set('code_type', codeBlockInfo.blockType); + } + if (codeBlockInfo.sectionTitle) { + currentUrl.searchParams.set( + 'section', + encodeURIComponent(codeBlockInfo.sectionTitle) + ); + } + if (codeBlockInfo.firstLine) { + currentUrl.searchParams.set( + 'first_line', + encodeURIComponent(codeBlockInfo.firstLine.substring(0, 100)) + ); + } + + // Update browser history without triggering page reload + if (window.history && window.history.replaceState) { + window.history.replaceState(null, '', currentUrl.toString()); + } + + // Send custom Google Analytics event if gtag is available + if (typeof window.gtag !== 'undefined') { + window.gtag('event', 'code_copy', { + language: codeBlockInfo.language, + line_count: codeBlockInfo.lineCount, + has_placeholders: codeBlockInfo.hasPlaceholders, + dl: codeBlockInfo.dl || null, + section_title: codeBlockInfo.sectionTitle, + first_line: codeBlockInfo.firstLine + ? codeBlockInfo.firstLine.substring(0, 100) + : null, + product: context, + }); + } const copyContent = async () => { try { @@ -84,6 +170,71 @@ function initialize() { copyContent(); }); + /** + * Extract contextual information about a code block + * @param {HTMLElement} codeElement - The code block element + * @returns {Object} Information about the code block + */ + function extractCodeBlockInfo(codeElement) { + const codeTag = codeElement.querySelector('code'); + const info = { + language: null, + lineCount: 0, + hasPlaceholders: false, + blockType: 'code', + dl: null, // Download script type + sectionTitle: null, + firstLine: null, + }; + + // Extract language from class attribute + if (codeTag && codeTag.className) { + const langMatch = codeTag.className.match( + /language-(\w+)|hljs-(\w+)|(\w+)/ + ); + if (langMatch) { + info.language = langMatch[1] || langMatch[2] || langMatch[3]; + } + } + + // Count lines + const text = codeElement.innerText || ''; + const lines = text.split('\n'); + info.lineCount = lines.length; + + // Get first non-empty line + info.firstLine = lines.find((line) => line.trim() !== '') || null; + + // Check for placeholders (common patterns) + info.hasPlaceholders = + /\b[A-Z_]{2,}\b|\{\{[^}]+\}\}|\$\{[^}]+\}|<[^>]+>/.test(text); + + // Determine if this is a download script + if (text.includes('https://www.influxdata.com/d/install_influxdb3.sh')) { + if (text.includes('install_influxdb3.sh enterprise')) { + info.dl = 'enterprise'; + } else { + info.dl = 'oss3'; + } + } else if (text.includes('docker pull influxdb:3-enterprise')) { + info.dl = 'enterprise'; + } else if (text.includes('docker pull influxdb3-core')) { + info.dl = 'oss3'; + } + + // Find nearest section heading + let element = codeElement; + while (element && element !== document.body) { + element = element.previousElementSibling || element.parentElement; + if (element && element.tagName && /^H[1-6]$/.test(element.tagName)) { + info.sectionTitle = element.textContent.trim(); + break; + } + } + + return info; + } + /////////////////////////////// FULL WINDOW CODE /////////////////////////////// /* diff --git a/config/staging/hugo.yml b/config/staging/hugo.yml index 3a0a651c2..7d22ffb17 100644 --- a/config/staging/hugo.yml +++ b/config/staging/hugo.yml @@ -13,6 +13,7 @@ minify: params: env: staging environment: staging -server: +server: { disableLiveReload: true +} \ No newline at end of file diff --git a/layouts/partials/header.html b/layouts/partials/header.html index 7960d5ed8..419f86196 100644 --- a/layouts/partials/header.html +++ b/layouts/partials/header.html @@ -5,7 +5,7 @@ - {{ if not hugo.IsServer }}{{ partial "header/google-analytics-head.html" }}{{ end }} + {{ partial "header/google-analytics-head.html" }} diff --git a/layouts/partials/header/google-analytics-head.html b/layouts/partials/header/google-analytics-head.html index 42d1a516b..0880fb083 100644 --- a/layouts/partials/header/google-analytics-head.html +++ b/layouts/partials/header/google-analytics-head.html @@ -1,7 +1,28 @@ - - - +{{ if and hugo.IsServer (not (eq .Site.Params.environment "staging")) }} + + + +{{ else }} + + + +{{ end }} From 8e040c8eb3bf01023a000d5ee32ad5ac50c562fe Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 27 Jun 2025 14:44:28 -0500 Subject: [PATCH 3/4] fix(core,ent3): and related params are required (closes #6166) --- content/influxdb3/core/reference/cli/influxdb3/serve.md | 4 ++-- content/influxdb3/core/reference/config-options.md | 4 ++-- .../influxdb3/enterprise/reference/cli/influxdb3/serve.md | 4 ++-- content/influxdb3/enterprise/reference/config-options.md | 2 +- content/shared/influxdb3-get-started/setup.md | 5 ++++- 5 files changed, 11 insertions(+), 8 deletions(-) diff --git a/content/influxdb3/core/reference/cli/influxdb3/serve.md b/content/influxdb3/core/reference/cli/influxdb3/serve.md index a769cb652..c6001d47b 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/core/reference/cli/influxdb3/serve.md @@ -24,8 +24,8 @@ influxdb3 serve [OPTIONS] --node-id ## Required parameters - **node-id**: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store. -- **object-store**: Determines where time series data is stored. _Default is `memory`_. -- **data-dir**: Path for local file storage (required when using `--object-store file`). +- **object-store**: Determines where time series data is stored. +- Other object store parameters depending on the selected `object-store` type. > [!NOTE] > `--node-id` supports alphanumeric strings with optional hyphens. diff --git a/content/influxdb3/core/reference/config-options.md b/content/influxdb3/core/reference/config-options.md index 7dfee8828..57ea60d05 100644 --- a/content/influxdb3/core/reference/config-options.md +++ b/content/influxdb3/core/reference/config-options.md @@ -144,7 +144,7 @@ influxdb3 serve Specifies which object storage to use to store Parquet files. This option supports the following values: -- `memory` _(default)_ +- `memory` - `memory-throttled` - `file` - `s3` @@ -171,7 +171,7 @@ Required when using the `file` [object store](#object-store). #### node-id Specifies the node identifier used as a prefix in all object store file paths. -This should be unique for any hosts sharing the same object store +Use a unique node identifier for each host sharing the same object store configuration--for example, the same bucket. | influxdb3 serve option | Environment variable | diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md index 2b0e70db2..90f3f93c0 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md @@ -27,8 +27,8 @@ influxdb3 serve [OPTIONS] \ - **node-id**: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store. - **cluster-id**: A unique identifier for your cluster. Must be different from any node-id in your cluster. -- **object-store**: Determines where time series data is stored. _Default is `memory`_. -- **data-dir**: Path for local file storage (required when using `--object-store file`). +- **object-store**: Determines where time series data is stored. +- Other object store parameters depending on the selected `object-store` type. > [!NOTE] > `--node-id` and `--cluster-id` support alphanumeric strings with optional hyphens. diff --git a/content/influxdb3/enterprise/reference/config-options.md b/content/influxdb3/enterprise/reference/config-options.md index 77a0bab5d..e1d4ef469 100644 --- a/content/influxdb3/enterprise/reference/config-options.md +++ b/content/influxdb3/enterprise/reference/config-options.md @@ -263,7 +263,7 @@ export DATABASE_NODE=node0 && influxdb3 serve \ Specifies which object storage to use to store Parquet files. This option supports the following values: -- `memory` _(default)_: Effectively no object persistence +- `memory`: Effectively no object persistence - `memory-throttled`: Like `memory` but with latency and throughput that somewhat resembles a cloud object store - `file`: Stores objects in the local filesystem (must also set `--data-dir`) - `s3`: Amazon S3 (must also set `--bucket`, `--aws-access-key-id`, `--aws-secret-access-key`, and possibly `--aws-default-region`) diff --git a/content/shared/influxdb3-get-started/setup.md b/content/shared/influxdb3-get-started/setup.md index 4ef284643..e8a3aa83f 100644 --- a/content/shared/influxdb3-get-started/setup.md +++ b/content/shared/influxdb3-get-started/setup.md @@ -44,7 +44,7 @@ Provide the following: - `--object-store`: Specifies the type of object store to use. InfluxDB supports the following: - - `file` _(default)_: local file system + - `file`: local file system - `memory`: in memory _(no object persistence)_ - `memory-throttled`: like `memory` but with latency and throughput that somewhat resembles a cloud-based object store @@ -52,6 +52,9 @@ Provide the following: - `google`: Google Cloud Storage - `azure`: Azure Blob Storage +- Other object store parameters depending on the selected `object-store` type. + For example, if you use `s3`, you must provide the bucket name and credentials. + > [!Note] > #### Diskless architecture > From cf8fab980221c9fc52a44d99e313d0a252b54fe7 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 27 Jun 2025 14:50:19 -0500 Subject: [PATCH 4/4] fix(core): broken link --- content/influxdb3/core/reference/config-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb3/core/reference/config-options.md b/content/influxdb3/core/reference/config-options.md index 57ea60d05..7e3f92bfc 100644 --- a/content/influxdb3/core/reference/config-options.md +++ b/content/influxdb3/core/reference/config-options.md @@ -186,7 +186,7 @@ Limits the number of Parquet files a query can access. **Default:** `432` -With the default `432` setting and the default [`gen1-duration`](#`gen1-duration`) +With the default `432` setting and the default [`gen1-duration`](#gen1-duration) setting of 10 minutes, queries can access up to a 72 hours of data, but potentially less depending on whether all data for a given 10 minute block of time was ingested during the same period.