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/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/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. 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/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..7e3f92bfc 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 | @@ -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. 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 > 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 }}