Merge pull request #6455 from influxdata/jts/chore-callout-instructions
chore(instructions): restructure agent instructions for docs-v2pull/6456/head
Jason Stirnaman
GitHub
commit
9f601a53ad
|
|
@ -3,5 +3,5 @@ Closes #
|
||||||
_Describe your proposed changes here._
|
_Describe your proposed changes here._
|
||||||
|
|
||||||
- [ ] Signed the [InfluxData CLA](https://www.influxdata.com/legal/cla/)
|
- [ ] 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
|
- [ ] Rebased/mergeable
|
||||||
|
|
|
||||||
|
|
@ -28,7 +28,7 @@ Be a critical thinking partner, provide honest feedback, and identify potential
|
||||||
|
|
||||||
### Testing
|
### 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):
|
**Quick reference** (NEVER CANCEL long-running tests):
|
||||||
- **Code blocks**: `yarn test:codeblocks:all` (15-45 minutes)
|
- **Code blocks**: `yarn test:codeblocks:all` (15-45 minutes)
|
||||||
|
|
@ -56,11 +56,15 @@ yarn test:links content/example.md
|
||||||
### Content Organization
|
### Content Organization
|
||||||
|
|
||||||
- **InfluxDB 3**: `/content/influxdb3/` (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer)
|
- **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/`
|
- **Telegraf**: `/content/telegraf/v1/`
|
||||||
- **Other tools**: `/content/kapacitor/`, `/content/chronograf/`, `/content/flux/`
|
- **Kapacitor**: `/content/kapacitor/`
|
||||||
- **Shared content**: `/content/shared/`
|
- **Chronograf**: `/content/chronograf/`
|
||||||
|
- **Flux**: `/content/flux/`
|
||||||
- **Examples**: `/content/example.md` (comprehensive shortcode reference)
|
- **Examples**: `/content/example.md` (comprehensive shortcode reference)
|
||||||
|
- **Shared content**: `/content/shared/`
|
||||||
|
|
||||||
### Key Files
|
### Key Files
|
||||||
|
|
||||||
|
|
@ -71,8 +75,8 @@ yarn test:links content/example.md
|
||||||
|
|
||||||
## Technology Stack
|
## Technology Stack
|
||||||
|
|
||||||
- **Hugo** (0.148.2+ extended) - Static site generator
|
- **Hugo** - Static site generator
|
||||||
- **Node.js/Yarn** (20.19.4+/1.22.22+) - Package management
|
- **Node.js/Yarn** - Package management
|
||||||
- **Testing**: Pytest, Cypress, link-checker, Vale
|
- **Testing**: Pytest, Cypress, link-checker, Vale
|
||||||
- **Tools**: Docker, ESLint, Prettier, Lefthook
|
- **Tools**: Docker, ESLint, Prettier, Lefthook
|
||||||
|
|
||||||
|
|
@ -109,9 +113,12 @@ npx hugo --quiet
|
||||||
### Writing Documentation
|
### Writing Documentation
|
||||||
|
|
||||||
For detailed guidelines, see:
|
For detailed guidelines, see:
|
||||||
- **Frontmatter**: `.github/instructions/content.instructions.md`
|
- **Workflow**: [DOCS-CONTRIBUTING.md](../DOCS-CONTRIBUTING.md) - Contribution guidelines and workflow
|
||||||
- **Shortcodes**: `.github/instructions/shortcodes-reference.instructions.md`
|
- **Shortcodes**: [DOCS-SHORTCODES.md](../DOCS-SHORTCODES.md) - Complete shortcode reference
|
||||||
- **Contributing**: `.github/instructions/contributing.instructions.md`
|
- **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
|
### Code Examples
|
||||||
|
|
||||||
|
|
@ -144,12 +151,11 @@ For detailed information on specific topics:
|
||||||
|
|
||||||
| Topic | File | Description |
|
| Topic | File | Description |
|
||||||
|-------|------|-------------|
|
|-------|------|-------------|
|
||||||
| **Content** | [content.instructions.md](instructions/content.instructions.md) | Frontmatter, metadata, page structure |
|
| **Content** | [content.instructions.md](instructions/content.instructions.md) | Lightweight pointer to frontmatter and shortcode references |
|
||||||
| **Shortcodes** | [shortcodes-reference.instructions.md](instructions/shortcodes-reference.instructions.md) | All available Hugo shortcodes |
|
| **Layouts** | [layouts.instructions.md](instructions/layouts.instructions.md) | Shortcode implementation patterns and testing |
|
||||||
| **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 workflow |
|
||||||
| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec management |
|
| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | TypeScript/JavaScript and CSS development |
|
||||||
| **Testing** | [TESTING.md](../TESTING.md) | Comprehensive testing procedures |
|
| **Testing** | [DOCS-TESTING.md](../DOCS-TESTING.md) | Comprehensive testing procedures |
|
||||||
| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | JavaScript and CSS development |
|
|
||||||
|
|
||||||
## Important Notes
|
## Important Notes
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
API documentation uses OpenAPI specifications and Redoc, not Hugo shortcodes.
|
||||||
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).
|
|
||||||
|
|
||||||
## Generate API documentation locally
|
## Workflow
|
||||||
|
|
||||||
From `api-docs` directory:
|
1. Edit YAML files in `/api-docs/`
|
||||||
|
2. Generate HTML documentation locally:
|
||||||
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.
|
|
||||||
```sh
|
```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
|
- `ref.yml`: Main API specification
|
||||||
generate-api-docs.sh
|
- `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).
|
||||||
|
|
|
||||||
|
|
@ -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
|
## TypeScript Configuration
|
||||||
`assets/js/main.js` as the entry point to import modules from.
|
|
||||||
|
|
||||||
|
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
|
## Component Pattern
|
||||||
encapsulate the UI feature and use the JavaScript module.
|
|
||||||
|
|
||||||
|
1. Add `data-component` attribute to HTML element:
|
||||||
```html
|
```html
|
||||||
<div data-component="my-component"></div>
|
<div data-component="my-component"></div>
|
||||||
```
|
```
|
||||||
|
|
||||||
2. In `assets/js/main.js`, import your module and initialize it on the element.
|
2. Create component module in `assets/js/components/`:
|
||||||
|
```typescript
|
||||||
## Debugging helpers for JavaScript
|
// assets/js/components/my-component.ts
|
||||||
|
export function initMyComponent(element: HTMLElement): void {
|
||||||
In your JavaScript module, import the debug helpers from `assets/js/utils/debug-helpers.js`.
|
// Component logic
|
||||||
|
|
||||||
```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...
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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:
|
registerComponent('my-component', initMyComponent);
|
||||||
|
|
||||||
```bash
|
|
||||||
yarn hugo server
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
### Method 1: Chrome DevTools with Source Maps
|
||||||
and attach the debugger to the Developer Tools console.
|
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.
|
### Method 2: Debug Helpers
|
||||||
The debug helpers are designed to be used in development and should not be used in production.
|
```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).
|
||||||
|
|
|
||||||
|
|
@ -1,243 +1,74 @@
|
||||||
---
|
---
|
||||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
applyTo: "content/**/*.md"
|
||||||
---
|
---
|
||||||
|
|
||||||
## Frontmatter Requirements
|
# Content File Guidelines
|
||||||
|
|
||||||
Documentation pages include frontmatter which specifies information about the page.
|
**Frontmatter reference**: [DOCS-FRONTMATTER.md](../../DOCS-FRONTMATTER.md)
|
||||||
Include proper frontmatter for pages in `/content/`, except `/content/shared/`.
|
**Shortcodes reference**: [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md)
|
||||||
Frontmatter populates variables in page templates and the site's navigation menu.
|
**Working examples**: [content/example.md](../../content/example.md)
|
||||||
|
|
||||||
|
## Required for All Content Files
|
||||||
|
|
||||||
|
Every content file needs:
|
||||||
```yaml
|
```yaml
|
||||||
title: # Page title (h1)
|
title: # Page h1 heading
|
||||||
seotitle: # SEO title
|
description: # SEO meta description
|
||||||
description: # SEO description
|
|
||||||
menu:
|
menu:
|
||||||
product_version:
|
product_menu_key: # Identifies the Hugo menu specific to the current product
|
||||||
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 <head> 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)
|
- Use semantic line feeds (one sentence per line)
|
||||||
- Format code examples to fit within 80 characters
|
- Test all code examples before committing
|
||||||
- Use long options in command line examples (`--option` instead of `-o`)
|
- Use appropriate shortcodes for UI elements
|
||||||
- Use GitHub callout syntax for notes and warnings
|
|
||||||
- Image naming: `project/version-context-description.png`
|
## 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).
|
||||||
|
|
|
||||||
|
|
@ -1,178 +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? 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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 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 "<COMMIT_MESSAGE>" --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 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)
|
|
||||||
```
|
|
||||||
|
|
||||||
See content.instructions.md for more details.
|
|
||||||
|
|
||||||
### 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`.
|
|
||||||
|
|
||||||
See api-docs.instructions.md for more details.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
git commit -m "<COMMIT_MESSAGE>" --no-verify
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Reference Sections
|
|
||||||
|
|
||||||
_See full CONTRIBUTING.md for complete details._
|
|
||||||
|
|
||||||
### Complete Frontmatter Reference
|
|
||||||
|
|
||||||
_For the complete Complete Frontmatter Reference reference, see content.instructions.md._
|
|
||||||
|
|
||||||
### Complete Shortcodes Reference
|
|
||||||
|
|
||||||
_For the complete Complete Shortcodes Reference reference, see content.instructions.md._
|
|
||||||
|
|
||||||
#### 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 CONTRIBUTING.md for complete details._
|
|
||||||
|
|
@ -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
|
||||||
|
<!-- layouts/shortcodes/example.html -->
|
||||||
|
{{ $param := .Get 0 }}
|
||||||
|
{{ $namedParam := .Get "name" }}
|
||||||
|
|
||||||
|
<div class="example">
|
||||||
|
{{ .Inner | markdownify }}
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
@ -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.
|
|
||||||
|
|
||||||
|
|
@ -17,11 +17,11 @@ See @README.md
|
||||||
See @.github/copilot-instructions.md for style guidelines and
|
See @.github/copilot-instructions.md for style guidelines and
|
||||||
product-specific documentation paths and URLs managed in this project.
|
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
|
documentation contributing guidelines, such as style and
|
||||||
formatting, and commonly used shortcodes.
|
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.
|
testing, link validation, style linting, and advanced testing procedures.
|
||||||
|
|
||||||
See @api-docs/README.md for information about the API reference documentation, how to
|
See @api-docs/README.md for information about the API reference documentation, how to
|
||||||
|
|
|
||||||
1807
CONTRIBUTING.md
1807
CONTRIBUTING.md
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,442 @@
|
||||||
|
# Contributing to InfluxData Documentation
|
||||||
|
|
||||||
|
<!-- agent:instruct: essential -->
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- agent:instruct: condense -->
|
||||||
|
## 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 "<COMMIT_MESSAGE>" --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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- agent:instruct: condense -->
|
||||||
|
## 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).
|
||||||
|
|
||||||
|
<!-- agent:instruct: essential -->
|
||||||
|
### 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 "<COMMIT_MESSAGE>" --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)**.
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- agent:instruct: condense -->
|
||||||
|
## Submission Process
|
||||||
|
|
||||||
|
<!-- agent:instruct: essential -->
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
- **[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
|
||||||
|
|
||||||
|
<!-- agent:instruct: condense -->
|
||||||
|
### 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
|
||||||
|
|
||||||
|
`<docs-v2>/.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).
|
||||||
|
|
||||||
|
<!-- agent:instruct: condense -->
|
||||||
|
#### 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
|
||||||
|
<div data-component="my-component"></div>
|
||||||
|
```
|
||||||
|
|
||||||
|
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:/<YOUR_WORKSPACE_ROOT>/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.
|
||||||
|
|
@ -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 <head> 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](DOCS-SHORTCODES.md#show-in) and [hide-in](DOCS-SHORTCODES.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
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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:
|
<!-- This file is auto-generated from data/products.yml. Do not edit directly. -->
|
||||||
|
<!-- Run 'npm run build:agent:instructions' to regenerate this file. -->
|
||||||
|
|
||||||
InfluxDB OSS 1.x (v1)
|
Use the following information to help determine which InfluxDB version and product the user is asking about:
|
||||||
- Documentation: https://docs.influxdata.com/influxdb/v1/
|
|
||||||
- Query languages: v1.8+ supports InfluxQL and Flux
|
InfluxDB OSS v2:
|
||||||
- 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)
|
|
||||||
- Documentation: https://docs.influxdata.com/influxdb/v2/
|
- Documentation: https://docs.influxdata.com/influxdb/v2/
|
||||||
- Query languages: InfluxQL and Flux
|
- Query languages: InfluxQL and Flux
|
||||||
- Clients: Telegraf, influx CLI, v2 client libraries
|
- Clients: Telegraf, influx CLI, v1/v2 client libraries
|
||||||
InfluxDB Cloud (v2, multi-tenant)
|
|
||||||
|
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/
|
- Documentation: https://docs.influxdata.com/influxdb/cloud/
|
||||||
- Query languages: InfluxQL and Flux
|
- Query languages: InfluxQL and Flux
|
||||||
- Clients: Telegraf, influx CLI, v2 client libraries
|
- 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
|
- Query languages: SQL and InfluxQL
|
||||||
- Clients: Telegraf, influxctl CLI, v3 client libraries
|
- 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
|
- Query languages: SQL and InfluxQL
|
||||||
- Clients: Telegraf, influxctl CLI, v3 client libraries
|
- 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
|
- 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/
|
||||||
|
|
||||||
|
|
|
||||||
22
README.md
22
README.md
|
|
@ -9,11 +9,27 @@ This repository contains the InfluxDB 2.x documentation published at [docs.influ
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
We welcome and encourage community contributions.
|
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
|
## 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
|
## Reporting a Vulnerability
|
||||||
|
|
||||||
|
|
@ -42,7 +58,7 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
|
||||||
yarn install
|
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).
|
3. To generate the API docs, see [api-docs/README.md](api-docs/README.md).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -10,315 +10,228 @@ import process from 'process';
|
||||||
import { execSync } from 'child_process';
|
import { execSync } from 'child_process';
|
||||||
|
|
||||||
// Get the current file path and directory
|
// Get the current file path and directory
|
||||||
export { buildContributingInstructions };
|
export { buildPlatformReference };
|
||||||
|
|
||||||
(async () => {
|
(async () => {
|
||||||
try {
|
try {
|
||||||
buildContributingInstructions();
|
await buildPlatformReference();
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
console.error('Error generating agent instructions:', error);
|
console.error('Error generating agent instructions:', error);
|
||||||
}
|
}
|
||||||
})();
|
})();
|
||||||
|
|
||||||
/** Build instructions from CONTRIBUTING.md
|
/**
|
||||||
* This script reads CONTRIBUTING.md, formats it appropriately,
|
* Build PLATFORM_REFERENCE.md from data/products.yml
|
||||||
* and saves it to .github/instructions/contributing.instructions.md
|
* This generates a reference document for AI agents to understand
|
||||||
* Includes optimization to reduce file size for better performance
|
* the different InfluxDB versions and products
|
||||||
*/
|
*/
|
||||||
function buildContributingInstructions() {
|
async function buildPlatformReference() {
|
||||||
// Paths
|
const yaml = await import('js-yaml');
|
||||||
const contributingPath = path.join(process.cwd(), 'CONTRIBUTING.md');
|
|
||||||
const instructionsDir = path.join(process.cwd(), '.github', 'instructions');
|
|
||||||
const instructionsPath = path.join(
|
|
||||||
instructionsDir,
|
|
||||||
'contributing.instructions.md'
|
|
||||||
);
|
|
||||||
|
|
||||||
// Ensure the instructions directory exists
|
// Paths
|
||||||
if (!fs.existsSync(instructionsDir)) {
|
const productsPath = path.join(process.cwd(), 'data', 'products.yml');
|
||||||
fs.mkdirSync(instructionsDir, { recursive: true });
|
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 = `<!-- This file is auto-generated from data/products.yml. Do not edit directly. -->
|
||||||
|
<!-- Run 'npm run build:agent:instructions' to regenerate this file. -->
|
||||||
|
|
||||||
|
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`;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Read the CONTRIBUTING.md file
|
// Query languages
|
||||||
let content = fs.readFileSync(contributingPath, 'utf8');
|
if (product.detector_config?.query_languages) {
|
||||||
|
const languages = Object.keys(
|
||||||
|
product.detector_config.query_languages
|
||||||
|
).join(' and ');
|
||||||
|
content += ` - Query languages: ${languages}\n`;
|
||||||
|
}
|
||||||
|
|
||||||
// Optimize content by removing less critical sections for Copilot
|
// Clients/Tools
|
||||||
content = optimizeContentForContext(content);
|
const clients = generateClientsInfo(productKey, product);
|
||||||
|
if (clients) {
|
||||||
|
content += ` - Clients: ${clients}\n`;
|
||||||
|
}
|
||||||
|
|
||||||
// Format the content for Copilot instructions with applyTo attribute
|
content += '\n';
|
||||||
content = `---
|
}
|
||||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
} else {
|
||||||
---
|
// Single version products
|
||||||
|
content += `${product.name}:\n`;
|
||||||
|
|
||||||
# Contributing instructions for InfluxData Documentation
|
// Documentation URL
|
||||||
|
const docUrl = generateDocUrl(productKey, product);
|
||||||
|
if (docUrl) {
|
||||||
|
content += ` - Documentation: ${docUrl}\n`;
|
||||||
|
}
|
||||||
|
|
||||||
## Purpose and scope
|
// Query languages
|
||||||
|
if (product.detector_config?.query_languages) {
|
||||||
|
const languages = Object.keys(
|
||||||
|
product.detector_config.query_languages
|
||||||
|
).join(' and ');
|
||||||
|
content += ` - Query languages: ${languages}\n`;
|
||||||
|
}
|
||||||
|
|
||||||
Help document InfluxData products
|
// Clients/Tools
|
||||||
by creating clear, accurate technical content with proper
|
const clients = generateClientsInfo(productKey, product);
|
||||||
code examples, frontmatter, shortcodes, and formatting.
|
if (clients) {
|
||||||
|
content += ` - Clients: ${clients}\n`;
|
||||||
|
}
|
||||||
|
|
||||||
${content}`;
|
content += '\n';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
// Write the formatted content to the instructions file
|
// Write the file
|
||||||
fs.writeFileSync(instructionsPath, content);
|
fs.writeFileSync(referencePath, content);
|
||||||
|
|
||||||
const fileSize = fs.statSync(instructionsPath).size;
|
const fileSize = fs.statSync(referencePath).size;
|
||||||
const sizeInKB = (fileSize / 1024).toFixed(1);
|
const sizeInKB = (fileSize / 1024).toFixed(1);
|
||||||
console.log(
|
console.log(
|
||||||
`✅ Generated instructions at ${instructionsPath} (${sizeInKB}KB)`
|
`✅ Generated platform reference at ${referencePath} (${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
|
// Add the file to git if it has changed
|
||||||
try {
|
try {
|
||||||
const gitStatus = execSync(
|
const gitStatus = execSync(
|
||||||
`git status --porcelain "${instructionsPath}"`
|
`git status --porcelain "${referencePath}"`
|
||||||
).toString();
|
).toString();
|
||||||
if (gitStatus.trim()) {
|
if (gitStatus.trim()) {
|
||||||
execSync(`git add "${instructionsPath}"`);
|
execSync(`git add "${referencePath}"`);
|
||||||
console.log('✅ Added instructions file to git staging');
|
console.log('✅ Added platform reference 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) {
|
} catch (error) {
|
||||||
console.warn('⚠️ Could not add files to git:', error.message);
|
console.warn('⚠️ Could not add file to git:', error.message);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Optimize content for AI agents by processing sections based on tags
|
* Generate documentation URL for a product
|
||||||
* while preserving essential documentation guidance and structure
|
|
||||||
*/
|
*/
|
||||||
function optimizeContentForContext(content) {
|
function generateDocUrl(productKey, product) {
|
||||||
// Split content into sections based on agent:instruct tags
|
const baseUrl = 'https://docs.influxdata.com';
|
||||||
const sections = [];
|
|
||||||
const tagRegex =
|
|
||||||
/<!-- agent:instruct: (essential|condense|remove|extract\s+\S+) -->/g;
|
|
||||||
|
|
||||||
let lastIndex = 0;
|
switch (productKey) {
|
||||||
let matches = [...content.matchAll(tagRegex)];
|
case 'influxdb':
|
||||||
|
return `${baseUrl}/influxdb/${product.latest}/`;
|
||||||
// Process each tagged section
|
case 'enterprise_influxdb':
|
||||||
for (let i = 0; i < matches.length; i++) {
|
return `${baseUrl}/enterprise_influxdb/${product.latest}/`;
|
||||||
const match = matches[i];
|
case 'influxdb_cloud':
|
||||||
|
return `${baseUrl}/influxdb/cloud/`;
|
||||||
// Add untagged content before this tag
|
case 'influxdb3_cloud_serverless':
|
||||||
if (match.index > lastIndex) {
|
return `${baseUrl}/influxdb3/cloud-serverless/`;
|
||||||
sections.push({
|
case 'influxdb3_cloud_dedicated':
|
||||||
type: 'untagged',
|
return `${baseUrl}/influxdb3/cloud-dedicated/`;
|
||||||
content: content.slice(lastIndex, match.index),
|
case 'influxdb3_clustered':
|
||||||
});
|
return `${baseUrl}/influxdb3/clustered/`;
|
||||||
}
|
case 'influxdb3_core':
|
||||||
|
return `${baseUrl}/influxdb3/core/`;
|
||||||
// Find the end of this section (next tag or end of content)
|
case 'influxdb3_enterprise':
|
||||||
const nextMatch = matches[i + 1];
|
return `${baseUrl}/influxdb3/enterprise/`;
|
||||||
const endIndex = nextMatch ? nextMatch.index : content.length;
|
case 'influxdb3_explorer':
|
||||||
|
return `${baseUrl}/influxdb3/explorer/`;
|
||||||
sections.push({
|
case 'telegraf':
|
||||||
type: match[1],
|
return `${baseUrl}/telegraf/${product.latest}/`;
|
||||||
content: content.slice(match.index, endIndex),
|
case 'chronograf':
|
||||||
});
|
return `${baseUrl}/chronograf/${product.latest}/`;
|
||||||
|
case 'kapacitor':
|
||||||
lastIndex = endIndex;
|
return `${baseUrl}/kapacitor/${product.latest}/`;
|
||||||
}
|
case 'flux':
|
||||||
|
return `${baseUrl}/flux/${product.latest}/`;
|
||||||
// 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:
|
default:
|
||||||
if (section.type.startsWith('extract ')) {
|
return null;
|
||||||
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
|
* Generate documentation URL for a specific version of a product
|
||||||
*/
|
*/
|
||||||
function cleanupSection(content) {
|
function generateDocUrlForVersion(productKey, product, version) {
|
||||||
// Remove the tag comment itself
|
const baseUrl = 'https://docs.influxdata.com';
|
||||||
content = content.replace(/<!-- agent:instruct: essential -->\n?/g, '');
|
|
||||||
|
|
||||||
// Only basic cleanup for essential sections
|
switch (productKey) {
|
||||||
content = content.replace(/\n{4,}/g, '\n\n\n');
|
case 'influxdb':
|
||||||
|
return `${baseUrl}/influxdb/${version}/`;
|
||||||
return content;
|
case 'enterprise_influxdb':
|
||||||
|
return `${baseUrl}/enterprise_influxdb/${version}/`;
|
||||||
|
default:
|
||||||
|
return generateDocUrl(productKey, product);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Condense sections to key information
|
* Generate client/tool information for a product
|
||||||
*/
|
*/
|
||||||
function condenseSection(content) {
|
function generateClientsInfo(productKey, product) {
|
||||||
// Remove the tag comment
|
const v3Products = [
|
||||||
content = content.replace(/<!-- agent:instruct: condense -->\n?/g, '');
|
'influxdb3_core',
|
||||||
|
'influxdb3_enterprise',
|
||||||
|
'influxdb3_cloud_dedicated',
|
||||||
|
'influxdb3_cloud_serverless',
|
||||||
|
'influxdb3_clustered',
|
||||||
|
];
|
||||||
|
|
||||||
// Extract section header
|
if (productKey === 'influxdb3_core') {
|
||||||
const headerMatch = content.match(/^(#+\s+.+)/m);
|
return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer';
|
||||||
if (!headerMatch) return content;
|
} else if (productKey === 'influxdb3_enterprise') {
|
||||||
|
return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer';
|
||||||
// Condense very long code examples
|
} else if (v3Products.includes(productKey)) {
|
||||||
content = content.replace(/```[\s\S]{300,}?```/g, (match) => {
|
return 'Telegraf, influxctl CLI, v3 client libraries';
|
||||||
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 (
|
} else if (
|
||||||
line.startsWith('- ') ||
|
productKey === 'influxdb' ||
|
||||||
line.startsWith('* ') ||
|
productKey === 'enterprise_influxdb'
|
||||||
line.match(/^\d+\./)
|
|
||||||
) {
|
) {
|
||||||
processedLines.push(line);
|
return 'Telegraf, influx CLI, v1/v2 client libraries';
|
||||||
} else if (paragraphCount < 2 && line.trim() !== '') {
|
} else if (productKey === 'influxdb_cloud') {
|
||||||
processedLines.push(line);
|
return 'Telegraf, influx CLI, v2 client libraries';
|
||||||
if (line.trim() !== '' && !line.startsWith(' ')) {
|
|
||||||
paragraphCount++;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
return (
|
return null;
|
||||||
processedLines.join('\n') +
|
|
||||||
'\n\n_See full 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(/<!-- agent:instruct: extract \S+ -->\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(/<!-- agent:instruct: \w+ -->\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;
|
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -10,12 +10,12 @@ pre-commit:
|
||||||
run: yarn eslint {staged_files}
|
run: yarn eslint {staged_files}
|
||||||
fail_text: "Debug helpers found! Remove debug imports and calls before committing."
|
fail_text: "Debug helpers found! Remove debug imports and calls before committing."
|
||||||
build-agent-instructions:
|
build-agent-instructions:
|
||||||
glob: "CONTRIBUTING.md"
|
glob: "data/products.yml"
|
||||||
run: yarn build:agent:instructions
|
run: yarn build:agent:instructions
|
||||||
# Report linting warnings and errors, don't output files to stdout
|
# Report linting warnings and errors, don't output files to stdout
|
||||||
lint-markdown:
|
lint-markdown:
|
||||||
tags: lint
|
tags: lint
|
||||||
glob: "{CONTRIBUTING.md,content/*.md}"
|
glob: "{README.md,DOCS-*.md,api-docs/README.md,content/*.md}"
|
||||||
run: |
|
run: |
|
||||||
docker compose run --rm --name remark-lint remark-lint '{staged_files}'
|
docker compose run --rm --name remark-lint remark-lint '{staged_files}'
|
||||||
cloud-lint:
|
cloud-lint:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue