From 189d86fcda8e0627fcc4640be163b82fb3a86e9b Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 8 Oct 2025 15:48:44 -0500 Subject: [PATCH 1/7] chore(instructions): restructure contributing instructions for humans and assistants --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/copilot-instructions.md | 36 +- .github/instructions/api-docs.instructions.md | 41 +- .github/instructions/assets.instructions.md | 79 +- .github/instructions/content.instructions.md | 292 +-- .../instructions/contributing.instructions.md | 172 +- .github/instructions/layouts.instructions.md | 38 + .../testing-setup.instructions.md | 15 - CLAUDE.md | 4 +- CONTRIBUTING.md | 1807 ----------------- DOCS-CONTRIBUTING.md | 442 ++++ DOCS-FRONTMATTER.md | 274 +++ ...ence.instructions.md => DOCS-SHORTCODES.md | 1024 +++++----- TESTING.md => DOCS-TESTING.md | 0 PLATFORM_REFERENCE.md | 73 +- README.md | 22 +- helper-scripts/build-agent-instructions.js | 226 ++- 17 files changed, 1802 insertions(+), 2745 deletions(-) create mode 100644 .github/instructions/layouts.instructions.md delete mode 100644 .github/instructions/testing-setup.instructions.md delete mode 100644 CONTRIBUTING.md create mode 100644 DOCS-CONTRIBUTING.md create mode 100644 DOCS-FRONTMATTER.md rename .github/instructions/shortcodes-reference.instructions.md => DOCS-SHORTCODES.md (59%) rename TESTING.md => DOCS-TESTING.md (100%) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4ba932d4b..d1f82e4ba 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -3,5 +3,5 @@ Closes # _Describe your proposed changes here._ - [ ] Signed the [InfluxData CLA](https://www.influxdata.com/legal/cla/) - ([if necessary](https://github.com/influxdata/docs-v2/blob/master/CONTRIBUTING.md#sign-the-influxdata-cla)) + ([if necessary](https://github.com/influxdata/docs-v2/blob/master/DOCS-CONTRIBUTING.md#sign-the-influxdata-cla)) - [ ] Rebased/mergeable diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e7b966fa5..53c095e9e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -28,7 +28,7 @@ Be a critical thinking partner, provide honest feedback, and identify potential ### Testing -For comprehensive testing procedures, see **[TESTING.md](../TESTING.md)**. +For comprehensive testing procedures, see **[DOCS-TESTING.md](../DOCS-TESTING.md)**. **Quick reference** (NEVER CANCEL long-running tests): - **Code blocks**: `yarn test:codeblocks:all` (15-45 minutes) @@ -56,11 +56,15 @@ yarn test:links content/example.md ### Content Organization - **InfluxDB 3**: `/content/influxdb3/` (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer) -- **InfluxDB v2**: `/content/influxdb/` (v2, cloud, enterprise_influxdb, v1) +- **InfluxDB v2**: `/content/influxdb/` (v2, cloud) +- **InfluxDB v1**: `/content/influxdb/v1` +- **InfluxDB Enterprise (v1)**: `/content/enterprise_influxdb/v1/` - **Telegraf**: `/content/telegraf/v1/` -- **Other tools**: `/content/kapacitor/`, `/content/chronograf/`, `/content/flux/` -- **Shared content**: `/content/shared/` +- **Kapacitor**: `/content/kapacitor/` +- **Chronograf**: `/content/chronograf/` +- **Flux**: `/content/flux/` - **Examples**: `/content/example.md` (comprehensive shortcode reference) +- **Shared content**: `/content/shared/` ### Key Files @@ -71,8 +75,8 @@ yarn test:links content/example.md ## Technology Stack -- **Hugo** (0.148.2+ extended) - Static site generator -- **Node.js/Yarn** (20.19.4+/1.22.22+) - Package management +- **Hugo** - Static site generator +- **Node.js/Yarn** - Package management - **Testing**: Pytest, Cypress, link-checker, Vale - **Tools**: Docker, ESLint, Prettier, Lefthook @@ -109,9 +113,12 @@ npx hugo --quiet ### Writing Documentation For detailed guidelines, see: -- **Frontmatter**: `.github/instructions/content.instructions.md` -- **Shortcodes**: `.github/instructions/shortcodes-reference.instructions.md` -- **Contributing**: `.github/instructions/contributing.instructions.md` +- **Workflow**: [DOCS-CONTRIBUTING.md](../DOCS-CONTRIBUTING.md) - Contribution guidelines and workflow +- **Shortcodes**: [DOCS-SHORTCODES.md](../DOCS-SHORTCODES.md) - Complete shortcode reference + - **Examples**: [content/example.md](../content/example.md) - Working examples for testing +- **Frontmatter**: [DOCS-FRONTMATTER.md](../DOCS-FRONTMATTER.md) - Complete page metadata reference +- **Testing**: [DOCS-TESTING.md](../DOCS-TESTING.md) - Testing procedures +- **API Docs**: [api-docs/README.md](../api-docs/README.md) - API documentation workflow ### Code Examples @@ -144,12 +151,11 @@ For detailed information on specific topics: | Topic | File | Description | |-------|------|-------------| -| **Content** | [content.instructions.md](instructions/content.instructions.md) | Frontmatter, metadata, page structure | -| **Shortcodes** | [shortcodes-reference.instructions.md](instructions/shortcodes-reference.instructions.md) | All available Hugo shortcodes | -| **Contributing** | [contributing.instructions.md](instructions/contributing.instructions.md) | Style guide, workflow, CLA | -| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec management | -| **Testing** | [TESTING.md](../TESTING.md) | Comprehensive testing procedures | -| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | JavaScript and CSS development | +| **Content** | [content.instructions.md](instructions/content.instructions.md) | Lightweight pointer to frontmatter and shortcode references | +| **Layouts** | [layouts.instructions.md](instructions/layouts.instructions.md) | Shortcode implementation patterns and testing | +| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec workflow | +| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | TypeScript/JavaScript and CSS development | +| **Testing** | [DOCS-TESTING.md](../DOCS-TESTING.md) | Comprehensive testing procedures | ## Important Notes diff --git a/.github/instructions/api-docs.instructions.md b/.github/instructions/api-docs.instructions.md index 96fdfa1b9..ba10069a1 100644 --- a/.github/instructions/api-docs.instructions.md +++ b/.github/instructions/api-docs.instructions.md @@ -1,28 +1,33 @@ --- -applyTo: "api-docs/**/*.md, layouts/**/*.html" +applyTo: "api-docs/**/*.md, api-docs/**/*.yml, api-docs/**/*.yaml" --- -# InfluxDB API documentation +# InfluxDB API Documentation -To edit the API reference documentation, edit the YAML files in `/api-docs`. +**Complete guide**: [api-docs/README.md](../../api-docs/README.md) -InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full -InfluxDB API documentation when documentation is deployed. -Redoc generates HTML documentation using the InfluxDB `swagger.yml`. -For more information about generating InfluxDB API documentation, see the -[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). +API documentation uses OpenAPI specifications and Redoc, not Hugo shortcodes. -## Generate API documentation locally +## Workflow -From `api-docs` directory: - -1. Install dependencies. To generate the API documentation locally, you need to have [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/getting-started/install) installed. +1. Edit YAML files in `/api-docs/` +2. Generate HTML documentation locally: ```sh - yarn install - ``` + cd api-docs + sh generate-api-docs.sh + ``` +3. Test generated documentation +4. Commit YAML changes (HTML is gitignored) -2. Run the script to generate the API documentation. +## Files - ```sh - generate-api-docs.sh - ``` \ No newline at end of file +- `ref.yml`: Main API specification +- `content/*.yml`: Custom content overlays +- `.redocly.yaml`: Linter and bundler configuration + +## Tools + +- Redoc: Generates HTML from OpenAPI specs +- @redocly/cli: Lints and bundles specs + +For complete documentation workflow, see [api-docs/README.md](../../api-docs/README.md). diff --git a/.github/instructions/assets.instructions.md b/.github/instructions/assets.instructions.md index 6eb06fe8f..741a5b4ea 100644 --- a/.github/instructions/assets.instructions.md +++ b/.github/instructions/assets.instructions.md @@ -1,55 +1,66 @@ --- -applyTo: "assets/**/*.md, layouts/**/*.html" +applyTo: "assets/js/**/*.js, assets/js/**/*.ts" --- -## JavaScript in the documentation UI +# JavaScript and TypeScript Guidelines -The InfluxData documentation UI uses JavaScript with ES6+ syntax and -`assets/js/main.js` as the entry point to import modules from. +## TypeScript Configuration +Project uses TypeScript with ES2020 target: +- Config: `tsconfig.json` +- Source: `assets/js/**/*.ts` +- Output: `dist/` +- Build: `yarn build:ts` +- Watch: `yarn build:ts:watch` -1. In your HTML file, add a `data-component` attribute to the element that will - encapsulate the UI feature and use the JavaScript module. +## Component Pattern +1. Add `data-component` attribute to HTML element: ```html
``` -2. In `assets/js/main.js`, import your module and initialize it on the element. - -## Debugging helpers for JavaScript - -In your JavaScript module, import the debug helpers from `assets/js/utils/debug-helpers.js`. - -```js - import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; - - const data = debugInspect(someData, 'Data'); - debugLog('Processing data', 'myFunction'); - - function processData() { - // Add a breakpoint that works with DevTools - debugBreak(); - - // Your existing code... +2. Create component module in `assets/js/components/`: + ```typescript + // assets/js/components/my-component.ts + export function initMyComponent(element: HTMLElement): void { + // Component logic } ``` -## Debugging with VS Code +3. Register in `assets/js/main.js`: + ```typescript + import { initMyComponent } from './components/my-component'; -1. Start Hugo in development mode--for example: - - ```bash - yarn hugo server + registerComponent('my-component', initMyComponent); ``` -2. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. +## Debugging -Your system uses the configuration in `launch.json` to launch the site in Chrome -and attach the debugger to the Developer Tools console. +### Method 1: Chrome DevTools with Source Maps +1. VS Code: Run > Start Debugging +2. Select "Debug Docs (source maps)" +3. Set breakpoints in `assets/js/ns-hugo-imp:` namespace -Make sure to remove the debug statements before merging your changes. -The debug helpers are designed to be used in development and should not be used in production. +### Method 2: Debug Helpers +```typescript +import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers'; -_See full CONTRIBUTING.md for complete details._ +const data = debugInspect(someData, 'Data'); +debugLog('Processing data', 'myFunction'); +debugBreak(); // Breakpoint +``` +Start with: `yarn hugo server` +Debug with: VS Code "Debug JS (debug-helpers)" configuration + +**Remove debug statements before committing.** + +## Type Safety + +- Use strict TypeScript mode +- Add type annotations for parameters and returns +- Use interfaces for complex objects +- Enable `checkJs: false` for gradual migration + +For complete JavaScript documentation, see [DOCS-CONTRIBUTING.md](../../DOCS-CONTRIBUTING.md#javascript-in-the-documentation-ui). diff --git a/.github/instructions/content.instructions.md b/.github/instructions/content.instructions.md index 458daf82b..b70f9aa77 100644 --- a/.github/instructions/content.instructions.md +++ b/.github/instructions/content.instructions.md @@ -1,243 +1,73 @@ --- -applyTo: "content/**/*.md, layouts/**/*.html" +applyTo: "content/**/*.md" --- -## Frontmatter Requirements +# Content File Guidelines -Documentation pages include frontmatter which specifies information about the page. -Include proper frontmatter for pages in `/content/`, except `/content/shared/`. -Frontmatter populates variables in page templates and the site's navigation menu. +**Frontmatter reference**: [DOCS-FRONTMATTER.md](../../DOCS-FRONTMATTER.md) +**Shortcodes reference**: [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md) +**Working examples**: [content/example.md](../../content/example.md) +## Required for All Content Files + +Every content file needs: ```yaml -title: # Page title (h1) -seotitle: # SEO title -description: # SEO description +title: # Page h1 heading +description: # SEO meta description menu: product_version: -weight: # Page order (1-99, 101-199, etc.) + name: # Navigation link text + parent: # Parent menu item (if nested) +weight: # Sort order (1-99, 101-199, 201-299...) ``` -### Complete Frontmatter Reference +## Style Guidelines -```yaml -title: # Title of the page used in the page's h1 -seotitle: # Page title used in the html title and used in search engine results -list_title: # Title used in article lists generated using the {{< children >}} shortcode -description: # Page description displayed in search engine results -menu: - influxdb_2_0: - name: # Article name that only appears in the left nav - parent: # Specifies a parent group and nests navigation items -weight: # Determines sort order in both the nav tree and in article lists -draft: # If true, will not render page on build -product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version ) -related: # Creates links to specific internal and external content at the bottom of the page - - /path/to/related/article - - https://external-link.com, This is an external link -external_url: # Used in children shortcode type="list" for page links that are external -list_image: # Image included with article descriptions in children type="articles" shortcode -list_note: # Used in children shortcode type="list" to add a small note next to listed links -list_code_example: # Code example included with article descriptions in children type="articles" shortcode -list_query_example:# Code examples included with article descriptions in children type="articles" shortcode, - # References to examples in data/query_examples -canonical: # Path to canonical page, overrides auto-gen'd canonical URL -v2: # Path to v2 equivalent page -alt_links: # Alternate pages in other products/versions for cross-product navigation - cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/ - core: /influxdb3/core/path/to/page/ -prepend: # Prepend markdown content to an article (especially powerful with cascade) - block: # (Optional) Wrap content in a block style (note, warn, cloud) - content: # Content to prepend to article -append: # Append markdown content to an article (especially powerful with cascade) - block: # (Optional) Wrap content in a block style (note, warn, cloud) - content: # Content to append to article -metadata: [] # List of metadata messages to include under the page h1 -updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata) -source: # Specify a file to pull page content from (typically in /content/shared/) -``` - -#### Title usage - -##### `title` - -The `title` frontmatter populates each page's HTML `h1` heading tag. -It shouldn't be overly long, but should set the context for users coming from outside sources. - -##### `seotitle` - -The `seotitle` frontmatter populates each page's HTML `title` attribute. -Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized. - -##### `list_title` - -The `list_title` frontmatter determines an article title when in a list generated -by the [`{{< children >}}` shortcode](#generate-a-list-of-children-articles). - -##### `menu > name` - -The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation. -It should be short and assume the context of its parent if it has one. - -#### Page Weights - -To ensure pages are sorted both by weight and their depth in the directory -structure, pages should be weighted in "levels." -All top level pages are weighted 1-99. -The next level is 101-199. -Then 201-299 and so on. - -_**Note:** `_index.md` files should be weighted one level up from the other `.md` files in the same directory._ - -#### Related content - -Use the `related` frontmatter to include links to specific articles at the bottom of an article. - -- If the page exists inside of this documentation, just include the path to the page. - It will automatically detect the title of the page. -- If the page exists inside of this documentation, but you want to customize the link text, - include the path to the page followed by a comma, and then the custom link text. - The path and custom text must be in that order and separated by a comma and a space. -- If the page exists outside of this documentation, include the full URL and a title for the link. - The link and title must be in that order and separated by a comma and a space. - -```yaml -related: - - /v2.0/write-data/quick-start - - /v2.0/write-data/quick-start, This is custom text for an internal link - - https://influxdata.com, This is an external link -``` - -#### Canonical URLs - -Search engines use canonical URLs to accurately rank pages with similar or identical content. -The `canonical` HTML meta tag identifies which page should be used as the source of truth. - -By default, canonical URLs are automatically generated for each page in the InfluxData -documentation using the latest version of the current product and the current path. - -Use the `canonical` frontmatter to override the auto-generated canonical URL. - -_**Note:** The `canonical` frontmatter supports the [`{{< latest >}}` shortcode](#latest-links)._ - -```yaml -canonical: /path/to/canonical/doc/ - -# OR - -canonical: /{{< latest "influxdb" "v2" >}}/path/to/canonical/doc/ -``` - -#### v2 equivalent documentation - -To display a notice on a 1.x page that links to an equivalent 2.0 page, -add the following frontmatter to the 1.x page: - -```yaml -v2: /influxdb/v2.0/get-started/ -``` - -#### Alternative links for cross-product navigation - -Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products, -for example, when a page exists at a different path in a different version or if -the feature doesn't exist in that product. -This enables the product switcher to navigate users to the corresponding page when they -switch between products. If a page doesn't exist in another product (for example, an -Enterprise-only feature), point to the nearest parent page if relevant. - -```yaml -alt_links: - cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ - cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ - core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist -``` - -Supported product keys for InfluxDB 3: -- `core` -- `enterprise` -- `cloud-serverless` -- `cloud-dedicated` -- `clustered` - -#### Prepend and append content to a page - -Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page. -Each has the following fields: - -```yaml -append: | - > [!Note] - > #### This is example markdown content - > This is just an example note block that gets appended to the article. -``` - -Use this frontmatter with [cascade](#cascade) to add the same content to -all children pages as well. - -```yaml -cascade: - append: | - > [!Note] - > #### This is example markdown content - > This is just an example note block that gets appended to the article. -``` - -#### Cascade - -To automatically apply frontmatter to a page and all of its children, use the -[`cascade` frontmatter](https://gohugo.io/content-management/front-matter/#front-matter-cascade) -built in into Hugo. - -```yaml -title: Example page -description: Example description -cascade: - layout: custom-layout -``` - -`cascade` applies the frontmatter to all children unless the child already includes -those frontmatter keys. Frontmatter defined on the page overrides frontmatter -"cascaded" from a parent. - -#### Use shared content in a page - -This repository makes heavy use of shared content to avoid duplication across InfluxDB editions and versions. -Use the `source` frontmatter to specify a shared file to use to populate the -page content. Shared files are typically stored in the `/content/shared` directory. - -When building shared content, use the `show-in` and `hide-in` shortcodes to show -or hide blocks of content based on the current InfluxDB product/version. -For more information, see [show-in](#show-in) and [hide-in](#hide-in). - -#### Links in shared content - -When creating links in shared content files, use `/influxdb3/version/` instead of the `{{% product-key %}}` shortcode. -The keyword `version` gets replaced during the build process with the appropriate product version. - -**Use this in shared content:** -```markdown -[Configuration options](/influxdb3/version/reference/config-options/) -[CLI serve command](/influxdb3/version/reference/cli/influxdb3/serve/) -``` - -**Not this:** -```markdown -[Configuration options](/influxdb3/{{% product-key %}}/reference/config-options/) -[CLI serve command](/influxdb3/{{% product-key %}}/reference/cli/influxdb3/serve/) -``` - -Don't list links to related content at the bottom of shared content files. -Instead, add the `related` frontmatter to the individual pages that use the shared content. - -#### Shortcodes in Markdown files - -For the complete shortcodes reference, see `/.github/instructions/shortcodes-reference.instructions.md`. - -### Style Guidelines - -- Follow Google Developer Documentation style guidelines - Use semantic line feeds (one sentence per line) -- Format code examples to fit within 80 characters -- Use long options in command line examples (`--option` instead of `-o`) -- Use GitHub callout syntax for notes and warnings -- Image naming: `project/version-context-description.png` +- Test all code examples before committing +- Use appropriate shortcodes for UI elements + +## Most Common Shortcodes + +**Callouts**: +```markdown +> [!Note] +> [!Warning] +> [!Caution] +> [!Important] +> [!Tip] +``` + +**Required elements**: +```markdown +{{< req >}} +{{< req type="key" >}} +``` + +**Code placeholders**: +```markdown +```sh { placeholders="DATABASE_NAME|API_TOKEN" } +curl -X POST https://cloud2.influxdata.com/api/v2/write?bucket=DATABASE_NAME +``` + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your database name +``` + +**Tabbed content**: +```markdown +{{< tabs-wrapper >}} +{{% tabs %}} +[Tab 1](#) +[Tab 2](#) +{{% /tabs %}} +{{% tab-content %}} +Content for tab 1 +{{% /tab-content %}} +{{% tab-content %}} +Content for tab 2 +{{% /tab-content %}} +{{< /tabs-wrapper >}} +``` + +For complete shortcodes reference, see [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md). diff --git a/.github/instructions/contributing.instructions.md b/.github/instructions/contributing.instructions.md index 6c17d9fdc..6f2ec437d 100644 --- a/.github/instructions/contributing.instructions.md +++ b/.github/instructions/contributing.instructions.md @@ -12,7 +12,7 @@ code examples, frontmatter, shortcodes, and formatting. ## Quick Start -Ready to contribute? Here's the essential workflow: +Ready to contribute? 1. [Sign the InfluxData CLA](#sign-the-influxdata-cla) (for substantial changes) 2. [Fork and clone](#fork-and-clone-influxdata-documentation-repository) this repository @@ -55,6 +55,7 @@ For the linting and tests to run, you need to install: - **Docker**: For running Vale linter and code block tests - **VS Code extensions** (optional): For enhanced editing experience + ```sh git commit -m "" --no-verify ``` @@ -71,7 +72,7 @@ docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . - YAML Schemas: validates frontmatter attributes. -_See full CONTRIBUTING.md for complete details._ +_See full DOCS-CONTRIBUTING.md for complete details._ #### Markdown @@ -81,6 +82,7 @@ _Some parts of the documentation, such as `./api-docs`, contain Markdown within #### Semantic line feeds + ```diff -Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. +Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. @@ -89,36 +91,94 @@ _Some parts of the documentation, such as `./api-docs`, contain Markdown within ### Essential Frontmatter Reference + ```yaml title: # Title of the page used in the page's h1 description: # Page description displayed in search engine results # ... (see full CONTRIBUTING.md for complete example) ``` -See content.instructions.md for more details. + +### Shared Content + + +```yaml +source: /shared/path/to/content.md +``` + + +_See full DOCS-CONTRIBUTING.md for complete details._ + +#### Callouts (notes and warnings) + +```md +> [!Note] +> Insert note markdown content here. + +> [!Warning] +> Insert warning markdown content here. + +> [!Caution] +> Insert caution markdown content here. + +> [!Important] +> Insert important markdown content here. + +> [!Tip] +> Insert tip markdown content here. +``` + +#### Tabbed content + +```md +{{< tabs-wrapper >}} + +{{% tabs %}} +[Button text for tab 1](#) +[Button text for tab 2](#) +{{% /tabs %}} + +{{% tab-content %}} +Markdown content for tab 1. +{{% /tab-content %}} + +{{% tab-content %}} +Markdown content for tab 2. +{{% /tab-content %}} + +{{< /tabs-wrapper >}} +``` + +#### Required elements + +```md +{{< req >}} +{{< req type="key" >}} + +- {{< req "\*" >}} **This element is required** +- {{< req "\*" >}} **This element is also required** +- **This element is NOT required** +``` + +For the complete shortcodes reference with all available shortcodes and usage examples, see **[SHORTCODES.md](SHORTCODES.md)**. + +Test shortcodes with working examples in **[content/example.md](content/example.md)**. + +--- ### InfluxDB API documentation -docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. -To edit the API documentation, edit the YAML files in `/api-docs`. +docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. The files are written in YAML and use [OpenAPI 3.0](https://swagger.io/specification/) standard. -See api-docs.instructions.md for more details. +InfluxData uses [Redoc](https://github.com/Redocly/redoc) to build and generate the full +InfluxDB API documentation when documentation is deployed. +For more information about editing and generating InfluxDB API documentation, see the +[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). --- ## Testing & Quality Assurance -For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. - -### Testing Code Blocks - -```bash -# Test code blocks -yarn test:codeblocks:all - -# Test links -yarn test:links content/influxdb3/core/**/*.md -``` Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: @@ -126,8 +186,29 @@ Pre-commit hooks run automatically when you commit changes, testing your staged git commit -m "" --no-verify ``` +### Quick Testing Reference + +```bash +# Test code blocks +yarn test:codeblocks:all + +# Test links +yarn test:links content/influxdb3/core/**/*.md + +# Run style linting +docker compose run -T vale content/**/*.md +``` + +For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. + + --- +## Submission Process + + +_See full DOCS-CONTRIBUTING.md for complete details._ + ### Commit Guidelines When creating commits, follow these guidelines: @@ -147,17 +228,18 @@ feat(telegraf): add new plugin documentation chore(ci): update Vale configuration ``` -## Reference Sections +### Submit a pull request -_See full CONTRIBUTING.md for complete details._ +Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). -### Complete Frontmatter Reference +--- -_For the complete Complete Frontmatter Reference reference, see content.instructions.md._ +## Reference Documentation -### Complete Shortcodes Reference +For detailed reference documentation, see: -_For the complete Complete Shortcodes Reference reference, see content.instructions.md._ +- **[FRONTMATTER.md](FRONTMATTER.md)** - Complete frontmatter field reference with all available options +- **[SHORTCODES.md](SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes #### Vale style linting configuration @@ -169,10 +251,52 @@ docs-v2 includes Vale writing style linter configurations to enforce documentati docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md ``` + - **Error**: - **Warning**: General style guide rules and best practices - **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list #### Configure style rules -_See full CONTRIBUTING.md for complete details._ + +_See full DOCS-CONTRIBUTING.md for complete details._ + +#### JavaScript in the documentation UI + +The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and +`assets/js/main.js` as the entry point to import modules from + + +1. In your HTML file, add a `data-component` attribute to the element that + +# ... (see full CONTRIBUTING.md for complete example) +```js + import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; + + const data = debugInspect(someData, 'Data'); + debugLog('Processing data', 'myFunction'); + + function processData() { + // Add a breakpoint that works with DevTools + debugBreak(); + + // Your existing code... + } + ``` + +3. Start Hugo in development mode--for example: + + ```bash + yarn hugo server + ``` + +4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. + +Your system uses the configuration in `launch.json` to launch the site in Chrome +and attach the debugger to the Developer Tools console. + +Make sure to remove the debug statements before merging your changes. +The debug helpers are designed to be used in development and should not be used in production. + +_See full DOCS-CONTRIBUTING.md for complete details._ + diff --git a/.github/instructions/layouts.instructions.md b/.github/instructions/layouts.instructions.md new file mode 100644 index 000000000..dc5d85e93 --- /dev/null +++ b/.github/instructions/layouts.instructions.md @@ -0,0 +1,38 @@ +--- +applyTo: "layouts/**/*.html" +--- + +# Layout and Shortcode Implementation Guidelines + +**Shortcodes reference**: [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md) +**Test examples**: [content/example.md](../../content/example.md) + +## Implementing Shortcodes + +When creating or modifying Hugo layouts and shortcodes: + +1. Use Hugo template syntax and functions +2. Follow existing patterns in `/layouts/shortcodes/` +3. Test in [content/example.md](../../content/example.md) +4. Document new shortcodes in [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md) + +## Shortcode Pattern + +```html + +{{ $param := .Get 0 }} +{{ $namedParam := .Get "name" }} + +
+ {{ .Inner | markdownify }} +
+``` + +## Testing + +Add usage examples to `content/example.md` to verify: +- Rendering in browser +- Hugo build succeeds +- No console errors + +See [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md) for complete shortcode documentation. diff --git a/.github/instructions/testing-setup.instructions.md b/.github/instructions/testing-setup.instructions.md deleted file mode 100644 index 7c0b9509b..000000000 --- a/.github/instructions/testing-setup.instructions.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -applyTo: "content/**/*.md, layouts/**/*.html" ---- - -### Detailed Testing Setup - -For comprehensive testing information, including: -- Code block testing setup and configuration -- Link validation testing procedures -- Style linting with Vale -- Pre-commit hooks and GitHub Actions integration -- Advanced testing procedures and troubleshooting - -Please refer to the main **[TESTING.md](../../TESTING.md)** file. - diff --git a/CLAUDE.md b/CLAUDE.md index 0fc7b5866..9a1202a6d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,11 +17,11 @@ See @README.md 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 essential InfluxData +See @DOCS-CONTRIBUTING.md for essential InfluxData documentation contributing guidelines, such as style and formatting, and commonly used shortcodes. -See @TESTING.md for comprehensive testing information, including code block +See @DOCS-TESTING.md for comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures. See @api-docs/README.md for information about the API reference documentation, how to diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 096ded745..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,1807 +0,0 @@ -# Contributing to InfluxData Documentation - - -## Quick Start - -Ready to contribute? Here's the essential workflow: - -1. [Sign the InfluxData CLA](#sign-the-influxdata-cla) (for substantial changes) -2. [Fork and clone](#fork-and-clone-influxdata-documentation-repository) this repository -3. [Install dependencies](#development-environment-setup) (Node.js, Yarn, Docker) -4. Make your changes following [style guidelines](#making-changes) -5. [Test your changes](TESTING.md) (pre-commit and pre-push hooks run automatically) -6. [Submit a pull request](#submission-process) - -For detailed setup and reference information, see the sections below. - ---- - -## Legal & Getting Started - -### Sign the InfluxData CLA - -The InfluxData Contributor License Agreement (CLA) is part of the legal framework -for the open source ecosystem that protects both you and InfluxData. -To make substantial contributions to InfluxData documentation, first sign the InfluxData CLA. -What constitutes a "substantial" change is at the discretion of InfluxData documentation maintainers. - -[Sign the InfluxData CLA](https://www.influxdata.com/legal/cla/) - -_**Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA._ - -_If you're new to contributing or you're looking for an easy update, see [`docs-v2` good-first-issues](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)._ - -### Fork and clone InfluxData Documentation Repository - -[Fork this repository](https://help.github.com/articles/fork-a-repo/) and -[clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine. - ---- - - -## Development Environment Setup - -### Prerequisites - -docs-v2 automatically runs format (Markdown, JS, and CSS) linting and code block tests for staged files that you try to commit. - -For the linting and tests to run, you need to install: - -- **Node.js and Yarn**: For managing dependencies and running build scripts -- **Docker**: For running Vale linter and code block tests -- **VS Code extensions** (optional): For enhanced editing experience - -\_**Note:** -The git pre-commit and pre-push hooks are configured to run linting and tests automatically -when you commit or push changes. -We strongly recommend letting them run, but you can skip them -(and avoid installing related dependencies) -by including the `--no-verify` flag with your commit--for example: - -```sh -git commit -m "" --no-verify -``` - -### Install Node.js dependencies - -To install dependencies listed in package.json: - -1. Install [Node.js](https://nodejs.org/en) for your system. -2. Install [Yarn](https://yarnpkg.com/getting-started/install) for your system. -3. Run `yarn` to install dependencies (including Hugo). - -`package.json` contains dependencies used in `/assets/js` JavaScript code and -dev dependencies used in pre-commit hooks for linting, syntax-checking, and testing. - -Dev dependencies include: - -- [Lefthook](https://github.com/evilmartians/lefthook): configures and -manages git pre-commit and pre-push hooks for linting and testing Markdown content. -- [prettier](https://prettier.io/docs/en/): formats code, including Markdown, according to style rules for consistency -- [Cypress]: e2e testing for UI elements and URLs in content - -### Install Docker - -docs-v2 includes Docker configurations (`compose.yaml` and Dockerfiles) for running the Vale style linter and tests for code blocks (Shell, Bash, and Python) in Markdown files. - -Install [Docker](https://docs.docker.com/get-docker/) for your system. - -#### Build the test dependency image - -After you have installed Docker, run the following command to build the test -dependency image, `influxdata:docs-pytest`. -The tests defined in `compose.yaml` use the dependencies and execution -environment from this image. - -```bash -docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . -``` - -### Run the documentation locally (optional) - -To run the documentation locally, follow the instructions provided in the README. - -### Install Visual Studio Code extensions - -If you use Microsoft Visual Studio (VS) Code, you can install extensions -to help you navigate, check, and edit files. - -docs-v2 contains a `./.vscode/settings.json` that configures the following extensions: - -- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments. -- Vale: shows linter errors and suggestions in the editor. -- YAML Schemas: validates frontmatter attributes. - ---- - - -## Making Changes - - -### Style Guidelines - -#### Markdown - -Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). - -_Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling._ - -#### Semantic line feeds - -Use [semantic line feeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). -Separating each sentence with a new line makes it easy to parse diffs with the human eye. - -**Diff without semantic line feeds:** - -```diff --Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. -+Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. -``` - -**Diff with semantic line feeds:** - -```diff -Data is taking off. -This data is time series. -You need a database that specializes in time series. --You should check out InfluxDB. -+You need InfluxDB. -``` - -#### Article headings - -Use only h2-h6 headings in markdown content. -h1 headings act as the page title and are populated automatically from the `title` frontmatter. -h2-h6 headings act as section headings. - -#### Image naming conventions - -Save images using the following naming format: `project/version-context-description.png`. -For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png`. -Specify a version other than 2.0 only if the image is specific to that version. - -### Essential Frontmatter Reference - -Every documentation page includes frontmatter which specifies information about the page. -Frontmatter populates variables in page templates and the site's navigation menu. - -**Essential fields:** - -```yaml -title: # Title of the page used in the page's h1 -description: # Page description displayed in search engine results -menu: - influxdb_2_0: - name: # Article name that only appears in the left nav - parent: # Specifies a parent group and nests navigation items -weight: # Determines sort order in both the nav tree and in article lists -``` - -For the complete frontmatter reference with all available fields, see [Complete Frontmatter Reference](#complete-frontmatter-reference). - - -### Common Shortcodes Reference - -#### Notes and warnings - -```md -> [!Note] -> Insert note markdown content here. - -> [!Warning] -> Insert warning markdown content here. - -> [!Caution] -> Insert caution markdown content here. - -> [!Important] -> Insert important markdown content here. - -> [!Tip] -> Insert tip markdown content here. -``` - -#### Tabbed content - -```md -{{< tabs-wrapper >}} - -{{% tabs %}} -[Button text for tab 1](#) -[Button text for tab 2](#) -{{% /tabs %}} - -{{% tab-content %}} -Markdown content for tab 1. -{{% /tab-content %}} - -{{% tab-content %}} -Markdown content for tab 2. -{{% /tab-content %}} - -{{< /tabs-wrapper >}} -``` - -#### Required elements - -```md -{{< req >}} -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` - -For the complete shortcodes reference with all available shortcodes, see [Complete Shortcodes Reference](#complete-shortcodes-reference). - ---- - -### InfluxDB API documentation - -docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. -To edit the API documentation, edit the YAML files in `/api-docs`. - -InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full -InfluxDB API documentation when documentation is deployed. -Redoc generates HTML documentation using the InfluxDB `swagger.yml`. -For more information about generating InfluxDB API documentation, see the -[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). - ---- - -## Testing & Quality Assurance - -For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. - -### Quick Testing Reference - -```bash -# Test code blocks -yarn test:codeblocks:all - -# Test links -yarn test:links content/influxdb3/core/**/*.md - -# Run style linting -docker compose run -T vale content/**/*.md -``` - -Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: - -```sh -git commit -m "" --no-verify -``` - ---- - - -## Submission Process - -### Commit Guidelines - -When creating commits, follow these guidelines: - -- Use a clear, descriptive commit message that explains the change -- Start with a type prefix: `fix()`, `feat()`, `style()`, `refactor()`, `test()`, `chore()` -- For product-specific changes, include the product in parentheses: `fix(enterprise)`, `fix(influxdb3)`, `fix(core)` -- Keep the first line under 72 characters -- Reference issues with "closes" or "fixes": `closes #123` or `closes influxdata/DAR#123` -- For multiple issues, use comma separation: `closes influxdata/DAR#517, closes influxdata/DAR#518` - -**Examples:** -``` -fix(enterprise): correct Docker environment variable name for license email -fix(influxdb3): correct Docker environment variable and compose examples for monolith -feat(telegraf): add new plugin documentation -chore(ci): update Vale configuration -``` - -### Submit a pull request - -Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). - ---- - -## Reference Sections - - -### Complete Frontmatter Reference - -Every documentation page includes frontmatter which specifies information about the page. -Frontmatter populates variables in page templates and the site's navigation menu. - -```yaml -title: # Title of the page used in the page's h1 -seotitle: # Page title used in the html title and used in search engine results -list_title: # Title used in article lists generated using the {{< children >}} shortcode -description: # Page description displayed in search engine results -menu: - influxdb_2_0: - name: # Article name that only appears in the left nav - parent: # Specifies a parent group and nests navigation items -weight: # Determines sort order in both the nav tree and in article lists -draft: # If true, will not render page on build -product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version ) -related: # Creates links to specific internal and external content at the bottom of the page - - /path/to/related/article - - https://external-link.com, This is an external link -external_url: # Used in children shortcode type="list" for page links that are external -list_image: # Image included with article descriptions in children type="articles" shortcode -list_note: # Used in children shortcode type="list" to add a small note next to listed links -list_code_example: # Code example included with article descriptions in children type="articles" shortcode -list_query_example:# Code examples included with article descriptions in children type="articles" shortcode, - # References to examples in data/query_examples -canonical: # Path to canonical page, overrides auto-gen'd canonical URL -v2: # Path to v2 equivalent page -alt_links: # Alternate pages in other products/versions for cross-product navigation - cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/ - core: /influxdb3/core/path/to/page/ -prepend: # Prepend markdown content to an article (especially powerful with cascade) - block: # (Optional) Wrap content in a block style (note, warn, cloud) - content: # Content to prepend to article -append: # Append markdown content to an article (especially powerful with cascade) - block: # (Optional) Wrap content in a block style (note, warn, cloud) - content: # Content to append to article -metadata: [] # List of metadata messages to include under the page h1 -updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata) -source: # Specify a file to pull page content from (typically in /content/shared/) -``` - -#### Title usage - -##### `title` - -The `title` frontmatter populates each page's HTML `h1` heading tag. -It shouldn't be overly long, but should set the context for users coming from outside sources. - -##### `seotitle` - -The `seotitle` frontmatter populates each page's HTML `title` attribute. -Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized. - -##### `list_title` - -The `list_title` frontmatter determines an article title when in a list generated -by the [`{{< children >}}` shortcode](#generate-a-list-of-children-articles). - -##### `menu > name` - -The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation. -It should be short and assume the context of its parent if it has one. - -#### Page Weights - -To ensure pages are sorted both by weight and their depth in the directory -structure, pages should be weighted in "levels." -All top level pages are weighted 1-99. -The next level is 101-199. -Then 201-299 and so on. - -_**Note:** `_index.md` files should be weighted one level up from the other `.md` files in the same directory._ - -#### Related content - -Use the `related` frontmatter to include links to specific articles at the bottom of an article. - -- If the page exists inside of this documentation, just include the path to the page. - It will automatically detect the title of the page. -- If the page exists inside of this documentation, but you want to customize the link text, - include the path to the page followed by a comma, and then the custom link text. - The path and custom text must be in that order and separated by a comma and a space. -- If the page exists outside of this documentation, include the full URL and a title for the link. - The link and title must be in that order and separated by a comma and a space. - -```yaml -related: - - /v2.0/write-data/quick-start - - /v2.0/write-data/quick-start, This is custom text for an internal link - - https://influxdata.com, This is an external link -``` - -#### Canonical URLs - -Search engines use canonical URLs to accurately rank pages with similar or identical content. -The `canonical` HTML meta tag identifies which page should be used as the source of truth. - -By default, canonical URLs are automatically generated for each page in the InfluxData -documentation using the latest version of the current product and the current path. - -Use the `canonical` frontmatter to override the auto-generated canonical URL. - -_**Note:** The `canonical` frontmatter supports the [`{{< latest >}}` shortcode](#latest-links)._ - -```yaml -canonical: /path/to/canonical/doc/ - -# OR - -canonical: /{{< latest "influxdb" "v2" >}}/path/to/canonical/doc/ -``` - -#### v2 equivalent documentation - -To display a notice on a 1.x page that links to an equivalent 2.0 page, -add the following frontmatter to the 1.x page: - -```yaml -v2: /influxdb/v2.0/get-started/ -``` - -#### Alternative links for cross-product navigation - -Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products, -for example, when a page exists at a different path in a different version or if -the feature doesn't exist in that product. -This enables the product switcher to navigate users to the corresponding page when they -switch between products. If a page doesn't exist in another product (for example, an -Enterprise-only feature), point to the nearest parent page if relevant. - -```yaml -alt_links: - cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ - cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ - core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist -``` - -Supported product keys for InfluxDB 3: -- `core` -- `enterprise` -- `cloud-serverless` -- `cloud-dedicated` -- `clustered` - -#### Prepend and append content to a page - -Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page. -Each has the following fields: - -```yaml -append: | - > [!Note] - > #### This is example markdown content - > This is just an example note block that gets appended to the article. -``` - -Use this frontmatter with [cascade](#cascade) to add the same content to -all children pages as well. - -```yaml -cascade: - append: | - > [!Note] - > #### This is example markdown content - > This is just an example note block that gets appended to the article. -``` - -#### Cascade - -To automatically apply frontmatter to a page and all of its children, use the -[`cascade` frontmatter](https://gohugo.io/content-management/front-matter/#front-matter-cascade) -built in into Hugo. - -```yaml -title: Example page -description: Example description -cascade: - layout: custom-layout -``` - -`cascade` applies the frontmatter to all children unless the child already includes -those frontmatter keys. Frontmatter defined on the page overrides frontmatter -"cascaded" from a parent. - -#### Use shared content in a page - -Use the `source` frontmatter to specify a shared file to use to populate the -page content. Shared files are typically stored in the `/content/shared` directory. - -When building shared content, use the `show-in` and `hide-in` shortcodes to show -or hide blocks of content based on the current InfluxDB product/version. -For more information, see [show-in](#show-in) and [hide-in](#hide-in). - - -### Complete Shortcodes Reference - -#### Notes and warnings - -Shortcodes are available for formatting notes and warnings in each article: - -```md -{{% note %}} -Insert note markdown content here. -{{% /note %}} - -{{% warn %}} -Insert warning markdown content here. -{{% /warn %}} -``` - -#### Product data - -Display the full product name and version name for the current page--for example: - -- InfluxDB 3 Core -- InfluxDB 3 Cloud Dedicated - -```md -{{% product-name %}} -``` - -Display the short version name (part of the key used in `products.yml`) from the current page URL--for example: - -- `/influxdb3/core` returns `core` - -```md -{{% product-key %}} -``` - -##### Enterprise name - -The name used to refer to InfluxData's enterprise offering is subject to change. -To facilitate easy updates in the future, use the `enterprise-name` shortcode -when referencing the enterprise product. -This shortcode accepts a `"short"` parameter which uses the "short-name". - -``` -This is content that references {{< enterprise-name >}}. -This is content that references {{< enterprise-name "short" >}}. -``` - -Product names are stored in `data/products.yml`. - -##### Enterprise link - -References to InfluxDB Enterprise are often accompanied with a link to a page where -visitors can get more information about the Enterprise offering. -This link is subject to change. -Use the `enterprise-link` shortcode when including links to more information about -InfluxDB Enterprise. - -``` -Find more info [here][{{< enterprise-link >}}] -``` - -#### Latest patch version - -Use the `{{< latest-patch >}}` shortcode to add the latest patch version of a product. -By default, this shortcode parses the product and minor version from the URL. -To specify a specific product and minor version, use the `product` and `version` arguments. -Easier to maintain being you update the version number in the `data/products.yml` file instead of updating individual links and code examples. - -```md -{{< latest-patch >}} - -{{< latest-patch product="telegraf" >}} - -{{< latest-patch product="chronograf" version="1.7" >}} -``` - -#### Latest influx CLI version - -Use the `{{< latest-patch cli=true >}}` shortcode to add the latest version of the `influx` -CLI supported by the minor version of InfluxDB. -By default, this shortcode parses the minor version from the URL. -To specify a specific minor version, use the `version` argument. -Maintain CLI version numbers in the `data/products.yml` file instead of updating individual links and code examples. - -```md -{{< latest-patch cli=true >}} - -{{< latest-cli version="2.1" >}} -``` - -#### API endpoint - -Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains -a colored request method, a specified API endpoint, and an optional link to -the API reference documentation. -Provide the following arguments: - -- **method**: HTTP request method (get, post, patch, put, or delete) -- **endpoint**: API endpoint -- **api-ref**: Link the endpoint to a specific place in the API documentation -- **influxdb_host**: Specify which InfluxDB product host to use - _if the `endpoint` contains the `influxdb/host` shortcode_. - Uses the current InfluxDB product as default. - Supports the following product values: - - - oss - - cloud - - serverless - - dedicated - - clustered - -```md -{{< api-endpoint method="get" endpoint="/api/v2/tasks" api-ref="/influxdb/cloud/api/#operation/GetTasks">}} -``` - -```md -{{< api-endpoint method="get" endpoint="{{< influxdb/host >}}/api/v2/tasks" influxdb_host="cloud">}} -``` - -#### Tabbed Content - -To create "tabbed" content (content that is changed by a users' selection), use the following three shortcodes in combination: - -`{{< tabs-wrapper >}}` -This shortcode creates a wrapper or container for the tabbed content. -All UI interactions are limited to the scope of each container. -If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`. -This shortcode must be closed with `{{< /tabs-wrapper >}}`. - -**Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML. - -`{{% tabs %}}` -This shortcode creates a container for buttons that control the display of tabbed content. -It should contain simple markdown links with anonymous anchors (`#`). -The link text is used as the button text. -This shortcode must be closed with `{{% /tabs %}}`. - -**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. - -The `{{% tabs %}}` shortcode has an optional `style` argument that lets you -assign CSS classes to the tags HTML container. The following classes are available: - -- **small**: Tab buttons are smaller and don't scale to fit the width. -- **even-wrap**: Prevents uneven tab widths when tabs are forced to wrap. - -`{{% tab-content %}}` -This shortcode creates a container for a content block. -Each content block in the tab group needs to be wrapped in this shortcode. -**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode** -This shortcode must be closed with `{{% /tab-content %}}`. - -**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. - -##### Example tabbed content group - -```md -{{< tabs-wrapper >}} - -{{% tabs %}} -[Button text for tab 1](#) -[Button text for tab 2](#) -{{% /tabs %}} - -{{% tab-content %}} -Markdown content for tab 1. -{{% /tab-content %}} - -{{% tab-content %}} -Markdown content for tab 2. -{{% /tab-content %}} - -{{< /tabs-wrapper >}} -``` - -##### Tabbed code blocks - -Shortcodes are also available for tabbed code blocks primarily used to give users -the option to choose between different languages and syntax. -The shortcode structure is the same as above, but the shortcode names are different: - -`{{< code-tabs-wrapper >}}` -`{{% code-tabs %}}` -`{{% code-tab-content %}}` - -````md -{{< code-tabs-wrapper >}} - -{{% code-tabs %}} -[Flux](#) -[InfluxQL](#) -{{% /code-tabs %}} - -{{% code-tab-content %}} - -```js -data = from(bucket: "example-bucket") - |> range(start: -15m) - |> filter(fn: (r) => - r._measurement == "mem" and - r._field == "used_percent" - ) -``` - -{{% /code-tab-content %}} - -{{% code-tab-content %}} - -```sql -SELECT "used_percent" -FROM "telegraf"."autogen"."mem" -WHERE time > now() - 15m -``` - -{{% /code-tab-content %}} - -{{< /code-tabs-wrapper >}} -```` - -##### Link to tabbed content - -To link to tabbed content, click on the tab and use the URL parameter shown. -It will have the form `?t=`, plus a string. -For example: - -``` -[Windows installation](/influxdb/v2.0/install/?t=Windows) -``` - -#### Required elements - -Use the `{{< req >}}` shortcode to identify required elements in documentation with -orange text and/or asterisks. By default, the shortcode outputs the text, "Required," but -you can customize the text by passing a string argument with the shortcode. - -```md -{{< req >}} -``` - -**Output:** Required - -```md -{{< req "This is Required" >}} -``` - -**Output:** This is required - -If using other named arguments like `key` or `color`, use the `text` argument to -customize the text of the required message. - -```md -{{< req text="Required if ..." color="blue" type="key" >}} -``` - -##### Required elements in a list - -When identifying required elements in a list, use `{{< req type="key" >}}` to generate -a "\* Required" key before the list. For required elements in the list, include -{{< req "\*" >}} before the text of the list item. For example: - -```md -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` - -##### Change color of required text - -Use the `color` argument to change the color of required text. -The following colors are available: - -- blue -- green -- magenta - -```md -{{< req color="magenta" text="This is required" >}} -``` - -#### Page navigation buttons - -Use the `{{< page-nav >}}` shortcode to add page navigation buttons to a page. -These are useful for guiding users through a set of docs that should be read in sequential order. -The shortcode has the following parameters: - -- **prev:** path of the previous document _(optional)_ -- **next:** path of the next document _(optional)_ -- **prevText:** override the button text linking to the previous document _(optional)_ -- **nextText:** override the button text linking to the next document _(optional)_ -- **keepTab:** include the currently selected tab in the button link _(optional)_ - -The shortcode generates buttons that link to both the previous and next documents. -By default, the shortcode uses either the `list_title` or the `title` of the linked -document, but you can use `prevText` and `nextText` to override button text. - -```md - - -{{ page-nav prev="/path/to/prev/" next="/path/to/next" >}} - - - -{{ page-nav prev="/path/to/prev/" prevText="Previous" next="/path/to/next" nextText="Next" >}} - - - -{{ page-nav prev="/path/to/prev/" next="/path/to/next" keepTab=true>}} -``` - -#### Keybinds - -Use the `{{< keybind >}}` shortcode to include OS-specific keybindings/hotkeys. -The following parameters are available: - -- mac -- linux -- win -- all -- other - -```md - - -{{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}} - - - -{{< keybind all="Ctrl+Shift+P" >}} - - - -{{< keybind mac="⇧⌘P" linux="Ctrl+Shift+P" win="Ctrl+Shift+Alt+P" >}} -``` - -#### Diagrams - -Use the `{{< diagram >}}` shortcode to dynamically build diagrams. -The shortcode uses [mermaid.js](https://github.com/mermaid-js/mermaid) to convert -simple text into SVG diagrams. -For information about the syntax, see the [mermaid.js documentation](https://mermaid-js.github.io/mermaid/#/). - -```md -{{< diagram >}} -flowchart TB -This --> That -That --> There -{{< /diagram >}} -``` - -#### File system diagrams - -Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system -diagram using a Markdown unordered list. - -##### Example filesystem diagram shortcode - -```md -{{< filesystem-diagram >}} - -- Dir1/ -- Dir2/ - - ChildDir/ - - Child - - Child -- Dir3/ - {{< /filesystem-diagram >}} -``` - -#### High-resolution images - -In many cases, screenshots included in the docs are taken from high-resolution (retina) screens. -Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be. -The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension. -This preserves the detail of the image and renders it at a size where there should be little to no "blur" -cause by browser image resizing. - -```html -{{< img-hd src="/path/to/image" alt="Alternate title" />}} -``` - -###### Notes - -- This should only be used on screenshots takes from high-resolution screens. -- The `src` should be relative to the `static` directory. -- Image widths are limited to the width of the article content container and will scale accordingly, - even with the `width` explicitly set. - -#### Truncated content blocks - -In some cases, it may be appropriate to shorten or truncate blocks of content. -Use cases include long examples of output data or tall images. -The following shortcode truncates blocks of content and allows users to opt into -to seeing the full content block. - -```md -{{% truncate %}} -Truncated markdown content here. -{{% /truncate %}} -``` - -#### Expandable accordion content blocks - -Use the `{{% expand "Item label" %}}` shortcode to create expandable, accordion-style content blocks. -Each expandable block needs a label that users can click to expand or collapse the content block. -Pass the label as a string to the shortcode. - -```md -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} - -{{% expand "Label 3" %}} -Markdown content associated with label 3. -{{% /expand %}} -``` - -Use the optional `{{< expand-wrapper >}}` shortcode around a group of `{{% expand %}}` -shortcodes to ensure proper spacing around the expandable elements: - -```md -{{< expand-wrapper >}} -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} -{{< /expand-wrapper >}} -``` - -#### Captions - -Use the `{{% caption %}}` shortcode to add captions to images and code blocks. -Captions are styled with a smaller font size, italic text, slight transparency, -and appear directly under the previous image or code block. - -```md -{{% caption %}} -Markdown content for the caption. -{{% /caption %}} -``` - -#### Generate a list of children articles - -Section landing pages often contain just a list of articles with links and descriptions for each. -This can be cumbersome to maintain as content is added. -To automate the listing of articles in a section, use the `{{< children >}}` shortcode. - -```md -{{< children >}} -``` - -The children shortcode can also be used to list only "section" articles (those with their own children), -or only "page" articles (those with no children) using the `show` argument: - -```md -{{< children show="sections" >}} - - - -{{< children show="pages" >}} -``` - -_By default, it displays both sections and pages._ - -Use the `type` argument to specify the format of the children list. - -```md -{{< children type="functions" >}} -``` - -The following list types are available: - -- **articles:** lists article titles as headers with the description or summary - of the article as a paragraph. Article headers link to the articles. -- **list:** lists children article links in an unordered list. -- **anchored-list:** lists anchored children article links in an unordered list - meant to act as a page navigation and link to children header. -- **functions:** a special use-case designed for listing Flux functions. - -##### Include a "Read more" link - -To include a "Read more" link with each child summary, set `readmore=true`. -_Only the `articles` list type supports "Read more" links._ - -```md -{{< children readmore=true >}} -``` - -##### Include a horizontal rule - -To include a horizontal rule after each child summary, set `hr=true`. -_Only the `articles` list type supports horizontal rules._ - -```md -{{< children hr=true >}} -``` - -##### Include a code example with a child summary - -Use the `list_code_example` frontmatter to provide a code example with an article -in an articles list. - -````yaml -list_code_example: | - ```sh - This is a code example - ``` -```` - -##### Organize and include native code examples - -To include text from a file in `/shared/text/`, use the -`{{< get-shared-text >}}` shortcode and provide the relative path and filename. - -This is useful for maintaining and referencing sample code variants in their -native file formats. - -1. Store code examples in their native formats at `/shared/text/`. - -```md -/shared/text/example1/example.js -/shared/text/example1/example.py -``` - -2. Include the files--for example, in code tabs: - - ````md - {{% code-tabs-wrapper %}} - {{% code-tabs %}} - [Javascript](#js) - [Python](#py) - {{% /code-tabs %}} - {{% code-tab-content %}} - - ```js - {{< get-shared-text "example1/example.js" >}} - ``` - - {{% /code-tab-content %}} - {{% code-tab-content %}} - - ```py - {{< get-shared-text "example1/example.py" >}} - ``` - - {{% /code-tab-content %}} - {{% /code-tabs-wrapper %}} - ```` - -##### Include specific files from the same directory -> [!Caution] -> #### Don't use for code examples -> Using this and `get-shared-text` shortcodes to include code examples prevents the code from being tested. - -To include the text from one file in another file in the same -directory, use the `{{< get-leaf-text >}}` shortcode. -The directory that contains both files must be a -Hugo [_Leaf Bundle_](https://gohugo.io/content-management/page-bundles/#leaf-bundles), -a directory that doesn't have any child directories. - -In the following example, `api` is a leaf bundle. `content` isn't. - -```md -content -| -|--- api -| query.pdmc -| query.sh -| \_index.md -``` - -###### query.pdmc - -```md -# Query examples -``` - -###### query.sh - -```md -curl https://localhost:8086/query -``` - -To include `query.sh` and `query.pdmc` in `api/_index.md`, use the following code: - -````md -{{< get-leaf-text "query.pdmc" >}} - -# Curl example - -```sh -{{< get-leaf-text "query.sh" >}} -``` -```` - -Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages: -`.ad`, `.adoc`, `.asciidoc`, `.htm`, `.html`, `.markdown`, `.md`, `.mdown`, `.mmark`, `.pandoc`, `.pdc`, `.org`, or `.rst`. - -##### Reference a query example in children - -To include a query example with the children in your list, update `data/query_examples.yml` -with the example code, input, and output, and use the `list_query_example` -frontmatter to reference the corresponding example. - -```yaml -list_query_example: cumulative_sum -``` - -##### Children frontmatter - -Each children list `type` uses [frontmatter properties](#page-frontmatter) when generating the list of articles. -The following table shows which children types use which frontmatter properties: - -| Frontmatter | articles | list | functions | -| :------------------- | :------: | :--: | :-------: | -| `list_title` | ✓ | ✓ | ✓ | -| `description` | ✓ | | | -| `external_url` | ✓ | ✓ | | -| `list_image` | ✓ | | | -| `list_note` | | ✓ | | -| `list_code_example` | ✓ | | | -| `list_query_example` | ✓ | | | - -#### Authentication token link - -Use the `{{% token-link "" "%}}` shortcode to -automatically generate links to token management documentation. The shortcode -accepts two _optional_ arguments: - -- **descriptor**: An optional token descriptor -- **link_append**: An optional path to append to the token management link path, - `///admin/tokens/`. - -```md -{{% token-link "database" "resource/" %}} - - -[database token](/influxdb3/enterprise/admin/tokens/resource/) -``` - -InfluxDB 3 Enterprise and InfluxDB 3 Core support different kinds of tokens. -The shortcode has a blacklist of token descriptors for each that will prevent -unsupported descriptors from appearing in the rendered output based on the -current product. - -#### Inline icons - -The `icon` shortcode allows you to inject icons in paragraph text. -It's meant to clarify references to specific elements in the InfluxDB user interface. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. - -``` -{{< icon "icon-name" "v2" >}} -``` - -Below is a list of available icons (some are aliases): - -- add-cell -- add-label -- alert -- calendar -- chat -- checkmark -- clone -- cloud -- cog -- config -- copy -- dashboard -- dashboards -- data-explorer -- delete -- download -- duplicate -- edit -- expand -- export -- eye -- eye-closed -- eye-open -- feedback -- fullscreen -- gear -- graph -- hide -- influx -- influx-icon -- nav-admin -- nav-config -- nav-configuration -- nav-dashboards -- nav-data-explorer -- nav-organizations -- nav-orgs -- nav-tasks -- note -- notebook -- notebooks -- org -- orgs -- pause -- pencil -- play -- plus -- refresh -- remove -- replay -- save-as -- search -- settings -- tasks -- toggle -- trash -- trashcan -- triangle -- view -- wrench -- x - -#### InfluxDB UI left navigation icons - -In many cases, documentation references an item in the left nav of the InfluxDB UI. -Provide a visual example of the navigation item using the `nav-icon` shortcode. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. - -``` -{{< nav-icon "tasks" "v2" >}} -``` - -The following case insensitive values are supported: - -- admin, influx -- data-explorer, data explorer -- notebooks, books -- dashboards -- tasks -- monitor, alerts, bell -- cloud, usage -- data, load data, load-data -- settings -- feedback - -#### Flexbox-formatted content blocks - -CSS Flexbox formatting lets you create columns in article content that adjust and -flow based on the viewable width. -In article content, this helps if you have narrow tables that could be displayed -side-by-side, rather than stacked vertically. -Use the `{{< flex >}}` shortcode to create the Flexbox wrapper. -Use the `{{% flex-content %}}` shortcode to identify each column content block. - -```md -{{< flex >}} -{{% flex-content %}} -Column 1 -{{% /flex-content %}} -{{% flex-content %}} -Column 2 -{{% /flex-content %}} -{{< /flex >}} -``` - -`{{% flex-content %}}` has an optional width argument that determines the maximum -width of the column. - -```md -{{% flex-content "half" %}} -``` - -The following options are available: - -- half _(Default)_ -- third -- quarter - -#### Tooltips - -Use the `{{< tooltip >}}` shortcode to add tooltips to text. -The **first** argument is the text shown in the tooltip. -The **second** argument is the highlighted text that triggers the tooltip. - -```md -I like {{< tooltip "Butterflies are awesome!" "butterflies" >}}. -``` - -The rendered output is "I like butterflies" with "butterflies" highlighted. -When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!" - -#### Flux sample data tables - -The Flux `sample` package provides basic sample datasets that can be used to -illustrate how Flux functions work. To quickly display one of the raw sample -datasets, use the `{{% flux/sample %}}` shortcode. - -The `flux/sample` shortcode has the following arguments that can be specified -by name or positionally. - -##### set - -Sample dataset to output. Use either `set` argument name or provide the set -as the first argument. The following sets are available: - -- float -- int -- uint -- string -- bool -- numericBool - -##### includeNull - -Specify whether or not to include _null_ values in the dataset. -Use either `includeNull` argument name or provide the boolean value as the second argument. - -##### includeRange - -Specify whether or not to include time range columns (`_start` and `_stop`) in the dataset. -This is only recommended when showing how functions that require a time range -(such as `window()`) operate on input data. -Use either `includeRange` argument name or provide the boolean value as the third argument. - -###### Example Flux sample data shortcodes - -```md - - -{{% flux/sample %}} - - - -{{% flux/sample set="string" includeNull=false %}} - - - -{{% flux/sample "int" true %}} - - - - -{{% flux/sample set="int" includeNull=true includeRange=true %}} -{{% flux/sample "int" true true %}} -``` - -#### Duplicate OSS content in Cloud - -Docs for InfluxDB OSS and InfluxDB Cloud share a majority of content. -To prevent duplication of content between versions, use the following shortcodes: - -- `{{< duplicate-oss >}}` -- `{{% oss-only %}}` -- `{{% cloud-only %}}` - -##### duplicate-oss - -The `{{< duplicate-oss >}}` shortcode copies the page content of the file located -at the identical file path in the most recent InfluxDB OSS version. -The Cloud version of this markdown file should contain the frontmatter required -for all pages, but the body content should just be the `{{< duplicate-oss >}}` shortcode. - -##### oss-only - -Wrap content that should only appear in the OSS version of the doc with the `{{% oss-only %}}` shortcode. -Use the shortcode on both inline and content blocks: - -```md -{{% oss-only %}}This is inline content that only renders in the InfluxDB OSS docs{{% /oss-only %}} - -{{% oss-only %}} - -This is a multi-paragraph content block that spans multiple paragraphs and will -only render in the InfluxDB OSS documentation. - -**Note:** Notice the blank newline after the opening short-code tag. -This is necessary to get the first sentence/paragraph to render correctly. - -{{% /oss-only %}} - -- {{% oss-only %}}This is a list item that will only render in InfluxDB OSS docs.{{% /oss-only %}} -- {{% oss-only %}} - - This is a multi-paragraph list item that will only render in the InfluxDB OSS docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /oss-only %}} - -1. Step 1 -2. {{% oss-only %}}This is a list item that will only render in InfluxDB OSS docs.{{% /oss-only %}} -3. {{% oss-only %}} - - This is a list item that contains multiple paragraphs or nested list items and will only render in the InfluxDB OSS docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /oss-only %}} -``` - -##### cloud-only - -Wrap content that should only appear in the Cloud version of the doc with the `{{% cloud-only %}}` shortcode. -Use the shortcode on both inline and content blocks: - -```md -{{% cloud-only %}}This is inline content that only renders in the InfluxDB Cloud docs{{% /cloud-only %}} - -{{% cloud-only %}} - -This is a multi-paragraph content block that spans multiple paragraphs and will -only render in the InfluxDB Cloud documentation. - -**Note:** Notice the blank newline after the opening short-code tag. -This is necessary to get the first sentence/paragraph to render correctly. - -{{% /cloud-only %}} - -- {{% cloud-only %}}This is a list item that will only render in InfluxDB Cloud docs.{{% /cloud-only %}} -- {{% cloud-only %}} - - This is a list item that contains multiple paragraphs or nested list items and will only render in the InfluxDB Cloud docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /cloud-only %}} - -1. Step 1 -2. {{% cloud-only %}}This is a list item that will only render in InfluxDB Cloud docs.{{% /cloud-only %}} -3. {{% cloud-only %}} - - This is a multi-paragraph list item that will only render in the InfluxDB Cloud docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /cloud-only %}} -``` - -#### Show or hide content blocks in shared content - -The `source` frontmatter lets you source page content from another file and is -used to share content across InfluxDB products. Within the shared content, you -can use the `show-in` and `hide-in` shortcodes to conditionally show or hide -content blocks based on the InfluxDB "version." Valid "versions" include: - -- v2 -- cloud -- cloud-serverless -- cloud-dedicated -- clustered -- core -- enterprise - -##### show-in - -The `show-in` shortcode accepts a comma-delimited string of InfluxDB "versions" -to show the content block in. The version is the second level of the page -path--for example: `/influxdb//...`. - -```md -{{% show-in "core,enterprise" %}} - -This content will appear in pages in the InfluxDB 3 Core and InfluxDB 3 Enterprise -documentation, but not any other InfluxDB documentation this content is shared in. - -{{% /show-in %}} -``` - -##### hide-in - -The `hide-in` shortcode accepts a comma-delimited string of InfluxDB "versions" -to hide the content block in. The version is the second level of the page -path--for example: `/influxdb//...`. - -```md -{{% hide-in "core,enterprise" %}} - -This content will not appear in pages in the InfluxDB 3 Core and InfluxDB 3 -Enterprise documentation, but will in all other InfluxDB documentation this -content is shared in. - -{{% /hide-in %}} -``` - -#### All-Caps - -Clockface v3 introduces many buttons with text formatted as all-caps. -Use the `{{< caps >}}` shortcode to format text to match those buttons. - -```md -Click {{< caps >}}Add Data{{< /caps >}} -``` - -#### Code callouts - -Use the `{{< code-callout >}}` shortcode to highlight and emphasize a specific -piece of code (for example, a variable, placeholder, or value) in a code block. -Provide the string to highlight in the code block. -Include a syntax for the codeblock to properly style the called out code. - -````md -{{< code-callout "03a2bbf46249a000" >}} - -```sh -http://localhost:8086/orgs/03a2bbf46249a000/... -``` - -{{< /code-callout >}} -```` - -#### InfluxDB University banners - -Use the `{{< influxdbu >}}` shortcode to add an InfluxDB University banner that -points to the InfluxDB University site or a specific course. -Use the default banner template, a predefined course template, or fully customize -the content of the banner. - -```html - -{{< influxdbu >}} - - -{{< influxdbu "influxdb-101" >}} - - -{{< influxdbu title="Course title" summary="Short course summary." action="Take -the course" link="https://university.influxdata.com/" >}} -``` - -##### Course templates - -Use one of the following course templates: - -- influxdb-101 -- telegraf-102 -- flux-103 - -##### Custom banner content - -Use the following shortcode parameters to customize the content of the InfluxDB -University banner: - -- **title**: Course or banner title -- **summary**: Short description shown under the title -- **action**: Text of the button -- **link**: URL the button links to - -#### Reference content - -The InfluxDB documentation is "task-based," meaning content primarily focuses on -what a user is **doing**, not what they are **using**. -However, there is a need to document tools and other things that don't necessarily -fit in the task-based style. -This is referred to as "reference content." - -Reference content is styled just as the rest of the InfluxDB documentation. -The only difference is the `menu` reference in the page's frontmatter. -When defining the menu for reference content, use the following pattern: - -```yaml -# Pattern -menu: - ___ref: - # ... - -# Example -menu: - influxdb_2_0_ref: - # ... -``` - -#### InfluxDB URLs - -When a user selects an InfluxDB product and region, example URLs in code blocks -throughout the documentation are updated to match their product and region. -InfluxDB URLs are configured in `/data/influxdb_urls.yml`. - -By default, the InfluxDB URL replaced inside of code blocks is `http://localhost:8086`. -Use this URL in all code examples that should be updated with a selected provider and region. - -For example: - -```` -```sh -# This URL will get updated -http://localhost:8086 - -# This URL will NOT get updated -http://example.com -``` -```` - -If the user selects the **US West (Oregon)** region, all occurrences of `http://localhost:8086` -in code blocks will get updated to `https://us-west-2-1.aws.cloud2.influxdata.com`. - -##### Exempt URLs from getting updated - -To exempt a code block from being updated, include the `{{< keep-url >}}` shortcode -just before the code block. - -```` -{{< keep-url >}} -``` -// This URL won't get updated -http://localhost:8086 -``` -```` - -##### Code examples only supported in InfluxDB Cloud - -Some functionality is only supported in InfluxDB Cloud and code examples should -only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com` -as the placeholder in the code block. It will get updated on page load and when -users select a Cloud region in the URL select modal. - -```` -```sh -# This URL will get updated -https://cloud2.influxdata.com -``` -```` - -##### Automatically populate InfluxDB host placeholder - -The InfluxDB host placeholder that gets replaced by custom domains differs -between each InfluxDB product/version. -Use the `influxdb/host` shortcode to automatically render the correct -host placeholder value for the current product. You can also pass a single -argument to specify a specific InfluxDB product to use. -Supported argument values: - -- oss -- cloud -- cloud-serverless -- cloud-dedicated -- clustered -- core -- enterprise - -``` -{{< influxdb/host >}} - -{{< influxdb/host "serverless" >}} -``` - -##### User-populated placeholders - -Use the `code-placeholders` shortcode to format placeholders -as text fields that users can populate with their own values. -The shortcode takes a regular expression for matching placeholder names. -Use the `code-placeholder-key` shortcode to format the placeholder names in -text that describes the placeholder--for example: - -```markdown -{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} -```sh -curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ - --header "Authorization: Token API_TOKEN" \ - --data-binary @path/to/line-protocol.txt -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to -- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) -``` - - - -### Advanced Configuration - -#### Vale style linting configuration - -docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms. - -**Advanced Vale usage:** - -```sh -docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md -``` - -The output contains error-level style alerts for the Markdown content. - -**Note**: We strongly recommend running Vale, but it's not included in the -docs-v2 pre-commit hooks for now. -You can include it in your own Git hooks. - -If a file contains style, spelling, or punctuation problems, -the Vale linter can raise one of the following alert levels: - -- **Error**: - - Problems that can cause content to render incorrectly - - Violations of branding guidelines or trademark guidelines - - Rejected vocabulary terms -- **Warning**: General style guide rules and best practices -- **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list - -#### Configure style rules - -`/.ci/vale/styles/` contains configuration files for the custom `InfluxDataDocs` style. - -The easiest way to add accepted or rejected spellings is to enter your terms (or regular expression patterns) into the Vocabulary files at `.ci/vale/styles/config/vocabularies`. - -To add accepted/rejected terms for specific products, configure a style for the product and include a `Branding.yml` configuration. As an example, see `content/influxdb/cloud-dedicated/.vale.ini` and `.ci/vale/styles/Cloud-Dedicated/Branding.yml`. - -To learn more about configuration and rules, see [Vale configuration](https://vale.sh/docs/topics/config). - - -#### JavaScript in the documentation UI - -The InfluxData documentation UI uses JavaScript with ES6+ syntax and -`assets/js/main.js` as the entry point to import modules from -`assets/js`. -Only `assets/js/main.js` should be imported in HTML files. - -`assets/js/main.js` registers components and initializes them on page load. - -If you're adding UI functionality that requires JavaScript, follow these steps: - -1. In your HTML file, add a `data-component` attribute to the element that - should be initialized by your JavaScript code. For example: - - ```html -
- ``` - -2. Following the component pattern, create a single-purpose JavaScript module - (`assets/js/components/my-component.js`) - that exports a single function that receives the component element and initializes it. -3. In `assets/js/main.js`, import the module and register the component to ensure - the component is initialized on page load. - -##### Debugging JavaScript - -To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods: - -- Use source maps and the Chrome DevTools debugger. -- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger. - -###### Using source maps and Chrome DevTools debugger - -1. In VS Code, select Run > Start Debugging. -2. Select the "Debug Docs (source maps)" configuration. -3. Click the play button to start the debugger. -5. Set breakpoints in the JavaScript source files--files in the - `assets/js/ns-hugo-imp:` namespace-- in the - VS Code editor or in the Chrome Developer Tools Sources panel: - - - In the VS Code Debugger panel > "Loaded Scripts" section, find the - `assets/js/ns-hugo-imp:` namespace. - - In the Chrome Developer Tools Sources panel, expand - `js/ns-hugo-imp://assets/js/`. - -###### Using debug helpers - -1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`. - These helpers provide breakpoints and console logging as a workaround or alternative for - using source maps and the Chrome DevTools debugger. -2. Insert debug statements by calling the helper functions in your code--for example: - - ```js - import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; - - const data = debugInspect(someData, 'Data'); - debugLog('Processing data', 'myFunction'); - - function processData() { - // Add a breakpoint that works with DevTools - debugBreak(); - - // Your existing code... - } - ``` - -3. Start Hugo in development mode--for example: - - ```bash - yarn hugo server - ``` - -4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. - -Your system uses the configuration in `launch.json` to launch the site in Chrome -and attach the debugger to the Developer Tools console. - -Make sure to remove the debug statements before merging your changes. -The debug helpers are designed to be used in development and should not be used in production. \ No newline at end of file diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md new file mode 100644 index 000000000..f605d08f9 --- /dev/null +++ b/DOCS-CONTRIBUTING.md @@ -0,0 +1,442 @@ +# Contributing to InfluxData Documentation + + +## Quick Start + +Ready to contribute? + +1. [Sign the InfluxData CLA](#sign-the-influxdata-cla) (for substantial changes) +2. [Fork and clone](#fork-and-clone-influxdata-documentation-repository) this repository +3. [Install dependencies](#development-environment-setup) (Node.js, Yarn, Docker) +4. Make your changes following [style guidelines](#making-changes) +5. [Test your changes](TESTING.md) (pre-commit and pre-push hooks run automatically) +6. [Submit a pull request](#submission-process) + +For detailed setup and reference information, see the sections below. + +--- + +## Legal & Getting Started + +### Sign the InfluxData CLA + +The InfluxData Contributor License Agreement (CLA) is part of the legal framework +for the open source ecosystem that protects both you and InfluxData. +To make substantial contributions to InfluxData documentation, first sign the InfluxData CLA. +What constitutes a "substantial" change is at the discretion of InfluxData documentation maintainers. + +[Sign the InfluxData CLA](https://www.influxdata.com/legal/cla/) + +_**Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA._ + +_If you're new to contributing or you're looking for an easy update, see [`docs-v2` good-first-issues](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)._ + +### Fork and clone InfluxData Documentation Repository + +[Fork this repository](https://help.github.com/articles/fork-a-repo/) and +[clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine. + +--- + + +## Development Environment Setup + +### Prerequisites + +docs-v2 automatically runs format (Markdown, JS, and CSS) linting and code block tests for staged files that you try to commit. + +For the linting and tests to run, you need to install: + +- **Node.js and Yarn**: For managing dependencies and running build scripts +- **Docker**: For running Vale linter and code block tests +- **VS Code extensions** (optional): For enhanced editing experience + +\_**Note:** +The git pre-commit and pre-push hooks are configured to run linting and tests automatically +when you commit or push changes. +We strongly recommend letting them run, but you can skip them +(and avoid installing related dependencies) +by including the `--no-verify` flag with your commit--for example: + +```sh +git commit -m "" --no-verify +``` + +### Install Node.js dependencies + +To install dependencies listed in package.json: + +1. Install [Node.js](https://nodejs.org/en) for your system. +2. Install [Yarn](https://yarnpkg.com/getting-started/install) for your system. +3. Run `yarn` to install dependencies (including Hugo). + +`package.json` contains dependencies used in `/assets/js` JavaScript code and +dev dependencies used in pre-commit hooks for linting, syntax-checking, and testing. + +Dev dependencies include: + +- [Lefthook](https://github.com/evilmartians/lefthook): configures and +manages git pre-commit and pre-push hooks for linting and testing Markdown content. +- [prettier](https://prettier.io/docs/en/): formats code, including Markdown, according to style rules for consistency +- [Cypress]: e2e testing for UI elements and URLs in content + +### Install Docker + +docs-v2 includes Docker configurations (`compose.yaml` and Dockerfiles) for running the Vale style linter and tests for code blocks (Shell, Bash, and Python) in Markdown files. + +Install [Docker](https://docs.docker.com/get-docker/) for your system. + +#### Build the test dependency image + +After you have installed Docker, run the following command to build the test +dependency image, `influxdata:docs-pytest`. +The tests defined in `compose.yaml` use the dependencies and execution +environment from this image. + +```bash +docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . +``` + +### Run the documentation locally (optional) + +To run the documentation locally, follow the instructions provided in the README. + +### Install Visual Studio Code extensions + +If you use Microsoft Visual Studio (VS) Code, you can install extensions +to help you navigate, check, and edit files. + +docs-v2 contains a `./.vscode/settings.json` that configures the following extensions: + +- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments. +- Vale: shows linter errors and suggestions in the editor. +- YAML Schemas: validates frontmatter attributes. + +--- + + +## Making Changes + + +### Style Guidelines + +#### Markdown + +Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). + +_Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling._ + +#### Semantic line feeds + +Use [semantic line feeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). +Separating each sentence with a new line makes it easy to parse diffs with the human eye. + +**Diff without semantic line feeds:** + +```diff +-Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. ++Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. +``` + +**Diff with semantic line feeds:** + +```diff +Data is taking off. +This data is time series. +You need a database that specializes in time series. +-You should check out InfluxDB. ++You need InfluxDB. +``` + +#### Article headings + +Use only h2-h6 headings in markdown content. +h1 headings act as the page title and are populated automatically from the `title` frontmatter. +h2-h6 headings act as section headings. + +#### Image naming conventions + +Save images using the following naming format: `project/version-context-description.png`. +For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png`. +Specify a version other than 2.0 only if the image is specific to that version. + +### Essential Frontmatter Reference + +Every documentation page includes frontmatter which specifies information about the page. +Frontmatter populates variables in page templates and the site's navigation menu. + +**Essential fields:** + +```yaml +title: # Title of the page used in the page's h1 +description: # Page description displayed in search engine results +menu: + influxdb_2_0: + name: # Article name that only appears in the left nav + parent: # Specifies a parent group and nests navigation items +weight: # Determines sort order in both the nav tree and in article lists +``` + +For the complete frontmatter reference with all available fields and detailed usage, see **[DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md)**. + +### Shared Content + +This repository uses shared content extensively to avoid duplication across InfluxDB editions and versions. + +Use the `source` frontmatter to specify a shared file for page content: + +```yaml +source: /shared/path/to/content.md +``` + +For complete details including examples and best practices, see the [Source section in DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md#source). + + +### Common Shortcodes Reference + +#### Callouts (notes and warnings) + +```md +> [!Note] +> Insert note markdown content here. + +> [!Warning] +> Insert warning markdown content here. + +> [!Caution] +> Insert caution markdown content here. + +> [!Important] +> Insert important markdown content here. + +> [!Tip] +> Insert tip markdown content here. +``` + +#### Tabbed content + +```md +{{< tabs-wrapper >}} + +{{% tabs %}} +[Button text for tab 1](#) +[Button text for tab 2](#) +{{% /tabs %}} + +{{% tab-content %}} +Markdown content for tab 1. +{{% /tab-content %}} + +{{% tab-content %}} +Markdown content for tab 2. +{{% /tab-content %}} + +{{< /tabs-wrapper >}} +``` + +#### Required elements + +```md +{{< req >}} +{{< req type="key" >}} + +- {{< req "\*" >}} **This element is required** +- {{< req "\*" >}} **This element is also required** +- **This element is NOT required** +``` + +For the complete shortcodes reference with all available shortcodes and usage examples, see **[SHORTCODES.md](SHORTCODES.md)**. + +Test shortcodes with working examples in **[content/example.md](content/example.md)**. + +--- + +### InfluxDB API documentation + +docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. The files are written in YAML and use [OpenAPI 3.0](https://swagger.io/specification/) standard. + +InfluxData uses [Redoc](https://github.com/Redocly/redoc) to build and generate the full +InfluxDB API documentation when documentation is deployed. +For more information about editing and generating InfluxDB API documentation, see the +[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). + +--- + +## Testing & Quality Assurance + + +Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: + +```sh +git commit -m "" --no-verify +``` + +### Quick Testing Reference + +```bash +# Test code blocks +yarn test:codeblocks:all + +# Test links +yarn test:links content/influxdb3/core/**/*.md + +# Run style linting +docker compose run -T vale content/**/*.md +``` + +For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. + + +--- + + +## Submission Process + + +### Commit Guidelines + +When creating commits, follow these guidelines: + +- Use a clear, descriptive commit message that explains the change +- Start with a type prefix: `fix()`, `feat()`, `style()`, `refactor()`, `test()`, `chore()` +- For product-specific changes, include the product in parentheses: `fix(enterprise)`, `fix(influxdb3)`, `fix(core)` +- Keep the first line under 72 characters +- Reference issues with "closes" or "fixes": `closes #123` or `closes influxdata/DAR#123` +- For multiple issues, use comma separation: `closes influxdata/DAR#517, closes influxdata/DAR#518` + +**Examples:** +``` +fix(enterprise): correct Docker environment variable name for license email +fix(influxdb3): correct Docker environment variable and compose examples for monolith +feat(telegraf): add new plugin documentation +chore(ci): update Vale configuration +``` + +### Submit a pull request + +Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). + +--- + +## Reference Documentation + +For detailed reference documentation, see: + +- **[FRONTMATTER.md](FRONTMATTER.md)** - Complete frontmatter field reference with all available options +- **[SHORTCODES.md](SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes + + +### Advanced Configuration + +#### Vale style linting configuration + +docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms. + +**Advanced Vale usage:** + +```sh +docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md +``` + +The output contains error-level style alerts for the Markdown content. + +If a file contains style, spelling, or punctuation problems, +the Vale linter can raise one of the following alert levels: + +- **Error**: + - Problems that can cause content to render incorrectly + - Violations of branding guidelines or trademark guidelines + - Rejected vocabulary terms +- **Warning**: General style guide rules and best practices +- **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list + +#### Configure style rules + +`/.ci/vale/styles/` contains configuration files for the custom `InfluxDataDocs` style. + +The easiest way to add accepted or rejected spellings is to enter your terms (or regular expression patterns) into the Vocabulary files at `.ci/vale/styles/config/vocabularies`. + +To add accepted/rejected terms for specific products, configure a style for the product and include a `Branding.yml` configuration. As an example, see `content/influxdb/cloud-dedicated/.vale.ini` and `.ci/vale/styles/Cloud-Dedicated/Branding.yml`. + +To learn more about configuration and rules, see [Vale configuration](https://vale.sh/docs/topics/config). + + +#### JavaScript in the documentation UI + +The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and +`assets/js/main.js` as the entry point to import modules from +`assets/js`. +Only `assets/js/main.js` should be imported in HTML files. + +`assets/js/main.js` registers components and initializes them on page load. + +If you're adding UI functionality that requires JavaScript, follow these steps: + +1. In your HTML file, add a `data-component` attribute to the element that + should be initialized by your JavaScript code. For example: + + ```html +
+ ``` + +2. Following the component pattern, create a single-purpose JavaScript module + (`assets/js/components/my-component.js`) + that exports a single function that receives the component element and initializes it. +3. In `assets/js/main.js`, import the module and register the component to ensure + the component is initialized on page load. + +##### Debugging JavaScript + +To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods: + +- Use source maps and the Chrome DevTools debugger. +- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger. + +###### Using source maps and Chrome DevTools debugger + +1. In VS Code, select Run > Start Debugging. +2. Select the "Debug Docs (source maps)" configuration. +3. Click the play button to start the debugger. +5. Set breakpoints in the JavaScript source files--files in the + `assets/js/ns-hugo-imp:` namespace-- in the + VS Code editor or in the Chrome Developer Tools Sources panel: + + - In the VS Code Debugger panel > "Loaded Scripts" section, find the + `assets/js/ns-hugo-imp:` namespace. + - In the Chrome Developer Tools Sources panel, expand + `js/ns-hugo-imp://assets/js/`. + +###### Using debug helpers + +1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`. + These helpers provide breakpoints and console logging as a workaround or alternative for + using source maps and the Chrome DevTools debugger. +2. Insert debug statements by calling the helper functions in your code--for example: + + ```js + import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; + + const data = debugInspect(someData, 'Data'); + debugLog('Processing data', 'myFunction'); + + function processData() { + // Add a breakpoint that works with DevTools + debugBreak(); + + // Your existing code... + } + ``` + +3. Start Hugo in development mode--for example: + + ```bash + yarn hugo server + ``` + +4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. + +Your system uses the configuration in `launch.json` to launch the site in Chrome +and attach the debugger to the Developer Tools console. + +Make sure to remove the debug statements before merging your changes. +The debug helpers are designed to be used in development and should not be used in production. \ No newline at end of file diff --git a/DOCS-FRONTMATTER.md b/DOCS-FRONTMATTER.md new file mode 100644 index 000000000..41017838f --- /dev/null +++ b/DOCS-FRONTMATTER.md @@ -0,0 +1,274 @@ +# Frontmatter Reference + +Complete reference for frontmatter fields used in InfluxData documentation pages. + +## Essential Fields + +Every documentation page requires these fields: + +```yaml +title: # Page h1 heading +description: # SEO meta description +menu: + product_version: + name: # Navigation link text + parent: # Parent menu item (if nested) +weight: # Sort order (1-99, 101-199, 201-299...) +``` + +## Complete Field Reference + +```yaml +title: # Title of the page used in the page's h1 +seotitle: # Page title used in the html title and used in search engine results +list_title: # Title used in article lists generated using the {{< children >}} shortcode +description: # Page description displayed in search engine results +menu: + influxdb_2_0: + name: # Article name that only appears in the left nav + parent: # Specifies a parent group and nests navigation items +weight: # Determines sort order in both the nav tree and in article lists +draft: # If true, will not render page on build +product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version ) +related: # Creates links to specific internal and external content at the bottom of the page + - /path/to/related/article + - https://external-link.com, This is an external link +external_url: # Used in children shortcode type="list" for page links that are external +list_image: # Image included with article descriptions in children type="articles" shortcode +list_note: # Used in children shortcode type="list" to add a small note next to listed links +list_code_example: # Code example included with article descriptions in children type="articles" shortcode +list_query_example:# Code examples included with article descriptions in children type="articles" shortcode, + # References to examples in data/query_examples +canonical: # Path to canonical page, overrides auto-gen'd canonical URL +v2: # Path to v2 equivalent page +alt_links: # Alternate pages in other products/versions for cross-product navigation + cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/ + core: /influxdb3/core/path/to/page/ +prepend: # Prepend markdown content to an article (especially powerful with cascade) + block: # (Optional) Wrap content in a block style (note, warn, cloud) + content: # Content to prepend to article +append: # Append markdown content to an article (especially powerful with cascade) + block: # (Optional) Wrap content in a block style (note, warn, cloud) + content: # Content to append to article +metadata: [] # List of metadata messages to include under the page h1 +updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata) +source: # Specify a file to pull page content from (typically in /content/shared/) +``` + +## Field Usage Details + +### Title Fields + +#### `title` + +The `title` frontmatter populates each page's HTML `h1` heading tag. +It shouldn't be overly long, but should set the context for users coming from outside sources. + +#### `seotitle` + +The `seotitle` frontmatter populates each page's HTML `title` attribute. +Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized. + +#### `list_title` + +The `list_title` frontmatter determines an article title when in a list generated +by the [`{{< children >}}` shortcode](#generate-a-list-of-children-articles). + +#### `menu > name` + +The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation. +It should be short and assume the context of its parent if it has one. + +### Page Weights + +To ensure pages are sorted both by weight and their depth in the directory +structure, pages should be weighted in "levels." +All top level pages are weighted 1-99. +The next level is 101-199. +Then 201-299 and so on. + +_**Note:** `_index.md` files should be weighted one level up from the other `.md` files in the same directory._ + +### Related Content + +Use the `related` frontmatter to include links to specific articles at the bottom of an article. + +- If the page exists inside of this documentation, just include the path to the page. + It will automatically detect the title of the page. +- If the page exists inside of this documentation, but you want to customize the link text, + include the path to the page followed by a comma, and then the custom link text. + The path and custom text must be in that order and separated by a comma and a space. +- If the page exists outside of this documentation, include the full URL and a title for the link. + The link and title must be in that order and separated by a comma and a space. + +```yaml +related: + - /v2.0/write-data/quick-start + - /v2.0/write-data/quick-start, This is custom text for an internal link + - https://influxdata.com, This is an external link +``` + +### Canonical URLs + +Search engines use canonical URLs to accurately rank pages with similar or identical content. +The `canonical` HTML meta tag identifies which page should be used as the source of truth. + +By default, canonical URLs are automatically generated for each page in the InfluxData +documentation using the latest version of the current product and the current path. + +Use the `canonical` frontmatter to override the auto-generated canonical URL. + +_**Note:** The `canonical` frontmatter supports the [`{{< latest >}}` shortcode](#latest-links)._ + +```yaml +canonical: /path/to/canonical/doc/ + +# OR + +canonical: /{{< latest "influxdb" "v2" >}}/path/to/canonical/doc/ +``` + +### v2 Equivalent Documentation + +To display a notice on a 1.x page that links to an equivalent 2.0 page, +add the following frontmatter to the 1.x page: + +```yaml +v2: /influxdb/v2.0/get-started/ +``` + +### Alternative Links (alt_links) + +Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products, +for example, when a page exists at a different path in a different version or if +the feature doesn't exist in that product. +This enables the product switcher to navigate users to the corresponding page when they +switch between products. If a page doesn't exist in another product (for example, an +Enterprise-only feature), point to the nearest parent page if relevant. + +```yaml +alt_links: + cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ + cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ + core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist +``` + +Supported product keys for InfluxDB 3: +- `core` +- `enterprise` +- `cloud-serverless` +- `cloud-dedicated` +- `clustered` + +### Prepend and Append + +Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page. +Each has the following fields: + +```yaml +append: | + > [!Note] + > #### This is example markdown content + > This is just an example note block that gets appended to the article. +``` + +Use this frontmatter with [cascade](#cascade) to add the same content to +all children pages as well. + +```yaml +cascade: + append: | + > [!Note] + > #### This is example markdown content + > This is just an example note block that gets appended to the article. +``` + +### Cascade + +To automatically apply frontmatter to a page and all of its children, use the +[`cascade` frontmatter](https://gohugo.io/content-management/front-matter/#front-matter-cascade) +built in into Hugo. + +```yaml +title: Example page +description: Example description +cascade: + layout: custom-layout +``` + +`cascade` applies the frontmatter to all children unless the child already includes +those frontmatter keys. Frontmatter defined on the page overrides frontmatter +"cascaded" from a parent. + +### Source + +This repository makes heavy use of shared content to avoid duplication across InfluxDB editions and versions. +Use the `source` frontmatter to specify a shared file to use to populate the +page content. Shared files are typically stored in the `/content/shared` directory. To source files, include the absolute path from the `/content` directory--for example, for a file located at `/content/shared/influxdb3-admin/databases/_index.md`, use the following frontmatter: + +```yaml +source: /shared/influxdb3-admin/databases/_index.md +``` + +When building shared content, use the `show-in` and `hide-in` shortcodes to show +or hide blocks of content based on the current InfluxDB product/version. +For more information, see [show-in](/.github/instructions/shortcodes-reference.instructions.md#show-in) and [hide-in](/.github/instructions/shortcodes-reference.instructions.md#hide-in). + +#### Links in shared content + +When creating links in shared content files, you can use the `version` keyword, which gets replaced during the build process with the appropriate product version. + +**Use this in shared content:** +```markdown +[Configuration options](/influxdb3/version/reference/config-options/) +[CLI serve command](/influxdb3/version/reference/cli/influxdb3/serve/) +``` + +**Not this:** +```markdown +[Configuration options](/influxdb3/{{% product-key %}}/reference/config-options/) +[CLI serve command](/influxdb3/{{% product-key %}}/reference/cli/influxdb3/serve/) +``` + +Don't list links to related content at the bottom of shared content files. +Instead, add the `related` frontmatter to the individual pages that use the shared content. + +### Validations for shared content + +If you edit shared content files, the link and style checks configured for the repository run on all files that use that shared content. + +## Children Shortcode Specific Frontmatter + +The following frontmatter fields are used specifically with the `{{< children >}}` shortcode +to control how pages appear in generated lists: + +### `list_title` + +Title used in article lists generated using the `{{< children >}}` shortcode. + +### `external_url` + +Used in `children` shortcode `type="list"` for page links that are external. + +### `list_image` + +Image included with article descriptions in `children type="articles"` shortcode. + +### `list_note` + +Used in `children` shortcode `type="list"` to add a small note next to listed links. + +### `list_code_example` + +Code example included with article descriptions in `children type="articles"` shortcode. + +### `list_query_example` + +Code examples included with article descriptions in `children type="articles"` shortcode. +References examples in `data/query_examples`. + +## Additional Resources + +- **Shortcodes Reference**: See `/.github/instructions/shortcodes-reference.instructions.md` +- **Contributing Guide**: See `/.github/instructions/contributing.instructions.md` +- **Style Guidelines**: Follow Google Developer Documentation style guidelines diff --git a/.github/instructions/shortcodes-reference.instructions.md b/DOCS-SHORTCODES.md similarity index 59% rename from .github/instructions/shortcodes-reference.instructions.md rename to DOCS-SHORTCODES.md index b5de68ec8..7c7ab9320 100644 --- a/.github/instructions/shortcodes-reference.instructions.md +++ b/DOCS-SHORTCODES.md @@ -1,13 +1,98 @@ ---- -applyTo: "content/**/*.md, layouts/**/*.html" +# Hugo Shortcodes Reference + +Complete reference for custom Hugo shortcodes used in InfluxData documentation. + +**For working examples and testing**: See [content/example.md](content/example.md) + +## Table of Contents + +- [Notes and Warnings](#notes-and-warnings) +- [Required Elements](#required-elements) +- [Product Data](#product-data) +- [Version Information](#version-information) +- [API Documentation](#api-documentation) +- [Content Organization](#content-organization) +- [Visual Elements](#visual-elements) +- [Content Formatting](#content-formatting) +- [Code Examples](#code-examples) +- [Data and Samples](#data-and-samples) +- [Content Management](#content-management) +- [Special Purpose](#special-purpose) + --- -### Complete Shortcodes Reference +## Notes and Warnings -influxdata/docs-v2 uses a variety of custom Hugo shortcodes to add functionality. -For more usage examples, see the shortcode test page at `/content/example.md`. +Use GitHub-flavored Markdown blockquotes with special alert types: -#### Product data +```md +> [!Note] +> Insert note markdown content here. + +> [!Warning] +> Insert warning markdown content here. + +> [!Caution] +> Insert caution markdown content here. + +> [!Important] +> Insert important markdown content here. + +> [!Tip] +> Insert tip markdown content here. +``` + +## Required Elements + +Use the `{{< req >}}` shortcode to identify required elements in documentation with orange text and/or asterisks. By default, the shortcode outputs the text, "Required," but you can customize the text by passing a string argument with the shortcode. + +### Basic usage + +```md +{{< req >}} +``` + +**Output:** Required + +```md +{{< req "This is Required" >}} +``` + +**Output:** This is required + +If using other named arguments like `key` or `color`, use the `text` argument to customize the text of the required message. + +```md +{{< req text="Required if ..." color="blue" type="key" >}} +``` + +### Required elements in a list + +When identifying required elements in a list, use `{{< req type="key" >}}` to generate a "\* Required" key before the list. For required elements in the list, include {{< req "\*" >}} before the text of the list item. For example: + +```md +{{< req type="key" >}} + +- {{< req "\*" >}} **This element is required** +- {{< req "\*" >}} **This element is also required** +- **This element is NOT required** +``` + +### Change color of required text + +Use the `color` argument to change the color of required text. The following colors are available: + +- blue +- green +- magenta + +```md +{{< req color="magenta" text="This is required" >}} +``` + +## Product Data + +### Product name Display the full product name and version name for the current page--for example: @@ -18,7 +103,9 @@ Display the full product name and version name for the current page--for example {{% product-name %}} ``` -Display the short version name (part of the key used in `products.yml`) from the current page URL--for example: +### Product key + +Display the short version name (part of the key used in `products.yml`) from the current page URL--for example: - `/influxdb3/core` returns `core` @@ -26,38 +113,30 @@ Display the short version name (part of the key used in `products.yml`) from the {{% product-key %}} ``` -##### Enterprise name +### Enterprise name -The name used to refer to InfluxData's enterprise offering is subject to change. -To facilitate easy updates in the future, use the `enterprise-name` shortcode -when referencing the enterprise product. -This shortcode accepts a `"short"` parameter which uses the "short-name". +The name used to refer to InfluxData's enterprise offering is subject to change. To facilitate easy updates in the future, use the `enterprise-name` shortcode when referencing the enterprise product. This shortcode accepts a `"short"` parameter which uses the "short-name". -``` +```md This is content that references {{< enterprise-name >}}. This is content that references {{< enterprise-name "short" >}}. ``` Product names are stored in `data/products.yml`. -##### Enterprise link +### Enterprise link -References to InfluxDB Enterprise are often accompanied with a link to a page where -visitors can get more information about the Enterprise offering. -This link is subject to change. -Use the `enterprise-link` shortcode when including links to more information about -InfluxDB Enterprise. +References to InfluxDB Enterprise are often accompanied with a link to a page where visitors can get more information about the Enterprise offering. This link is subject to change. Use the `enterprise-link` shortcode when including links to more information about InfluxDB Enterprise. -``` +```md Find more info [here][{{< enterprise-link >}}] ``` -#### Latest patch version +## Version Information -Use the `{{< latest-patch >}}` shortcode to add the latest patch version of a product. -By default, this shortcode parses the product and minor version from the URL. -To specify a specific product and minor version, use the `product` and `version` arguments. -Easier to maintain being you update the version number in the `data/products.yml` file instead of updating individual links and code examples. +### Latest patch version + +Use the `{{< latest-patch >}}` shortcode to add the latest patch version of a product. By default, this shortcode parses the product and minor version from the URL. To specify a specific product and minor version, use the `product` and `version` arguments. Easier to maintain being you update the version number in the `data/products.yml` file instead of updating individual links and code examples. ```md {{< latest-patch >}} @@ -67,13 +146,9 @@ Easier to maintain being you update the version number in the `data/products.yml {{< latest-patch product="chronograf" version="1.7" >}} ``` -#### Latest influx CLI version +### Latest influx CLI version -Use the `{{< latest-patch cli=true >}}` shortcode to add the latest version of the `influx` -CLI supported by the minor version of InfluxDB. -By default, this shortcode parses the minor version from the URL. -To specify a specific minor version, use the `version` argument. -Maintain CLI version numbers in the `data/products.yml` file instead of updating individual links and code examples. +Use the `{{< latest-patch cli=true >}}` shortcode to add the latest version of the `influx` CLI supported by the minor version of InfluxDB. By default, this shortcode parses the minor version from the URL. To specify a specific minor version, use the `version` argument. Maintain CLI version numbers in the `data/products.yml` file instead of updating individual links and code examples. ```md {{< latest-patch cli=true >}} @@ -81,21 +156,16 @@ Maintain CLI version numbers in the `data/products.yml` file instead of updating {{< latest-cli version="2.1" >}} ``` -#### API endpoint +## API Documentation -Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains -a colored request method, a specified API endpoint, and an optional link to -the API reference documentation. -Provide the following arguments: +### API endpoint + +Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains a colored request method, a specified API endpoint, and an optional link to the API reference documentation. Provide the following arguments: - **method**: HTTP request method (get, post, patch, put, or delete) - **endpoint**: API endpoint - **api-ref**: Link the endpoint to a specific place in the API documentation -- **influxdb_host**: Specify which InfluxDB product host to use - _if the `endpoint` contains the `influxdb/host` shortcode_. - Uses the current InfluxDB product as default. - Supports the following product values: - +- **influxdb_host**: Specify which InfluxDB product host to use _if the `endpoint` contains the `influxdb/host` shortcode_. Uses the current InfluxDB product as default. Supports the following product values: - oss - cloud - serverless @@ -110,41 +180,39 @@ Provide the following arguments: {{< api-endpoint method="get" endpoint="{{< influxdb/host >}}/api/v2/tasks" influxdb_host="cloud">}} ``` -#### Tabbed Content +## Content Organization + +### Tabbed Content To create "tabbed" content (content that is changed by a users' selection), use the following three shortcodes in combination: -`{{< tabs-wrapper >}}` -This shortcode creates a wrapper or container for the tabbed content. -All UI interactions are limited to the scope of each container. -If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`. -This shortcode must be closed with `{{< /tabs-wrapper >}}`. +#### tabs-wrapper + +`{{< tabs-wrapper >}}` +This shortcode creates a wrapper or container for the tabbed content. All UI interactions are limited to the scope of each container. If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`. This shortcode must be closed with `{{< /tabs-wrapper >}}`. **Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML. -`{{% tabs %}}` -This shortcode creates a container for buttons that control the display of tabbed content. -It should contain simple markdown links with anonymous anchors (`#`). -The link text is used as the button text. -This shortcode must be closed with `{{% /tabs %}}`. +#### tabs + +`{{% tabs %}}` +This shortcode creates a container for buttons that control the display of tabbed content. It should contain simple markdown links with anonymous anchors (`#`). The link text is used as the button text. This shortcode must be closed with `{{% /tabs %}}`. **Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. -The `{{% tabs %}}` shortcode has an optional `style` argument that lets you -assign CSS classes to the tags HTML container. The following classes are available: +The `{{% tabs %}}` shortcode has an optional `style` argument that lets you assign CSS classes to the tags HTML container. The following classes are available: - **small**: Tab buttons are smaller and don't scale to fit the width. - **even-wrap**: Prevents uneven tab widths when tabs are forced to wrap. -`{{% tab-content %}}` -This shortcode creates a container for a content block. -Each content block in the tab group needs to be wrapped in this shortcode. -**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode** -This shortcode must be closed with `{{% /tab-content %}}`. +#### tab-content + +`{{% tab-content %}}` +This shortcode creates a container for a content block. Each content block in the tab group needs to be wrapped in this shortcode. **The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode** This shortcode must be closed with `{{% /tab-content %}}`. **Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. -##### Example tabbed content group +#### Example tabbed content group ```md {{< tabs-wrapper >}} @@ -165,14 +233,12 @@ Markdown content for tab 2. {{< /tabs-wrapper >}} ``` -##### Tabbed code blocks +#### Tabbed code blocks -Shortcodes are also available for tabbed code blocks primarily used to give users -the option to choose between different languages and syntax. -The shortcode structure is the same as above, but the shortcode names are different: +Shortcodes are also available for tabbed code blocks primarily used to give users the option to choose between different languages and syntax. The shortcode structure is the same as above, but the shortcode names are different: -`{{< code-tabs-wrapper >}}` -`{{% code-tabs %}}` +`{{< code-tabs-wrapper >}}` +`{{% code-tabs %}}` `{{% code-tab-content %}}` ````md @@ -209,73 +275,17 @@ WHERE time > now() - 15m {{< /code-tabs-wrapper >}} ```` -##### Link to tabbed content +#### Link to tabbed content -To link to tabbed content, click on the tab and use the URL parameter shown. -It will have the form `?t=`, plus a string. -For example: +To link to tabbed content, click on the tab and use the URL parameter shown. It will have the form `?t=`, plus a string. For example: -``` +```md [Windows installation](/influxdb/v2.0/install/?t=Windows) ``` -#### Required elements +### Page navigation buttons -Use the `{{< req >}}` shortcode to identify required elements in documentation with -orange text and/or asterisks. By default, the shortcode outputs the text, "Required," but -you can customize the text by passing a string argument with the shortcode. - -```md -{{< req >}} -``` - -**Output:** Required - -```md -{{< req "This is Required" >}} -``` - -**Output:** This is required - -If using other named arguments like `key` or `color`, use the `text` argument to -customize the text of the required message. - -```md -{{< req text="Required if ..." color="blue" type="key" >}} -``` - -##### Required elements in a list - -When identifying required elements in a list, use `{{< req type="key" >}}` to generate -a "\* Required" key before the list. For required elements in the list, include -{{< req "\*" >}} before the text of the list item. For example: - -```md -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` - -##### Change color of required text - -Use the `color` argument to change the color of required text. -The following colors are available: - -- blue -- green -- magenta - -```md -{{< req color="magenta" text="This is required" >}} -``` - -#### Page navigation buttons - -Use the `{{< page-nav >}}` shortcode to add page navigation buttons to a page. -These are useful for guiding users through a set of docs that should be read in sequential order. -The shortcode has the following parameters: +Use the `{{< page-nav >}}` shortcode to add page navigation buttons to a page. These are useful for guiding users through a set of docs that should be read in sequential order. The shortcode has the following parameters: - **prev:** path of the previous document _(optional)_ - **next:** path of the next document _(optional)_ @@ -283,9 +293,7 @@ The shortcode has the following parameters: - **nextText:** override the button text linking to the next document _(optional)_ - **keepTab:** include the currently selected tab in the button link _(optional)_ -The shortcode generates buttons that link to both the previous and next documents. -By default, the shortcode uses either the `list_title` or the `title` of the linked -document, but you can use `prevText` and `nextText` to override button text. +The shortcode generates buttons that link to both the previous and next documents. By default, the shortcode uses either the `list_title` or the `title` of the linked document, but you can use `prevText` and `nextText` to override button text. ```md @@ -301,156 +309,15 @@ document, but you can use `prevText` and `nextText` to override button text. {{ page-nav prev="/path/to/prev/" next="/path/to/next" keepTab=true>}} ``` -#### Keybinds +### Generate a list of children articles -Use the `{{< keybind >}}` shortcode to include OS-specific keybindings/hotkeys. -The following parameters are available: - -- mac -- linux -- win -- all -- other - -```md - - -{{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}} - - - -{{< keybind all="Ctrl+Shift+P" >}} - - - -{{< keybind mac="⇧⌘P" linux="Ctrl+Shift+P" win="Ctrl+Shift+Alt+P" >}} -``` - -#### Diagrams - -Use the `{{< diagram >}}` shortcode to dynamically build diagrams. -The shortcode uses [mermaid.js](https://github.com/mermaid-js/mermaid) to convert -simple text into SVG diagrams. -For information about the syntax, see the [mermaid.js documentation](https://mermaid-js.github.io/mermaid/#/). - -```md -{{< diagram >}} -flowchart TB -This --> That -That --> There -{{< /diagram >}} -``` - -#### File system diagrams - -Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system -diagram using a Markdown unordered list. - -##### Example filesystem diagram shortcode - -```md -{{< filesystem-diagram >}} - -- Dir1/ -- Dir2/ - - ChildDir/ - - Child - - Child -- Dir3/ - {{< /filesystem-diagram >}} -``` - -#### High-resolution images - -In many cases, screenshots included in the docs are taken from high-resolution (retina) screens. -Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be. -The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension. -This preserves the detail of the image and renders it at a size where there should be little to no "blur" -cause by browser image resizing. - -```html -{{< img-hd src="/path/to/image" alt="Alternate title" />}} -``` - -###### Notes - -- This should only be used on screenshots takes from high-resolution screens. -- The `src` should be relative to the `static` directory. -- Image widths are limited to the width of the article content container and will scale accordingly, - even with the `width` explicitly set. - -#### Truncated content blocks - -In some cases, it may be appropriate to shorten or truncate blocks of content. -Use cases include long examples of output data or tall images. -The following shortcode truncates blocks of content and allows users to opt into -to seeing the full content block. - -```md -{{% truncate %}} -Truncated markdown content here. -{{% /truncate %}} -``` - -#### Expandable accordion content blocks - -Use the `{{% expand "Item label" %}}` shortcode to create expandable, accordion-style content blocks. -Each expandable block needs a label that users can click to expand or collapse the content block. -Pass the label as a string to the shortcode. - -```md -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} - -{{% expand "Label 3" %}} -Markdown content associated with label 3. -{{% /expand %}} -``` - -Use the optional `{{< expand-wrapper >}}` shortcode around a group of `{{% expand %}}` -shortcodes to ensure proper spacing around the expandable elements: - -```md -{{< expand-wrapper >}} -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} -{{< /expand-wrapper >}} -``` - -#### Captions - -Use the `{{% caption %}}` shortcode to add captions to images and code blocks. -Captions are styled with a smaller font size, italic text, slight transparency, -and appear directly under the previous image or code block. - -```md -{{% caption %}} -Markdown content for the caption. -{{% /caption %}} -``` - -#### Generate a list of children articles - -Section landing pages often contain just a list of articles with links and descriptions for each. -This can be cumbersome to maintain as content is added. -To automate the listing of articles in a section, use the `{{< children >}}` shortcode. +Section landing pages often contain just a list of articles with links and descriptions for each. This can be cumbersome to maintain as content is added. To automate the listing of articles in a section, use the `{{< children >}}` shortcode. ```md {{< children >}} ``` -The children shortcode can also be used to list only "section" articles (those with their own children), -or only "page" articles (those with no children) using the `show` argument: +The children shortcode can also be used to list only "section" articles (those with their own children), or only "page" articles (those with no children) using the `show` argument: ```md {{< children show="sections" >}} @@ -470,35 +337,30 @@ Use the `type` argument to specify the format of the children list. The following list types are available: -- **articles:** lists article titles as headers with the description or summary - of the article as a paragraph. Article headers link to the articles. +- **articles:** lists article titles as headers with the description or summary of the article as a paragraph. Article headers link to the articles. - **list:** lists children article links in an unordered list. -- **anchored-list:** lists anchored children article links in an unordered list - meant to act as a page navigation and link to children header. +- **anchored-list:** lists anchored children article links in an unordered list meant to act as a page navigation and link to children header. - **functions:** a special use-case designed for listing Flux functions. -##### Include a "Read more" link +#### Include a "Read more" link -To include a "Read more" link with each child summary, set `readmore=true`. -_Only the `articles` list type supports "Read more" links._ +To include a "Read more" link with each child summary, set `readmore=true`. _Only the `articles` list type supports "Read more" links._ ```md {{< children readmore=true >}} ``` -##### Include a horizontal rule +#### Include a horizontal rule -To include a horizontal rule after each child summary, set `hr=true`. -_Only the `articles` list type supports horizontal rules._ +To include a horizontal rule after each child summary, set `hr=true`. _Only the `articles` list type supports horizontal rules._ ```md {{< children hr=true >}} ``` -##### Include a code example with a child summary +#### Include a code example with a child summary -Use the `list_code_example` frontmatter to provide a code example with an article -in an articles list. +Use the `list_code_example` frontmatter to provide a code example with an article in an articles list. ````yaml list_code_example: | @@ -507,13 +369,11 @@ list_code_example: | ``` ```` -##### Organize and include native code examples +#### Organize and include native code examples -To include text from a file in `/shared/text/`, use the -`{{< get-shared-text >}}` shortcode and provide the relative path and filename. +To include text from a file in `/shared/text/`, use the `{{< get-shared-text >}}` shortcode and provide the relative path and filename. -This is useful for maintaining and referencing sample code variants in their -native file formats. +This is useful for maintaining and referencing sample code variants in their native file formats. 1. Store code examples in their native formats at `/shared/text/`. @@ -547,16 +407,13 @@ native file formats. {{% /code-tabs-wrapper %}} ```` -##### Include specific files from the same directory +#### Include specific files from the same directory + > [!Caution] -> #### Don't use for code examples +> **Don't use for code examples** > Using this and `get-shared-text` shortcodes to include code examples prevents the code from being tested. -To include the text from one file in another file in the same -directory, use the `{{< get-leaf-text >}}` shortcode. -The directory that contains both files must be a -Hugo [_Leaf Bundle_](https://gohugo.io/content-management/page-bundles/#leaf-bundles), -a directory that doesn't have any child directories. +To include the text from one file in another file in the same directory, use the `{{< get-leaf-text >}}` shortcode. The directory that contains both files must be a Hugo [_Leaf Bundle_](https://gohugo.io/content-management/page-bundles/#leaf-bundles), a directory that doesn't have any child directories. In the following example, `api` is a leaf bundle. `content` isn't. @@ -569,13 +426,13 @@ content | \_index.md ``` -###### query.pdmc +##### query.pdmc ```md # Query examples ``` -###### query.sh +##### query.sh ```md curl https://localhost:8086/query @@ -593,23 +450,19 @@ To include `query.sh` and `query.pdmc` in `api/_index.md`, use the following cod ``` ```` -Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages: -`.ad`, `.adoc`, `.asciidoc`, `.htm`, `.html`, `.markdown`, `.md`, `.mdown`, `.mmark`, `.pandoc`, `.pdc`, `.org`, or `.rst`. +Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages: `.ad`, `.adoc`, `.asciidoc`, `.htm`, `.html`, `.markdown`, `.md`, `.mdown`, `.mmark`, `.pandoc`, `.pdc`, `.org`, or `.rst`. -##### Reference a query example in children +#### Reference a query example in children -To include a query example with the children in your list, update `data/query_examples.yml` -with the example code, input, and output, and use the `list_query_example` -frontmatter to reference the corresponding example. +To include a query example with the children in your list, update `data/query_examples.yml` with the example code, input, and output, and use the `list_query_example` frontmatter to reference the corresponding example. ```yaml list_query_example: cumulative_sum ``` -##### Children frontmatter +#### Children frontmatter -Each children list `type` uses [frontmatter properties](#page-frontmatter) when generating the list of articles. -The following table shows which children types use which frontmatter properties: +Each children list `type` uses frontmatter properties when generating the list of articles. The following table shows which children types use which frontmatter properties: | Frontmatter | articles | list | functions | | :------------------- | :------: | :--: | :-------: | @@ -621,36 +474,81 @@ The following table shows which children types use which frontmatter properties: | `list_code_example` | ✓ | | | | `list_query_example` | ✓ | | | -#### Authentication token link +## Visual Elements -Use the `{{% token-link "" "%}}` shortcode to -automatically generate links to token management documentation. The shortcode -accepts two _optional_ arguments: +### Keybinds -- **descriptor**: An optional token descriptor -- **link_append**: An optional path to append to the token management link path, - `///admin/tokens/`. +Use the `{{< keybind >}}` shortcode to include OS-specific keybindings/hotkeys. The following parameters are available: + +- mac +- linux +- win +- all +- other ```md -{{% token-link "database" "resource/" %}} + - -[database token](/influxdb3/enterprise/admin/tokens/resource/) +{{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}} + + + +{{< keybind all="Ctrl+Shift+P" >}} + + + +{{< keybind mac="⇧⌘P" linux="Ctrl+Shift+P" win="Ctrl+Shift+Alt+P" >}} ``` -InfluxDB 3 Enterprise and InfluxDB 3 Core support different kinds of tokens. -The shortcode has a blacklist of token descriptors for each that will prevent -unsupported descriptors from appearing in the rendered output based on the -current product. +### Diagrams -#### Inline icons - -The `icon` shortcode allows you to inject icons in paragraph text. -It's meant to clarify references to specific elements in the InfluxDB user interface. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. +Use the `{{< diagram >}}` shortcode to dynamically build diagrams. The shortcode uses [mermaid.js](https://github.com/mermaid-js/mermaid) to convert simple text into SVG diagrams. For information about the syntax, see the [mermaid.js documentation](https://mermaid-js.github.io/mermaid/#/). +```md +{{< diagram >}} +flowchart TB +This --> That +That --> There +{{< /diagram >}} ``` + +### File system diagrams + +Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system diagram using a Markdown unordered list. + +#### Example filesystem diagram shortcode + +```md +{{< filesystem-diagram >}} + +- Dir1/ +- Dir2/ + - ChildDir/ + - Child + - Child +- Dir3/ +{{< /filesystem-diagram >}} +``` + +### High-resolution images + +In many cases, screenshots included in the docs are taken from high-resolution (retina) screens. Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be. The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension. This preserves the detail of the image and renders it at a size where there should be little to no "blur" cause by browser image resizing. + +```html +{{< img-hd src="/path/to/image" alt="Alternate title" />}} +``` + +#### Notes + +- This should only be used on screenshots takes from high-resolution screens. +- The `src` should be relative to the `static` directory. +- Image widths are limited to the width of the article content container and will scale accordingly, even with the `width` explicitly set. + +### Inline icons + +The `icon` shortcode allows you to inject icons in paragraph text. It's meant to clarify references to specific elements in the InfluxDB user interface. This shortcode supports Clockface (the UI) v2 and v3. Specify the version to use as the second argument. The default version is `v3`. + +```md {{< icon "icon-name" "v2" >}} ``` @@ -718,14 +616,11 @@ Below is a list of available icons (some are aliases): - wrench - x -#### InfluxDB UI left navigation icons +### InfluxDB UI left navigation icons -In many cases, documentation references an item in the left nav of the InfluxDB UI. -Provide a visual example of the navigation item using the `nav-icon` shortcode. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. +In many cases, documentation references an item in the left nav of the InfluxDB UI. Provide a visual example of the navigation item using the `nav-icon` shortcode. This shortcode supports Clockface (the UI) v2 and v3. Specify the version to use as the second argument. The default version is `v3`. -``` +```md {{< nav-icon "tasks" "v2" >}} ``` @@ -742,14 +637,63 @@ The following case insensitive values are supported: - settings - feedback -#### Flexbox-formatted content blocks +## Content Formatting -CSS Flexbox formatting lets you create columns in article content that adjust and -flow based on the viewable width. -In article content, this helps if you have narrow tables that could be displayed -side-by-side, rather than stacked vertically. -Use the `{{< flex >}}` shortcode to create the Flexbox wrapper. -Use the `{{% flex-content %}}` shortcode to identify each column content block. +### Truncated content blocks + +In some cases, it may be appropriate to shorten or truncate blocks of content. Use cases include long examples of output data or tall images. The following shortcode truncates blocks of content and allows users to opt into to seeing the full content block. + +```md +{{% truncate %}} +Truncated markdown content here. +{{% /truncate %}} +``` + +### Expandable accordion content blocks + +Use the `{{% expand "Item label" %}}` shortcode to create expandable, accordion-style content blocks. Each expandable block needs a label that users can click to expand or collapse the content block. Pass the label as a string to the shortcode. + +```md +{{% expand "Label 1" %}} +Markdown content associated with label 1. +{{% /expand %}} + +{{% expand "Label 2" %}} +Markdown content associated with label 2. +{{% /expand %}} + +{{% expand "Label 3" %}} +Markdown content associated with label 3. +{{% /expand %}} +``` + +Use the optional `{{< expand-wrapper >}}` shortcode around a group of `{{% expand %}}` shortcodes to ensure proper spacing around the expandable elements: + +```md +{{< expand-wrapper >}} +{{% expand "Label 1" %}} +Markdown content associated with label 1. +{{% /expand %}} + +{{% expand "Label 2" %}} +Markdown content associated with label 2. +{{% /expand %}} +{{< /expand-wrapper >}} +``` + +### Captions + +Use the `{{% caption %}}` shortcode to add captions to images and code blocks. Captions are styled with a smaller font size, italic text, slight transparency, and appear directly under the previous image or code block. + +```md +{{% caption %}} +Markdown content for the caption. +{{% /caption %}} +``` + +### Flexbox-formatted content blocks + +CSS Flexbox formatting lets you create columns in article content that adjust and flow based on the viewable width. In article content, this helps if you have narrow tables that could be displayed side-by-side, rather than stacked vertically. Use the `{{< flex >}}` shortcode to create the Flexbox wrapper. Use the `{{% flex-content %}}` shortcode to identify each column content block. ```md {{< flex >}} @@ -762,8 +706,7 @@ Column 2 {{< /flex >}} ``` -`{{% flex-content %}}` has an optional width argument that determines the maximum -width of the column. +`{{% flex-content %}}` has an optional width argument that determines the maximum width of the column. ```md {{% flex-content "half" %}} @@ -775,32 +718,136 @@ The following options are available: - third - quarter -#### Tooltips +### Tooltips -Use the `{{< tooltip >}}` shortcode to add tooltips to text. -The **first** argument is the text shown in the tooltip. -The **second** argument is the highlighted text that triggers the tooltip. +Use the `{{< tooltip >}}` shortcode to add tooltips to text. The **first** argument is the text shown in the tooltip. The **second** argument is the highlighted text that triggers the tooltip. ```md I like {{< tooltip "Butterflies are awesome!" "butterflies" >}}. ``` -The rendered output is "I like butterflies" with "butterflies" highlighted. -When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!" +The rendered output is "I like butterflies" with "butterflies" highlighted. When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!" -#### Flux sample data tables +### All-Caps -The Flux `sample` package provides basic sample datasets that can be used to -illustrate how Flux functions work. To quickly display one of the raw sample -datasets, use the `{{% flux/sample %}}` shortcode. +Clockface v3 introduces many buttons with text formatted as all-caps. Use the `{{< caps >}}` shortcode to format text to match those buttons. -The `flux/sample` shortcode has the following arguments that can be specified -by name or positionally. +```md +Click {{< caps >}}Add Data{{< /caps >}} +``` -##### set +## Code Examples -Sample dataset to output. Use either `set` argument name or provide the set -as the first argument. The following sets are available: +### Authentication token link + +Use the `{{% token-link "" "%}}` shortcode to automatically generate links to token management documentation. The shortcode accepts two _optional_ arguments: + +- **descriptor**: An optional token descriptor +- **link_append**: An optional path to append to the token management link path, `///admin/tokens/`. + +```md +{{% token-link "database" "resource/" %}} + + +[database token](/influxdb3/enterprise/admin/tokens/resource/) +``` + +InfluxDB 3 Enterprise and InfluxDB 3 Core support different kinds of tokens. The shortcode has a blacklist of token descriptors for each that will prevent unsupported descriptors from appearing in the rendered output based on the current product. + +### Code callouts + +Use the `{{< code-callout >}}` shortcode to highlight and emphasize a specific piece of code (for example, a variable, placeholder, or value) in a code block. Provide the string to highlight in the code block. Include a syntax for the codeblock to properly style the called out code. + +````md +{{< code-callout "03a2bbf46249a000" >}} + +```sh +http://localhost:8086/orgs/03a2bbf46249a000/... +``` + +{{< /code-callout >}} +```` + +### Placeholders in code samples + +#### Best Practices + +- Use UPPERCASE for placeholders to make them easily identifiable +- Don't use pronouns in placeholders (e.g., "your", "this") +- List placeholders in the same order they appear in the code +- Provide clear descriptions including: + - Expected data type or format + - Purpose of the value + - Any constraints or requirements +- Mark optional placeholders as "Optional:" in their descriptions +- Placeholder key descriptions should fit the context of the code snippet +- Include examples for complex formats + +#### Writing Placeholder Descriptions + +Descriptions should follow consistent patterns: + +1. **Admin Authentication tokens**: + - Recommended: "a {{% token-link "admin" %}} for your {{< product-name >}} instance" + - Avoid: "your token", "the token", "an authorization token" +2. **Database resource tokens**: + - Recommended: "your {{% token-link "database" %}}"{{% show-in "enterprise" %}} with permissions on the specified database{{% /show-in %}} + - Avoid: "your token", "the token", "an authorization token" +3. **Database names**: + - Recommended: "the name of the database to [action]" + - Avoid: "your database", "the database name" +4. **Conditional content**: + - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions + - Example: "your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}" + +#### Common placeholders for InfluxDB 3 + +- `AUTH_TOKEN`: your {{% token-link %}} +- `DATABASE_NAME`: the database to use +- `TABLE_NAME`: Name of the table/measurement to query or write to +- `NODE_ID`: Node ID for a specific node in a cluster +- `CLUSTER_ID`: Cluster ID for a specific cluster +- `HOST`: InfluxDB server hostname or URL +- `PORT`: InfluxDB server port (typically 8181) +- `QUERY`: SQL or InfluxQL query string +- `LINE_PROTOCOL`: Line protocol data for writes +- `PLUGIN_FILENAME`: Name of plugin file to use +- `CACHE_NAME`: Name for a new or existing cache + +#### Syntax + +- `{ placeholders="PATTERN1|PATTERN2" }`: Use this code block attribute to define placeholder patterns +- `{{% code-placeholder-key %}}`: Use this shortcode to define a placeholder key +- `{{% /code-placeholder-key %}}`: Use this shortcode to close the key name + +_The `placeholders` attribute supercedes the deprecated `code-placeholders` shortcode._ + +#### Example usage + +```sh { placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" } +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --header "Authorization: Token API_TOKEN" \ + --data-binary @path/to/line-protocol.txt +``` + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to +- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) + +## Data and Samples + +### Flux sample data tables + +The Flux `sample` package provides basic sample datasets that can be used to illustrate how Flux functions work. To quickly display one of the raw sample datasets, use the `{{% flux/sample %}}` shortcode. + +The `flux/sample` shortcode has the following arguments that can be specified by name or positionally. + +#### set + +Sample dataset to output. Use either `set` argument name or provide the set as the first argument. The following sets are available: - float - int @@ -809,19 +856,15 @@ as the first argument. The following sets are available: - bool - numericBool -##### includeNull +#### includeNull -Specify whether or not to include _null_ values in the dataset. -Use either `includeNull` argument name or provide the boolean value as the second argument. +Specify whether or not to include _null_ values in the dataset. Use either `includeNull` argument name or provide the boolean value as the second argument. -##### includeRange +#### includeRange -Specify whether or not to include time range columns (`_start` and `_stop`) in the dataset. -This is only recommended when showing how functions that require a time range -(such as `window()`) operate on input data. -Use either `includeRange` argument name or provide the boolean value as the third argument. +Specify whether or not to include time range columns (`_start` and `_stop`) in the dataset. This is only recommended when showing how functions that require a time range (such as `window()`) operate on input data. Use either `includeRange` argument name or provide the boolean value as the third argument. -###### Example Flux sample data shortcodes +#### Example Flux sample data shortcodes ```md @@ -843,26 +886,23 @@ Use either `includeRange` argument name or provide the boolean value as the thir {{% flux/sample "int" true true %}} ``` -#### Duplicate OSS content in Cloud +## Content Management -Docs for InfluxDB OSS and InfluxDB Cloud share a majority of content. -To prevent duplication of content between versions, use the following shortcodes: +### Duplicate OSS content in Cloud + +Docs for InfluxDB OSS and InfluxDB Cloud share a majority of content. To prevent duplication of content between versions, use the following shortcodes: - `{{< duplicate-oss >}}` - `{{% oss-only %}}` - `{{% cloud-only %}}` -##### duplicate-oss +#### duplicate-oss -The `{{< duplicate-oss >}}` shortcode copies the page content of the file located -at the identical file path in the most recent InfluxDB OSS version. -The Cloud version of this markdown file should contain the frontmatter required -for all pages, but the body content should just be the `{{< duplicate-oss >}}` shortcode. +The `{{< duplicate-oss >}}` shortcode copies the page content of the file located at the identical file path in the most recent InfluxDB OSS version. The Cloud version of this markdown file should contain the frontmatter required for all pages, but the body content should just be the `{{< duplicate-oss >}}` shortcode. -##### oss-only +#### oss-only -Wrap content that should only appear in the OSS version of the doc with the `{{% oss-only %}}` shortcode. -Use the shortcode on both inline and content blocks: +Wrap content that should only appear in the OSS version of the doc with the `{{% oss-only %}}` shortcode. Use the shortcode on both inline and content blocks: ```md {{% oss-only %}}This is inline content that only renders in the InfluxDB OSS docs{{% /oss-only %}} @@ -901,10 +941,9 @@ This is necessary to get the first sentence/paragraph to render correctly. {{% /oss-only %}} ``` -##### cloud-only +#### cloud-only -Wrap content that should only appear in the Cloud version of the doc with the `{{% cloud-only %}}` shortcode. -Use the shortcode on both inline and content blocks: +Wrap content that should only appear in the Cloud version of the doc with the `{{% cloud-only %}}` shortcode. Use the shortcode on both inline and content blocks: ```md {{% cloud-only %}}This is inline content that only renders in the InfluxDB Cloud docs{{% /cloud-only %}} @@ -943,12 +982,9 @@ This is necessary to get the first sentence/paragraph to render correctly. {{% /cloud-only %}} ``` -#### Show or hide content blocks in shared content +### Show or hide content blocks in shared content -The `source` frontmatter lets you source page content from another file and is -used to share content across InfluxDB products. Within the shared content, you -can use the `show-in` and `hide-in` shortcodes to conditionally show or hide -content blocks based on the InfluxDB "version." Valid "versions" include: +The `source` frontmatter lets you source page content from another file and is used to share content across InfluxDB products. Within the shared content, you can use the `show-in` and `hide-in` shortcodes to conditionally show or hide content blocks based on the InfluxDB "version." Valid "versions" include: - v2 - cloud @@ -958,11 +994,9 @@ content blocks based on the InfluxDB "version." Valid "versions" include: - core - enterprise -##### show-in +#### show-in -The `show-in` shortcode accepts a comma-delimited string of InfluxDB "versions" -to show the content block in. The version is the second level of the page -path--for example: `/influxdb//...`. +The `show-in` shortcode accepts a comma-delimited string of InfluxDB "versions" to show the content block in. The version is the second level of the page path--for example: `/influxdb//...`. ```md {{% show-in "core,enterprise" %}} @@ -973,11 +1007,9 @@ documentation, but not any other InfluxDB documentation this content is shared i {{% /show-in %}} ``` -##### hide-in +#### hide-in -The `hide-in` shortcode accepts a comma-delimited string of InfluxDB "versions" -to hide the content block in. The version is the second level of the page -path--for example: `/influxdb//...`. +The `hide-in` shortcode accepts a comma-delimited string of InfluxDB "versions" to hide the content block in. The version is the second level of the page path--for example: `/influxdb//...`. ```md {{% hide-in "core,enterprise" %}} @@ -989,38 +1021,11 @@ content is shared in. {{% /hide-in %}} ``` -#### All-Caps +## Special Purpose -Clockface v3 introduces many buttons with text formatted as all-caps. -Use the `{{< caps >}}` shortcode to format text to match those buttons. +### InfluxDB University banners -```md -Click {{< caps >}}Add Data{{< /caps >}} -``` - -#### Code callouts - -Use the `{{< code-callout >}}` shortcode to highlight and emphasize a specific -piece of code (for example, a variable, placeholder, or value) in a code block. -Provide the string to highlight in the code block. -Include a syntax for the codeblock to properly style the called out code. - -````md -{{< code-callout "03a2bbf46249a000" >}} - -```sh -http://localhost:8086/orgs/03a2bbf46249a000/... -``` - -{{< /code-callout >}} -```` - -#### InfluxDB University banners - -Use the `{{< influxdbu >}}` shortcode to add an InfluxDB University banner that -points to the InfluxDB University site or a specific course. -Use the default banner template, a predefined course template, or fully customize -the content of the banner. +Use the `{{< influxdbu >}}` shortcode to add an InfluxDB University banner that points to the InfluxDB University site or a specific course. Use the default banner template, a predefined course template, or fully customize the content of the banner. ```html @@ -1030,11 +1035,10 @@ the content of the banner. {{< influxdbu "influxdb-101" >}} -{{< influxdbu title="Course title" summary="Short course summary." action="Take -the course" link="https://university.influxdata.com/" >}} +{{< influxdbu title="Course title" summary="Short course summary." action="Take the course" link="https://university.influxdata.com/" >}} ``` -##### Course templates +#### Course templates Use one of the following course templates: @@ -1042,27 +1046,20 @@ Use one of the following course templates: - telegraf-102 - flux-103 -##### Custom banner content +#### Custom banner content -Use the following shortcode parameters to customize the content of the InfluxDB -University banner: +Use the following shortcode parameters to customize the content of the InfluxDB University banner: - **title**: Course or banner title - **summary**: Short description shown under the title - **action**: Text of the button - **link**: URL the button links to -#### Reference content +### Reference content -The InfluxDB documentation is "task-based," meaning content primarily focuses on -what a user is **doing**, not what they are **using**. -However, there is a need to document tools and other things that don't necessarily -fit in the task-based style. -This is referred to as "reference content." +The InfluxDB documentation is "task-based," meaning content primarily focuses on what a user is **doing**, not what they are **using**. However, there is a need to document tools and other things that don't necessarily fit in the task-based style. This is referred to as "reference content." -Reference content is styled just as the rest of the InfluxDB documentation. -The only difference is the `menu` reference in the page's frontmatter. -When defining the menu for reference content, use the following pattern: +Reference content is styled just as the rest of the InfluxDB documentation. The only difference is the `menu` reference in the page's frontmatter. When defining the menu for reference content, use the following pattern: ```yaml # Pattern @@ -1076,18 +1073,15 @@ menu: # ... ``` -#### InfluxDB URLs +### InfluxDB URLs -When a user selects an InfluxDB product and region, example URLs in code blocks -throughout the documentation are updated to match their product and region. -InfluxDB URLs are configured in `/data/influxdb_urls.yml`. +When a user selects an InfluxDB product and region, example URLs in code blocks throughout the documentation are updated to match their product and region. InfluxDB URLs are configured in `/data/influxdb_urls.yml`. -By default, the InfluxDB URL replaced inside of code blocks is `http://localhost:8086`. -Use this URL in all code examples that should be updated with a selected provider and region. +By default, the InfluxDB URL replaced inside of code blocks is `http://localhost:8086`. Use this URL in all code examples that should be updated with a selected provider and region. For example: -```` +````md ```sh # This URL will get updated http://localhost:8086 @@ -1097,15 +1091,13 @@ http://example.com ``` ```` -If the user selects the **US West (Oregon)** region, all occurrences of `http://localhost:8086` -in code blocks will get updated to `https://us-west-2-1.aws.cloud2.influxdata.com`. +If the user selects the **US West (Oregon)** region, all occurrences of `http://localhost:8086` in code blocks will get updated to `https://us-west-2-1.aws.cloud2.influxdata.com`. -##### Exempt URLs from getting updated +#### Exempt URLs from getting updated -To exempt a code block from being updated, include the `{{< keep-url >}}` shortcode -just before the code block. +To exempt a code block from being updated, include the `{{< keep-url >}}` shortcode just before the code block. -```` +````md {{< keep-url >}} ``` // This URL won't get updated @@ -1113,28 +1105,20 @@ http://localhost:8086 ``` ```` -##### Code examples only supported in InfluxDB Cloud +#### Code examples only supported in InfluxDB Cloud -Some functionality is only supported in InfluxDB Cloud and code examples should -only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com` -as the placeholder in the code block. It will get updated on page load and when -users select a Cloud region in the URL select modal. +Some functionality is only supported in InfluxDB Cloud and code examples should only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com` as the placeholder in the code block. It will get updated on page load and when users select a Cloud region in the URL select modal. -```` +````md ```sh # This URL will get updated https://cloud2.influxdata.com ``` ```` -##### Automatically populate InfluxDB host placeholder +#### Automatically populate InfluxDB host placeholder -The InfluxDB host placeholder that gets replaced by custom domains differs -between each InfluxDB product/version. -Use the `influxdb/host` shortcode to automatically render the correct -host placeholder value for the current product. You can also pass a single -argument to specify a specific InfluxDB product to use. -Supported argument values: +The InfluxDB host placeholder that gets replaced by custom domains differs between each InfluxDB product/version. Use the `influxdb/host` shortcode to automatically render the correct host placeholder value for the current product. You can also pass a single argument to specify a specific InfluxDB product to use. Supported argument values: - oss - cloud @@ -1144,112 +1128,12 @@ Supported argument values: - core - enterprise -``` +```md {{< influxdb/host >}} {{< influxdb/host "serverless" >}} ``` -#### Placeholders in code samples +--- - ##### Best Practices - -- Use UPPERCASE for placeholders to make them easily identifiable -- Don't use pronouns in placeholders (e.g., "your", "this") -- List placeholders in the same order they appear in the code -- Provide clear descriptions including: - - Expected data type or format - - Purpose of the value - - Any constraints or requirements -- Mark optional placeholders as "Optional:" in their descriptions -- Placeholder key descriptions should fit the context of the code snippet -- Include examples for complex formats - -##### Writing Placeholder Descriptions - -Descriptions should follow consistent patterns: - -1. **Admin Authentication tokens**: - - Recommended: "a {{% token-link "admin" %}} for your {{< product-name >}} instance" - - Avoid: "your token", "the token", "an authorization token" -2. **Database resource tokens**: - - Recommended: "your {{% token-link "database" %}}"{{% show-in "enterprise" %}} with permissions on the specified database{{% /show-in %}} - - Avoid: "your token", "the token", "an authorization token" -3. **Database names**: - - Recommended: "the name of the database to [action]" - - Avoid: "your database", "the database name" -4. **Conditional content**: - - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions - - Example: "your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}" - -##### Common placeholders for InfluxDB 3 - -- `AUTH_TOKEN`: your {{% token-link %}} -- `DATABASE_NAME`: the database to use -- `TABLE_NAME`: Name of the table/measurement to query or write to -- `NODE_ID`: Node ID for a specific node in a cluster -- `CLUSTER_ID`: Cluster ID for a specific cluster -- `HOST`: InfluxDB server hostname or URL -- `PORT`: InfluxDB server port (typically 8181) -- `QUERY`: SQL or InfluxQL query string -- `LINE_PROTOCOL`: Line protocol data for writes -- `PLUGIN_FILENAME`: Name of plugin file to use -- `CACHE_NAME`: Name for a new or existing cache - -##### Syntax - -- `{ placeholders="PATTERN1|PATTERN2" }`: Use this code block attribute to define placeholder patterns -- `{{% code-placeholder-key %}}`: Use this shortcode to define a placeholder key -- `{{% /code-placeholder-key %}}`: Use this shortcode to close the key name - -##### Example usage - -```sh { placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" } -curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ - --header "Authorization: Token API_TOKEN" \ - --data-binary @path/to/line-protocol.txt -``` - -Replace the following: - -- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to -- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) - -**Old (deprecated) syntax**: - -Replace the following syntax with the new `placeholders` syntax shown above. - -- `{{% code-placeholders "PLACEHOLDER1|PLACEHOLDER2" %}}` -- `{{% /code-placeholders %}}` - -## Notes and warnings - -```md -> [!Note] -> Insert note markdown content here. - -> [!Warning] -> Insert warning markdown content here. - -> [!Caution] -> Insert caution markdown content here. - -> [!Important] -> Insert important markdown content here. - -> [!Tip] -> Insert tip markdown content here. -``` - -## Required elements - -```md -{{< req >}} -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` \ No newline at end of file +**For working examples**: Test all shortcodes in [content/example.md](content/example.md) diff --git a/TESTING.md b/DOCS-TESTING.md similarity index 100% rename from TESTING.md rename to DOCS-TESTING.md diff --git a/PLATFORM_REFERENCE.md b/PLATFORM_REFERENCE.md index bc4f1f9ca..56dd14857 100644 --- a/PLATFORM_REFERENCE.md +++ b/PLATFORM_REFERENCE.md @@ -1,30 +1,65 @@ -When a user asks a question and doesn't include a product from the list below, ask them which product in the list they are using, along with the version and query language: + + -InfluxDB OSS 1.x (v1) - - Documentation: https://docs.influxdata.com/influxdb/v1/ - - Query languages: v1.8+ supports InfluxQL and Flux - - Clients: Telegraf, influx CLI, v1 client libraries -InfluxDB Enterprise (v1) - - Documentation: https://docs.influxdata.com/enterprise_influxdb/v1/ - - Query languages: v1.8+ supports InfluxQL and Flux - - Clients: Telegraf, influx CLI, v1 client libraries -InfluxDB OSS 2.x (v2) +Use the following information to help determine which InfluxDB version and product the user is asking about: + +InfluxDB OSS v2: - Documentation: https://docs.influxdata.com/influxdb/v2/ - Query languages: InfluxQL and Flux - - Clients: Telegraf, influx CLI, v2 client libraries -InfluxDB Cloud (v2, multi-tenant) + - Clients: Telegraf, influx CLI, v1/v2 client libraries + +InfluxDB OSS v1: + - Documentation: https://docs.influxdata.com/influxdb/v1/ + - Query languages: InfluxQL and Flux + - Clients: Telegraf, influx CLI, v1/v2 client libraries + +InfluxDB Enterprise: + - Documentation: https://docs.influxdata.com/enterprise_influxdb/v1.12/ + - Query languages: InfluxQL and Flux + - Clients: Telegraf, influx CLI, v1/v2 client libraries + +InfluxDB Cloud (TSM): - Documentation: https://docs.influxdata.com/influxdb/cloud/ - Query languages: InfluxQL and Flux - Clients: Telegraf, influx CLI, v2 client libraries -InfluxDB Clustered (v3, 3.0, self-managed distributed) - - Documentation: https://docs.influxdata.com/influxdb/clustered/ + +InfluxDB Cloud Serverless: + - Documentation: https://docs.influxdata.com/influxdb3/cloud-serverless/ + - Query languages: SQL and InfluxQL and Flux + - Clients: Telegraf, influxctl CLI, v3 client libraries + +InfluxDB Cloud Dedicated: + - Documentation: https://docs.influxdata.com/influxdb3/cloud-dedicated/ - Query languages: SQL and InfluxQL - Clients: Telegraf, influxctl CLI, v3 client libraries -InfluxDB Cloud Dedicated (3.0, v3, InfluxData-managed single tenant) - - Documentation: https://docs.influxdata.com/influxdb/cloud-dedicated/ + +InfluxDB Clustered: + - Documentation: https://docs.influxdata.com/influxdb3/clustered/ - Query languages: SQL and InfluxQL - Clients: Telegraf, influxctl CLI, v3 client libraries -InfluxDB Cloud Serverless (v3, 3.0, InfluxData-managed multi-tenant) - - Documentation: https://docs.influxdata.com/influxdb/clustered/ + +InfluxDB 3 Core: + - Documentation: https://docs.influxdata.com/influxdb3/core/ - Query languages: SQL and InfluxQL - - Clients: Telegraf, influx CLI, v3 client libraries + - Clients: Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer + +InfluxDB 3 Enterprise: + - Documentation: https://docs.influxdata.com/influxdb3/enterprise/ + - Query languages: SQL and InfluxQL + - Clients: Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer + +InfluxDB 3 Explorer: + - Documentation: https://docs.influxdata.com/influxdb3/explorer/ + +Telegraf: + - Documentation: https://docs.influxdata.com/telegraf/v1.36/ + +Chronograf: + - Documentation: https://docs.influxdata.com/chronograf/v1.10/ + +Kapacitor: + - Documentation: https://docs.influxdata.com/kapacitor/v1.8/ + +Flux: + - Documentation: https://docs.influxdata.com/flux/v0.x/ + diff --git a/README.md b/README.md index ab99436fd..3774360e2 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,27 @@ This repository contains the InfluxDB 2.x documentation published at [docs.influ ## Contributing We welcome and encourage community contributions. -For information about contributing to the InfluxData documentation, see [Contribution guidelines](CONTRIBUTING.md). +For information about contributing to the InfluxData documentation, see [Contribution guidelines](DOCS-CONTRIBUTING.md). ## Testing -For information about testing the documentation, including code block testing, link validation, and style linting, see [Testing guide](TESTING.md). +For information about testing the documentation, including code block testing, link validation, and style linting, see [Testing guide](DOCS-TESTING.md). + +## Documentation + +Comprehensive reference documentation for contributors: + +- **[Contributing Guide](DOCS-CONTRIBUTING.md)** - Workflow and contribution guidelines +- **[Shortcodes Reference](DOCS-SHORTCODES.md)** - Complete Hugo shortcode documentation + - [Working examples](content/example.md) - Test shortcodes in the browser +- **[Frontmatter Reference](DOCS-FRONTMATTER.md)** - Complete page metadata documentation +- **[Testing Guide](DOCS-TESTING.md)** - Testing procedures and requirements +- **[API Documentation](api-docs/README.md)** - API reference generation + +### Quick Links +- [Style guidelines](DOCS-CONTRIBUTING.md#style-guidelines) +- [Commit guidelines](DOCS-CONTRIBUTING.md#commit-guidelines) +- [Code block testing](DOCS-TESTING.md#code-block-testing) ## Reporting a Vulnerability @@ -42,7 +58,7 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report- yarn install ``` - _**Note:** The most recent version of Hugo tested with this documentation is **0.123.8**._ + _**Note:** The most recent version of Hugo tested with this documentation is **0.149.0**._ 3. To generate the API docs, see [api-docs/README.md](api-docs/README.md). diff --git a/helper-scripts/build-agent-instructions.js b/helper-scripts/build-agent-instructions.js index 4722b25bb..fb14da591 100644 --- a/helper-scripts/build-agent-instructions.js +++ b/helper-scripts/build-agent-instructions.js @@ -10,24 +10,32 @@ import process from 'process'; import { execSync } from 'child_process'; // Get the current file path and directory -export { buildContributingInstructions }; +export { buildContributingInstructions, buildPlatformReference }; (async () => { try { - buildContributingInstructions(); + // Check if DOCS-CONTRIBUTING.md exists before trying to build instructions + const contributingPath = path.join(process.cwd(), 'DOCS-CONTRIBUTING.md'); + if (fs.existsSync(contributingPath)) { + buildContributingInstructions(); + } else { + console.log('⚠️ DOCS-CONTRIBUTING.md not found, skipping contributing instructions'); + } + + await buildPlatformReference(); } catch (error) { console.error('Error generating agent instructions:', error); } })(); -/** Build instructions from CONTRIBUTING.md - * This script reads CONTRIBUTING.md, formats it appropriately, +/** Build instructions from DOCS-CONTRIBUTING.md + * This script reads DOCS-CONTRIBUTING.md, formats it appropriately, * and saves it to .github/instructions/contributing.instructions.md * Includes optimization to reduce file size for better performance */ function buildContributingInstructions() { // Paths - const contributingPath = path.join(process.cwd(), 'CONTRIBUTING.md'); + const contributingPath = path.join(process.cwd(), 'DOCS-CONTRIBUTING.md'); const instructionsDir = path.join(process.cwd(), '.github', 'instructions'); const instructionsPath = path.join( instructionsDir, @@ -238,7 +246,7 @@ function condenseSection(content) { return ( processedLines.join('\n') + - '\n\n_See full CONTRIBUTING.md for complete details._\n\n' + '\n\n_See full DOCS-CONTRIBUTING.md for complete details._\n\n' ); } @@ -322,3 +330,209 @@ function cleanupFormatting(content) { return content; } + +/** + * Build PLATFORM_REFERENCE.md from data/products.yml + * This generates a reference document for AI agents to understand + * the different InfluxDB versions and products + */ +async function buildPlatformReference() { + const yaml = await import('js-yaml'); + + // Paths + const productsPath = path.join(process.cwd(), 'data', 'products.yml'); + const referencePath = path.join(process.cwd(), 'PLATFORM_REFERENCE.md'); + + // Read and parse the products.yml file + const productsContent = fs.readFileSync(productsPath, 'utf8'); + const products = yaml.load(productsContent); + + // Generate markdown content + let content = ` + + +Use the following information to help determine which InfluxDB version and product the user is asking about: + +`; + + // Define product order + const productOrder = [ + 'influxdb', + 'enterprise_influxdb', + 'influxdb_cloud', + 'influxdb3_cloud_serverless', + 'influxdb3_cloud_dedicated', + 'influxdb3_clustered', + 'influxdb3_core', + 'influxdb3_enterprise', + 'influxdb3_explorer', + 'telegraf', + 'chronograf', + 'kapacitor', + 'flux', + ]; + + // Process each product in order + for (const productKey of productOrder) { + const product = products[productKey]; + if (!product) continue; + + // Handle products with multiple versions (like influxdb with v1 and v2) + if (product.versions && product.versions.length > 1) { + // Generate entries for each version + for (const version of product.versions) { + const versionName = version === 'v2' ? `${product.name} OSS ${version}` : + version === 'v1' ? `${product.name} OSS ${version}` : + `${product.name} ${version}`; + + content += `${versionName}:\n`; + + // Documentation URL + const docUrl = generateDocUrlForVersion(productKey, product, version); + if (docUrl) { + content += ` - Documentation: ${docUrl}\n`; + } + + // Query languages + if (product.detector_config?.query_languages) { + const languages = Object.keys(product.detector_config.query_languages).join(' and '); + content += ` - Query languages: ${languages}\n`; + } + + // Clients/Tools + const clients = generateClientsInfo(productKey, product); + if (clients) { + content += ` - Clients: ${clients}\n`; + } + + content += '\n'; + } + } else { + // Single version products + content += `${product.name}:\n`; + + // Documentation URL + const docUrl = generateDocUrl(productKey, product); + if (docUrl) { + content += ` - Documentation: ${docUrl}\n`; + } + + // Query languages + if (product.detector_config?.query_languages) { + const languages = Object.keys(product.detector_config.query_languages).join(' and '); + content += ` - Query languages: ${languages}\n`; + } + + // Clients/Tools + const clients = generateClientsInfo(productKey, product); + if (clients) { + content += ` - Clients: ${clients}\n`; + } + + content += '\n'; + } + } + + // Write the file + fs.writeFileSync(referencePath, content); + + const fileSize = fs.statSync(referencePath).size; + const sizeInKB = (fileSize / 1024).toFixed(1); + console.log( + `✅ Generated platform reference at ${referencePath} (${sizeInKB}KB)` + ); + + // Add the file to git if it has changed + try { + const gitStatus = execSync( + `git status --porcelain "${referencePath}"` + ).toString(); + if (gitStatus.trim()) { + execSync(`git add "${referencePath}"`); + console.log('✅ Added platform reference to git staging'); + } + } catch (error) { + console.warn('⚠️ Could not add file to git:', error.message); + } +} + +/** + * Generate documentation URL for a product + */ +function generateDocUrl(productKey, product) { + const baseUrl = 'https://docs.influxdata.com'; + + switch (productKey) { + case 'influxdb': + return `${baseUrl}/influxdb/${product.latest}/`; + case 'enterprise_influxdb': + return `${baseUrl}/enterprise_influxdb/${product.latest}/`; + case 'influxdb_cloud': + return `${baseUrl}/influxdb/cloud/`; + case 'influxdb3_cloud_serverless': + return `${baseUrl}/influxdb3/cloud-serverless/`; + case 'influxdb3_cloud_dedicated': + return `${baseUrl}/influxdb3/cloud-dedicated/`; + case 'influxdb3_clustered': + return `${baseUrl}/influxdb3/clustered/`; + case 'influxdb3_core': + return `${baseUrl}/influxdb3/core/`; + case 'influxdb3_enterprise': + return `${baseUrl}/influxdb3/enterprise/`; + case 'influxdb3_explorer': + return `${baseUrl}/influxdb3/explorer/`; + case 'telegraf': + return `${baseUrl}/telegraf/${product.latest}/`; + case 'chronograf': + return `${baseUrl}/chronograf/${product.latest}/`; + case 'kapacitor': + return `${baseUrl}/kapacitor/${product.latest}/`; + case 'flux': + return `${baseUrl}/flux/${product.latest}/`; + default: + return null; + } +} + +/** + * Generate documentation URL for a specific version of a product + */ +function generateDocUrlForVersion(productKey, product, version) { + const baseUrl = 'https://docs.influxdata.com'; + + switch (productKey) { + case 'influxdb': + return `${baseUrl}/influxdb/${version}/`; + case 'enterprise_influxdb': + return `${baseUrl}/enterprise_influxdb/${version}/`; + default: + return generateDocUrl(productKey, product); + } +} + +/** + * Generate client/tool information for a product + */ +function generateClientsInfo(productKey, product) { + const v3Products = [ + 'influxdb3_core', + 'influxdb3_enterprise', + 'influxdb3_cloud_dedicated', + 'influxdb3_cloud_serverless', + 'influxdb3_clustered', + ]; + + if (productKey === 'influxdb3_core') { + return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer'; + } else if (productKey === 'influxdb3_enterprise') { + return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer'; + } else if (v3Products.includes(productKey)) { + return 'Telegraf, influxctl CLI, v3 client libraries'; + } else if (productKey === 'influxdb' || productKey === 'enterprise_influxdb') { + return 'Telegraf, influx CLI, v1/v2 client libraries'; + } else if (productKey === 'influxdb_cloud') { + return 'Telegraf, influx CLI, v2 client libraries'; + } + + return null; +} From 3a857320e8a5f5d3ddcd7826014f50e5e2e1c1ef Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 8 Oct 2025 16:15:30 -0500 Subject: [PATCH 2/7] chore(instructions): restructure agent instructions build process Remove contributing.instructions.md build logic and simplify to only build platform reference from products.yml. Update lefthook to only trigger on products.yml changes instead of CONTRIBUTING.md. --- .../instructions/contributing.instructions.md | 302 ----------------- helper-scripts/build-agent-instructions.js | 312 +----------------- lefthook.yml | 4 +- 3 files changed, 3 insertions(+), 615 deletions(-) delete mode 100644 .github/instructions/contributing.instructions.md diff --git a/.github/instructions/contributing.instructions.md b/.github/instructions/contributing.instructions.md deleted file mode 100644 index 6f2ec437d..000000000 --- a/.github/instructions/contributing.instructions.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -applyTo: "content/**/*.md, layouts/**/*.html" ---- - -# Contributing instructions for InfluxData Documentation - -## Purpose and scope - -Help document InfluxData products -by creating clear, accurate technical content with proper -code examples, frontmatter, shortcodes, and formatting. - -## Quick Start - -Ready to contribute? - -1. [Sign the InfluxData CLA](#sign-the-influxdata-cla) (for substantial changes) -2. [Fork and clone](#fork-and-clone-influxdata-documentation-repository) this repository -3. [Install dependencies](#development-environment-setup) (Node.js, Yarn, Docker) -4. Make your changes following [style guidelines](#making-changes) -5. [Test your changes](TESTING.md) (pre-commit and pre-push hooks run automatically) -6. [Submit a pull request](#submission-process) - -For detailed setup and reference information, see the sections below. - ---- - -### Sign the InfluxData CLA - -The InfluxData Contributor License Agreement (CLA) is part of the legal framework -for the open source ecosystem that protects both you and InfluxData. -To make substantial contributions to InfluxData documentation, first sign the InfluxData CLA. -What constitutes a "substantial" change is at the discretion of InfluxData documentation maintainers. - -[Sign the InfluxData CLA](https://www.influxdata.com/legal/cla/) - -_**Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA._ - -_If you're new to contributing or you're looking for an easy update, see [`docs-v2` good-first-issues](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)._ - -### Fork and clone InfluxData Documentation Repository - -[Fork this repository](https://help.github.com/articles/fork-a-repo/) and -[clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine. - ---- - -### Prerequisites - -docs-v2 automatically runs format (Markdown, JS, and CSS) linting and code block tests for staged files that you try to commit. - -For the linting and tests to run, you need to install: - -- **Node.js and Yarn**: For managing dependencies and running build scripts -- **Docker**: For running Vale linter and code block tests -- **VS Code extensions** (optional): For enhanced editing experience - - -```sh -git commit -m "" --no-verify -``` -# ... (see full CONTRIBUTING.md for complete example) -```bash -docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . -``` - -### Install Visual Studio Code extensions - - -- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments. -- Vale: shows linter errors and suggestions in the editor. -- YAML Schemas: validates frontmatter attributes. - - -_See full DOCS-CONTRIBUTING.md for complete details._ - -#### Markdown - -Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). - -_Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling._ - -#### Semantic line feeds - - -```diff --Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. -+Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. -# ... (see full CONTRIBUTING.md for complete example) -``` - -### Essential Frontmatter Reference - - -```yaml -title: # Title of the page used in the page's h1 -description: # Page description displayed in search engine results -# ... (see full CONTRIBUTING.md for complete example) -``` - - -### Shared Content - - -```yaml -source: /shared/path/to/content.md -``` - - -_See full DOCS-CONTRIBUTING.md for complete details._ - -#### Callouts (notes and warnings) - -```md -> [!Note] -> Insert note markdown content here. - -> [!Warning] -> Insert warning markdown content here. - -> [!Caution] -> Insert caution markdown content here. - -> [!Important] -> Insert important markdown content here. - -> [!Tip] -> Insert tip markdown content here. -``` - -#### Tabbed content - -```md -{{< tabs-wrapper >}} - -{{% tabs %}} -[Button text for tab 1](#) -[Button text for tab 2](#) -{{% /tabs %}} - -{{% tab-content %}} -Markdown content for tab 1. -{{% /tab-content %}} - -{{% tab-content %}} -Markdown content for tab 2. -{{% /tab-content %}} - -{{< /tabs-wrapper >}} -``` - -#### Required elements - -```md -{{< req >}} -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` - -For the complete shortcodes reference with all available shortcodes and usage examples, see **[SHORTCODES.md](SHORTCODES.md)**. - -Test shortcodes with working examples in **[content/example.md](content/example.md)**. - ---- - -### InfluxDB API documentation - -docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. The files are written in YAML and use [OpenAPI 3.0](https://swagger.io/specification/) standard. - -InfluxData uses [Redoc](https://github.com/Redocly/redoc) to build and generate the full -InfluxDB API documentation when documentation is deployed. -For more information about editing and generating InfluxDB API documentation, see the -[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). - ---- - -## Testing & Quality Assurance - - -Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: - -```sh -git commit -m "" --no-verify -``` - -### Quick Testing Reference - -```bash -# Test code blocks -yarn test:codeblocks:all - -# Test links -yarn test:links content/influxdb3/core/**/*.md - -# Run style linting -docker compose run -T vale content/**/*.md -``` - -For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. - - ---- - -## Submission Process - - -_See full DOCS-CONTRIBUTING.md for complete details._ - -### Commit Guidelines - -When creating commits, follow these guidelines: - -- Use a clear, descriptive commit message that explains the change -- Start with a type prefix: `fix()`, `feat()`, `style()`, `refactor()`, `test()`, `chore()` -- For product-specific changes, include the product in parentheses: `fix(enterprise)`, `fix(influxdb3)`, `fix(core)` -- Keep the first line under 72 characters -- Reference issues with "closes" or "fixes": `closes #123` or `closes influxdata/DAR#123` -- For multiple issues, use comma separation: `closes influxdata/DAR#517, closes influxdata/DAR#518` - -**Examples:** -``` -fix(enterprise): correct Docker environment variable name for license email -fix(influxdb3): correct Docker environment variable and compose examples for monolith -feat(telegraf): add new plugin documentation -chore(ci): update Vale configuration -``` - -### Submit a pull request - -Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). - ---- - -## Reference Documentation - -For detailed reference documentation, see: - -- **[FRONTMATTER.md](FRONTMATTER.md)** - Complete frontmatter field reference with all available options -- **[SHORTCODES.md](SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes - -#### Vale style linting configuration - -docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms. - -**Advanced Vale usage:** - -```sh -docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md -``` - - -- **Error**: -- **Warning**: General style guide rules and best practices -- **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list - -#### Configure style rules - - -_See full DOCS-CONTRIBUTING.md for complete details._ - -#### JavaScript in the documentation UI - -The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and -`assets/js/main.js` as the entry point to import modules from - - -1. In your HTML file, add a `data-component` attribute to the element that - -# ... (see full CONTRIBUTING.md for complete example) -```js - import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; - - const data = debugInspect(someData, 'Data'); - debugLog('Processing data', 'myFunction'); - - function processData() { - // Add a breakpoint that works with DevTools - debugBreak(); - - // Your existing code... - } - ``` - -3. Start Hugo in development mode--for example: - - ```bash - yarn hugo server - ``` - -4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. - -Your system uses the configuration in `launch.json` to launch the site in Chrome -and attach the debugger to the Developer Tools console. - -Make sure to remove the debug statements before merging your changes. -The debug helpers are designed to be used in development and should not be used in production. - -_See full DOCS-CONTRIBUTING.md for complete details._ - diff --git a/helper-scripts/build-agent-instructions.js b/helper-scripts/build-agent-instructions.js index fb14da591..1804e48e3 100644 --- a/helper-scripts/build-agent-instructions.js +++ b/helper-scripts/build-agent-instructions.js @@ -10,326 +10,16 @@ import process from 'process'; import { execSync } from 'child_process'; // Get the current file path and directory -export { buildContributingInstructions, buildPlatformReference }; +export { buildPlatformReference }; (async () => { try { - // Check if DOCS-CONTRIBUTING.md exists before trying to build instructions - const contributingPath = path.join(process.cwd(), 'DOCS-CONTRIBUTING.md'); - if (fs.existsSync(contributingPath)) { - buildContributingInstructions(); - } else { - console.log('⚠️ DOCS-CONTRIBUTING.md not found, skipping contributing instructions'); - } - await buildPlatformReference(); } catch (error) { console.error('Error generating agent instructions:', error); } })(); -/** Build instructions from DOCS-CONTRIBUTING.md - * This script reads DOCS-CONTRIBUTING.md, formats it appropriately, - * and saves it to .github/instructions/contributing.instructions.md - * Includes optimization to reduce file size for better performance - */ -function buildContributingInstructions() { - // Paths - const contributingPath = path.join(process.cwd(), 'DOCS-CONTRIBUTING.md'); - const instructionsDir = path.join(process.cwd(), '.github', 'instructions'); - const instructionsPath = path.join( - instructionsDir, - 'contributing.instructions.md' - ); - - // Ensure the instructions directory exists - if (!fs.existsSync(instructionsDir)) { - fs.mkdirSync(instructionsDir, { recursive: true }); - } - - // Read the CONTRIBUTING.md file - let content = fs.readFileSync(contributingPath, 'utf8'); - - // Optimize content by removing less critical sections for Copilot - content = optimizeContentForContext(content); - - // Format the content for Copilot instructions with applyTo attribute - content = `--- -applyTo: "content/**/*.md, layouts/**/*.html" ---- - -# Contributing instructions for InfluxData Documentation - -## Purpose and scope - -Help document InfluxData products -by creating clear, accurate technical content with proper -code examples, frontmatter, shortcodes, and formatting. - -${content}`; - - // Write the formatted content to the instructions file - fs.writeFileSync(instructionsPath, content); - - const fileSize = fs.statSync(instructionsPath).size; - const sizeInKB = (fileSize / 1024).toFixed(1); - console.log( - `✅ Generated instructions at ${instructionsPath} (${sizeInKB}KB)` - ); - - if (fileSize > 40000) { - console.warn( - `⚠️ Instructions file is large (${sizeInKB}KB > 40KB) and may ` + - `impact performance` - ); - } - - // Add the file to git if it has changed - try { - const gitStatus = execSync( - `git status --porcelain "${instructionsPath}"` - ).toString(); - if (gitStatus.trim()) { - execSync(`git add "${instructionsPath}"`); - console.log('✅ Added instructions file to git staging'); - } - - // Also add any extracted files to git - const extractedFiles = execSync( - `git status --porcelain "${instructionsDir}/*.md"` - ).toString(); - if (extractedFiles.trim()) { - execSync(`git add "${instructionsDir}"/*.md`); - console.log('✅ Added extracted files to git staging'); - } - } catch (error) { - console.warn('⚠️ Could not add files to git:', error.message); - } -} - -/** - * Optimize content for AI agents by processing sections based on tags - * while preserving essential documentation guidance and structure - */ -function optimizeContentForContext(content) { - // Split content into sections based on agent:instruct tags - const sections = []; - const tagRegex = - //g; - - let lastIndex = 0; - let matches = [...content.matchAll(tagRegex)]; - - // Process each tagged section - for (let i = 0; i < matches.length; i++) { - const match = matches[i]; - - // Add untagged content before this tag - if (match.index > lastIndex) { - sections.push({ - type: 'untagged', - content: content.slice(lastIndex, match.index), - }); - } - - // Find the end of this section (next tag or end of content) - const nextMatch = matches[i + 1]; - const endIndex = nextMatch ? nextMatch.index : content.length; - - sections.push({ - type: match[1], - content: content.slice(match.index, endIndex), - }); - - lastIndex = endIndex; - } - - // Add any remaining untagged content - if (lastIndex < content.length) { - sections.push({ - type: 'untagged', - content: content.slice(lastIndex), - }); - } - - // Process sections based on their tags - let processedContent = ''; - - sections.forEach((section) => { - switch (section.type) { - case 'essential': - processedContent += cleanupSection(section.content); - break; - case 'condense': - processedContent += condenseSection(section.content); - break; - case 'remove': - // Skip these sections entirely - break; - default: - if (section.type.startsWith('extract ')) { - const filename = section.type.substring(8); // Remove 'extract ' prefix - processedContent += processExtractSection(section.content, filename); - } else { - processedContent += processUntaggedSection(section.content); - } - break; - case 'untagged': - processedContent += processUntaggedSection(section.content); - break; - } - }); - - // Final cleanup - return cleanupFormatting(processedContent); -} - -/** - * Clean up essential sections while preserving all content - */ -function cleanupSection(content) { - // Remove the tag comment itself - content = content.replace(/\n?/g, ''); - - // Only basic cleanup for essential sections - content = content.replace(/\n{4,}/g, '\n\n\n'); - - return content; -} - -/** - * Condense sections to key information - */ -function condenseSection(content) { - // Remove the tag comment - content = content.replace(/\n?/g, ''); - - // Extract section header - const headerMatch = content.match(/^(#+\s+.+)/m); - if (!headerMatch) return content; - - // Condense very long code examples - content = content.replace(/```[\s\S]{300,}?```/g, (match) => { - const firstLines = match.split('\n').slice(0, 3).join('\n'); - return `${firstLines}\n# ... (see full CONTRIBUTING.md for complete example)\n\`\`\``; - }); - - // Keep first paragraph and key bullet points - const lines = content.split('\n'); - const processedLines = []; - let inCodeBlock = false; - let paragraphCount = 0; - - for (const line of lines) { - if (line.startsWith('```')) { - inCodeBlock = !inCodeBlock; - processedLines.push(line); - } else if (inCodeBlock) { - processedLines.push(line); - } else if (line.startsWith('#')) { - processedLines.push(line); - } else if (line.trim() === '') { - processedLines.push(line); - } else if ( - line.startsWith('- ') || - line.startsWith('* ') || - line.match(/^\d+\./) - ) { - processedLines.push(line); - } else if (paragraphCount < 2 && line.trim() !== '') { - processedLines.push(line); - if (line.trim() !== '' && !line.startsWith(' ')) { - paragraphCount++; - } - } - } - - return ( - processedLines.join('\n') + - '\n\n_See full DOCS-CONTRIBUTING.md for complete details._\n\n' - ); -} - -/** - * Process extract sections to create separate files and placeholders - */ -function processExtractSection(content, filename) { - // Remove the tag comment - content = content.replace(/\n?/g, ''); - - // Extract section header - const headerMatch = content.match(/^(#+\s+.+)/m); - if (!headerMatch) return content; - - const header = headerMatch[1]; - const sectionTitle = header.replace(/^#+\s+/, ''); - - // Write the section content to a separate file - const instructionsDir = path.join(process.cwd(), '.github', 'instructions'); - const extractedFilePath = path.join(instructionsDir, filename); - - // Add frontmatter to the extracted file - const extractedContent = `--- -applyTo: "content/**/*.md, layouts/**/*.html" ---- - -${content}`; - - fs.writeFileSync(extractedFilePath, extractedContent); - - console.log(`✅ Extracted ${sectionTitle} to ${extractedFilePath}`); - - // Create a placeholder that references the extracted file - return `${header}\n\n_For the complete ${sectionTitle} reference, see ${filename}._\n\n`; -} - -/** - * Process untagged sections with moderate optimization - */ -function processUntaggedSection(content) { - // Apply moderate processing to untagged sections - - // Condense very long code examples but keep structure - content = content.replace(/```[\s\S]{400,}?```/g, (match) => { - const firstLines = match.split('\n').slice(0, 5).join('\n'); - return `${firstLines}\n# ... (content truncated)\n\`\`\``; - }); - - return content; -} - -/** - * Clean up formatting issues in the processed content - */ -function cleanupFormatting(content) { - // Fix multiple consecutive newlines - content = content.replace(/\n{4,}/g, '\n\n\n'); - - // Remove agent-instructions comments that might remain - content = content.replace(/\n?/g, ''); - - // Fix broken code blocks - content = content.replace( - /```(\w+)?\n\n+```/g, - '```$1\n# (empty code block)\n```' - ); - - // Fix broken markdown headers - content = content.replace(/^(#+)\s*$/gm, ''); - - // Fix broken list formatting - content = content.replace(/^(-|\*|\d+\.)\s*$/gm, ''); - - // Remove empty sections - content = content.replace(/^#+\s+.+\n+(?=^#+\s+)/gm, (match) => { - if (match.trim().split('\n').length <= 2) { - return ''; - } - return match; - }); - - return content; -} /** * Build PLATFORM_REFERENCE.md from data/products.yml diff --git a/lefthook.yml b/lefthook.yml index 202152a37..e528b285f 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -10,12 +10,12 @@ pre-commit: run: yarn eslint {staged_files} fail_text: "Debug helpers found! Remove debug imports and calls before committing." build-agent-instructions: - glob: "CONTRIBUTING.md" + glob: "data/products.yml" run: yarn build:agent:instructions # Report linting warnings and errors, don't output files to stdout lint-markdown: tags: lint - glob: "{CONTRIBUTING.md,content/*.md}" + glob: "{README.md,DOCS-*.md,api-docs/README.md,content/*.md}" run: | docker compose run --rm --name remark-lint remark-lint '{staged_files}' cloud-lint: From 35a679b22553041af4b191efc3d514a42e21c59b Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 8 Oct 2025 16:43:53 -0500 Subject: [PATCH 3/7] Update DOCS-CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- DOCS-CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md index f605d08f9..a505f2a97 100644 --- a/DOCS-CONTRIBUTING.md +++ b/DOCS-CONTRIBUTING.md @@ -322,8 +322,8 @@ Push your changes up to your forked repository, then [create a new pull request] For detailed reference documentation, see: -- **[FRONTMATTER.md](FRONTMATTER.md)** - Complete frontmatter field reference with all available options -- **[SHORTCODES.md](SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes +- **[DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md)** - Complete frontmatter field reference with all available options +- **[DOCS-SHORTCODES.md](DOCS-SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes ### Advanced Configuration From c97ef01053cf9b01ce9bd3344f80f7a6498de645 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 8 Oct 2025 16:46:00 -0500 Subject: [PATCH 4/7] Apply suggestion from @jstirnaman --- DOCS-FRONTMATTER.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DOCS-FRONTMATTER.md b/DOCS-FRONTMATTER.md index 41017838f..cb0542fcb 100644 --- a/DOCS-FRONTMATTER.md +++ b/DOCS-FRONTMATTER.md @@ -212,7 +212,7 @@ source: /shared/influxdb3-admin/databases/_index.md When building shared content, use the `show-in` and `hide-in` shortcodes to show or hide blocks of content based on the current InfluxDB product/version. -For more information, see [show-in](/.github/instructions/shortcodes-reference.instructions.md#show-in) and [hide-in](/.github/instructions/shortcodes-reference.instructions.md#hide-in). +For more information, see [show-in](DOCS-SHORTCODES.md#show-in) and [hide-in](DOCS-SHORTCODES.md#hide-in). #### Links in shared content From bbcc6b0b8c1c9df3ffc518fa9899371b45e37abc Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 8 Oct 2025 16:50:50 -0500 Subject: [PATCH 5/7] chore(js): formatting --- helper-scripts/build-agent-instructions.js | 23 +++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/helper-scripts/build-agent-instructions.js b/helper-scripts/build-agent-instructions.js index 1804e48e3..40069a755 100644 --- a/helper-scripts/build-agent-instructions.js +++ b/helper-scripts/build-agent-instructions.js @@ -20,7 +20,6 @@ export { buildPlatformReference }; } })(); - /** * Build PLATFORM_REFERENCE.md from data/products.yml * This generates a reference document for AI agents to understand @@ -71,9 +70,12 @@ Use the following information to help determine which InfluxDB version and produ if (product.versions && product.versions.length > 1) { // Generate entries for each version for (const version of product.versions) { - const versionName = version === 'v2' ? `${product.name} OSS ${version}` : - version === 'v1' ? `${product.name} OSS ${version}` : - `${product.name} ${version}`; + const versionName = + version === 'v2' + ? `${product.name} OSS ${version}` + : version === 'v1' + ? `${product.name} OSS ${version}` + : `${product.name} ${version}`; content += `${versionName}:\n`; @@ -85,7 +87,9 @@ Use the following information to help determine which InfluxDB version and produ // Query languages if (product.detector_config?.query_languages) { - const languages = Object.keys(product.detector_config.query_languages).join(' and '); + const languages = Object.keys( + product.detector_config.query_languages + ).join(' and '); content += ` - Query languages: ${languages}\n`; } @@ -109,7 +113,9 @@ Use the following information to help determine which InfluxDB version and produ // Query languages if (product.detector_config?.query_languages) { - const languages = Object.keys(product.detector_config.query_languages).join(' and '); + const languages = Object.keys( + product.detector_config.query_languages + ).join(' and '); content += ` - Query languages: ${languages}\n`; } @@ -218,7 +224,10 @@ function generateClientsInfo(productKey, product) { return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer'; } else if (v3Products.includes(productKey)) { return 'Telegraf, influxctl CLI, v3 client libraries'; - } else if (productKey === 'influxdb' || productKey === 'enterprise_influxdb') { + } else if ( + productKey === 'influxdb' || + productKey === 'enterprise_influxdb' + ) { return 'Telegraf, influx CLI, v1/v2 client libraries'; } else if (productKey === 'influxdb_cloud') { return 'Telegraf, influx CLI, v2 client libraries'; From 9e40ccb02ac6fd546281668d46f10ac2885eb927 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 9 Oct 2025 10:48:39 -0500 Subject: [PATCH 6/7] Update .github/instructions/content.instructions.md Co-authored-by: Scott Anderson --- .github/instructions/content.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/content.instructions.md b/.github/instructions/content.instructions.md index b70f9aa77..179bea82c 100644 --- a/.github/instructions/content.instructions.md +++ b/.github/instructions/content.instructions.md @@ -15,7 +15,7 @@ Every content file needs: title: # Page h1 heading description: # SEO meta description menu: - product_version: + product_menu_key: # Identifies the Hugo menu specific to the current product name: # Navigation link text parent: # Parent menu item (if nested) weight: # Sort order (1-99, 101-199, 201-299...) From 1ea96437cbc78717aacbf1219412d9678c8b7937 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 9 Oct 2025 10:49:01 -0500 Subject: [PATCH 7/7] Update .github/instructions/content.instructions.md Co-authored-by: Scott Anderson --- .github/instructions/content.instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/instructions/content.instructions.md b/.github/instructions/content.instructions.md index 179bea82c..ce5d29ae0 100644 --- a/.github/instructions/content.instructions.md +++ b/.github/instructions/content.instructions.md @@ -45,10 +45,11 @@ weight: # Sort order (1-99, 101-199, 201-299...) ``` **Code placeholders**: -```markdown +~~~markdown ```sh { placeholders="DATABASE_NAME|API_TOKEN" } curl -X POST https://cloud2.influxdata.com/api/v2/write?bucket=DATABASE_NAME ``` +~~~ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your database name