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._
|
||||
|
||||
- [ ] 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
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Be a critical thinking partner, provide honest feedback, and identify potential
|
|||
|
||||
### Testing
|
||||
|
||||
For comprehensive testing procedures, see **[TESTING.md](../TESTING.md)**.
|
||||
For comprehensive testing procedures, see **[DOCS-TESTING.md](../DOCS-TESTING.md)**.
|
||||
|
||||
**Quick reference** (NEVER CANCEL long-running tests):
|
||||
- **Code blocks**: `yarn test:codeblocks:all` (15-45 minutes)
|
||||
|
|
@ -56,11 +56,15 @@ yarn test:links content/example.md
|
|||
### Content Organization
|
||||
|
||||
- **InfluxDB 3**: `/content/influxdb3/` (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer)
|
||||
- **InfluxDB v2**: `/content/influxdb/` (v2, cloud, enterprise_influxdb, v1)
|
||||
- **InfluxDB v2**: `/content/influxdb/` (v2, cloud)
|
||||
- **InfluxDB v1**: `/content/influxdb/v1`
|
||||
- **InfluxDB Enterprise (v1)**: `/content/enterprise_influxdb/v1/`
|
||||
- **Telegraf**: `/content/telegraf/v1/`
|
||||
- **Other tools**: `/content/kapacitor/`, `/content/chronograf/`, `/content/flux/`
|
||||
- **Shared content**: `/content/shared/`
|
||||
- **Kapacitor**: `/content/kapacitor/`
|
||||
- **Chronograf**: `/content/chronograf/`
|
||||
- **Flux**: `/content/flux/`
|
||||
- **Examples**: `/content/example.md` (comprehensive shortcode reference)
|
||||
- **Shared content**: `/content/shared/`
|
||||
|
||||
### Key Files
|
||||
|
||||
|
|
@ -71,8 +75,8 @@ yarn test:links content/example.md
|
|||
|
||||
## Technology Stack
|
||||
|
||||
- **Hugo** (0.148.2+ extended) - Static site generator
|
||||
- **Node.js/Yarn** (20.19.4+/1.22.22+) - Package management
|
||||
- **Hugo** - Static site generator
|
||||
- **Node.js/Yarn** - Package management
|
||||
- **Testing**: Pytest, Cypress, link-checker, Vale
|
||||
- **Tools**: Docker, ESLint, Prettier, Lefthook
|
||||
|
||||
|
|
@ -109,9 +113,12 @@ npx hugo --quiet
|
|||
### Writing Documentation
|
||||
|
||||
For detailed guidelines, see:
|
||||
- **Frontmatter**: `.github/instructions/content.instructions.md`
|
||||
- **Shortcodes**: `.github/instructions/shortcodes-reference.instructions.md`
|
||||
- **Contributing**: `.github/instructions/contributing.instructions.md`
|
||||
- **Workflow**: [DOCS-CONTRIBUTING.md](../DOCS-CONTRIBUTING.md) - Contribution guidelines and workflow
|
||||
- **Shortcodes**: [DOCS-SHORTCODES.md](../DOCS-SHORTCODES.md) - Complete shortcode reference
|
||||
- **Examples**: [content/example.md](../content/example.md) - Working examples for testing
|
||||
- **Frontmatter**: [DOCS-FRONTMATTER.md](../DOCS-FRONTMATTER.md) - Complete page metadata reference
|
||||
- **Testing**: [DOCS-TESTING.md](../DOCS-TESTING.md) - Testing procedures
|
||||
- **API Docs**: [api-docs/README.md](../api-docs/README.md) - API documentation workflow
|
||||
|
||||
### Code Examples
|
||||
|
||||
|
|
@ -144,12 +151,11 @@ For detailed information on specific topics:
|
|||
|
||||
| Topic | File | Description |
|
||||
|-------|------|-------------|
|
||||
| **Content** | [content.instructions.md](instructions/content.instructions.md) | Frontmatter, metadata, page structure |
|
||||
| **Shortcodes** | [shortcodes-reference.instructions.md](instructions/shortcodes-reference.instructions.md) | All available Hugo shortcodes |
|
||||
| **Contributing** | [contributing.instructions.md](instructions/contributing.instructions.md) | Style guide, workflow, CLA |
|
||||
| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec management |
|
||||
| **Testing** | [TESTING.md](../TESTING.md) | Comprehensive testing procedures |
|
||||
| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | JavaScript and CSS development |
|
||||
| **Content** | [content.instructions.md](instructions/content.instructions.md) | Lightweight pointer to frontmatter and shortcode references |
|
||||
| **Layouts** | [layouts.instructions.md](instructions/layouts.instructions.md) | Shortcode implementation patterns and testing |
|
||||
| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec workflow |
|
||||
| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | TypeScript/JavaScript and CSS development |
|
||||
| **Testing** | [DOCS-TESTING.md](../DOCS-TESTING.md) | Comprehensive testing procedures |
|
||||
|
||||
## Important Notes
|
||||
|
||||
|
|
|
|||
|
|
@ -1,28 +1,33 @@
|
|||
---
|
||||
applyTo: "api-docs/**/*.md, layouts/**/*.html"
|
||||
applyTo: "api-docs/**/*.md, api-docs/**/*.yml, api-docs/**/*.yaml"
|
||||
---
|
||||
|
||||
# InfluxDB API documentation
|
||||
# InfluxDB API Documentation
|
||||
|
||||
To edit the API reference documentation, edit the YAML files in `/api-docs`.
|
||||
**Complete guide**: [api-docs/README.md](../../api-docs/README.md)
|
||||
|
||||
InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full
|
||||
InfluxDB API documentation when documentation is deployed.
|
||||
Redoc generates HTML documentation using the InfluxDB `swagger.yml`.
|
||||
For more information about generating InfluxDB API documentation, see the
|
||||
[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme).
|
||||
API documentation uses OpenAPI specifications and Redoc, not Hugo shortcodes.
|
||||
|
||||
## Generate API documentation locally
|
||||
## Workflow
|
||||
|
||||
From `api-docs` directory:
|
||||
|
||||
1. Install dependencies. To generate the API documentation locally, you need to have [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/getting-started/install) installed.
|
||||
1. Edit YAML files in `/api-docs/`
|
||||
2. Generate HTML documentation locally:
|
||||
```sh
|
||||
yarn install
|
||||
cd api-docs
|
||||
sh generate-api-docs.sh
|
||||
```
|
||||
3. Test generated documentation
|
||||
4. Commit YAML changes (HTML is gitignored)
|
||||
|
||||
2. Run the script to generate the API documentation.
|
||||
## Files
|
||||
|
||||
```sh
|
||||
generate-api-docs.sh
|
||||
```
|
||||
- `ref.yml`: Main API specification
|
||||
- `content/*.yml`: Custom content overlays
|
||||
- `.redocly.yaml`: Linter and bundler configuration
|
||||
|
||||
## Tools
|
||||
|
||||
- Redoc: Generates HTML from OpenAPI specs
|
||||
- @redocly/cli: Lints and bundles specs
|
||||
|
||||
For complete documentation workflow, see [api-docs/README.md](../../api-docs/README.md).
|
||||
|
|
|
|||
|
|
@ -1,55 +1,66 @@
|
|||
---
|
||||
applyTo: "assets/**/*.md, layouts/**/*.html"
|
||||
applyTo: "assets/js/**/*.js, assets/js/**/*.ts"
|
||||
---
|
||||
|
||||
## JavaScript in the documentation UI
|
||||
# JavaScript and TypeScript Guidelines
|
||||
|
||||
The InfluxData documentation UI uses JavaScript with ES6+ syntax and
|
||||
`assets/js/main.js` as the entry point to import modules from.
|
||||
## TypeScript Configuration
|
||||
|
||||
Project uses TypeScript with ES2020 target:
|
||||
- Config: `tsconfig.json`
|
||||
- Source: `assets/js/**/*.ts`
|
||||
- Output: `dist/`
|
||||
- Build: `yarn build:ts`
|
||||
- Watch: `yarn build:ts:watch`
|
||||
|
||||
1. In your HTML file, add a `data-component` attribute to the element that will
|
||||
encapsulate the UI feature and use the JavaScript module.
|
||||
## Component Pattern
|
||||
|
||||
1. Add `data-component` attribute to HTML element:
|
||||
```html
|
||||
<div data-component="my-component"></div>
|
||||
```
|
||||
|
||||
2. In `assets/js/main.js`, import your module and initialize it on the element.
|
||||
|
||||
## Debugging helpers for JavaScript
|
||||
|
||||
In your JavaScript module, import the debug helpers from `assets/js/utils/debug-helpers.js`.
|
||||
|
||||
```js
|
||||
import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js';
|
||||
|
||||
const data = debugInspect(someData, 'Data');
|
||||
debugLog('Processing data', 'myFunction');
|
||||
|
||||
function processData() {
|
||||
// Add a breakpoint that works with DevTools
|
||||
debugBreak();
|
||||
|
||||
// Your existing code...
|
||||
2. Create component module in `assets/js/components/`:
|
||||
```typescript
|
||||
// assets/js/components/my-component.ts
|
||||
export function initMyComponent(element: HTMLElement): void {
|
||||
// Component logic
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging with VS Code
|
||||
3. Register in `assets/js/main.js`:
|
||||
```typescript
|
||||
import { initMyComponent } from './components/my-component';
|
||||
|
||||
1. Start Hugo in development mode--for example:
|
||||
|
||||
```bash
|
||||
yarn hugo server
|
||||
registerComponent('my-component', initMyComponent);
|
||||
```
|
||||
|
||||
2. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration.
|
||||
## Debugging
|
||||
|
||||
Your system uses the configuration in `launch.json` to launch the site in Chrome
|
||||
and attach the debugger to the Developer Tools console.
|
||||
### Method 1: Chrome DevTools with Source Maps
|
||||
1. VS Code: Run > Start Debugging
|
||||
2. Select "Debug Docs (source maps)"
|
||||
3. Set breakpoints in `assets/js/ns-hugo-imp:` namespace
|
||||
|
||||
Make sure to remove the debug statements before merging your changes.
|
||||
The debug helpers are designed to be used in development and should not be used in production.
|
||||
### Method 2: Debug Helpers
|
||||
```typescript
|
||||
import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers';
|
||||
|
||||
_See full CONTRIBUTING.md for complete details._
|
||||
const data = debugInspect(someData, 'Data');
|
||||
debugLog('Processing data', 'myFunction');
|
||||
debugBreak(); // Breakpoint
|
||||
```
|
||||
|
||||
Start with: `yarn hugo server`
|
||||
Debug with: VS Code "Debug JS (debug-helpers)" configuration
|
||||
|
||||
**Remove debug statements before committing.**
|
||||
|
||||
## Type Safety
|
||||
|
||||
- Use strict TypeScript mode
|
||||
- Add type annotations for parameters and returns
|
||||
- Use interfaces for complex objects
|
||||
- Enable `checkJs: false` for gradual migration
|
||||
|
||||
For complete JavaScript documentation, see [DOCS-CONTRIBUTING.md](../../DOCS-CONTRIBUTING.md#javascript-in-the-documentation-ui).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Include proper frontmatter for pages in `/content/`, except `/content/shared/`.
|
||||
Frontmatter populates variables in page templates and the site's navigation menu.
|
||||
**Frontmatter reference**: [DOCS-FRONTMATTER.md](../../DOCS-FRONTMATTER.md)
|
||||
**Shortcodes reference**: [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md)
|
||||
**Working examples**: [content/example.md](../../content/example.md)
|
||||
|
||||
## Required for All Content Files
|
||||
|
||||
Every content file needs:
|
||||
```yaml
|
||||
title: # Page title (h1)
|
||||
seotitle: # SEO title
|
||||
description: # SEO description
|
||||
title: # Page h1 heading
|
||||
description: # SEO meta description
|
||||
menu:
|
||||
product_version:
|
||||
weight: # Page order (1-99, 101-199, etc.)
|
||||
product_menu_key: # Identifies the Hugo menu specific to the current product
|
||||
name: # Navigation link text
|
||||
parent: # Parent menu item (if nested)
|
||||
weight: # Sort order (1-99, 101-199, 201-299...)
|
||||
```
|
||||
|
||||
### 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)
|
||||
- Format code examples to fit within 80 characters
|
||||
- Use long options in command line examples (`--option` instead of `-o`)
|
||||
- Use GitHub callout syntax for notes and warnings
|
||||
- Image naming: `project/version-context-description.png`
|
||||
- Test all code examples before committing
|
||||
- Use appropriate shortcodes for UI elements
|
||||
|
||||
## Most Common Shortcodes
|
||||
|
||||
**Callouts**:
|
||||
```markdown
|
||||
> [!Note]
|
||||
> [!Warning]
|
||||
> [!Caution]
|
||||
> [!Important]
|
||||
> [!Tip]
|
||||
```
|
||||
|
||||
**Required elements**:
|
||||
```markdown
|
||||
{{< req >}}
|
||||
{{< req type="key" >}}
|
||||
```
|
||||
|
||||
**Code placeholders**:
|
||||
~~~markdown
|
||||
```sh { placeholders="DATABASE_NAME|API_TOKEN" }
|
||||
curl -X POST https://cloud2.influxdata.com/api/v2/write?bucket=DATABASE_NAME
|
||||
```
|
||||
~~~
|
||||
|
||||
Replace the following:
|
||||
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your database name
|
||||
```
|
||||
|
||||
**Tabbed content**:
|
||||
```markdown
|
||||
{{< tabs-wrapper >}}
|
||||
{{% tabs %}}
|
||||
[Tab 1](#)
|
||||
[Tab 2](#)
|
||||
{{% /tabs %}}
|
||||
{{% tab-content %}}
|
||||
Content for tab 1
|
||||
{{% /tab-content %}}
|
||||
{{% tab-content %}}
|
||||
Content for tab 2
|
||||
{{% /tab-content %}}
|
||||
{{< /tabs-wrapper >}}
|
||||
```
|
||||
|
||||
For complete shortcodes reference, see [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
product-specific documentation paths and URLs managed in this project.
|
||||
|
||||
See @.github/instructions/contributing.instructions.md for essential InfluxData
|
||||
See @DOCS-CONTRIBUTING.md for essential InfluxData
|
||||
documentation contributing guidelines, such as style and
|
||||
formatting, and commonly used shortcodes.
|
||||
|
||||
See @TESTING.md for comprehensive testing information, including code block
|
||||
See @DOCS-TESTING.md for comprehensive testing information, including code block
|
||||
testing, link validation, style linting, and advanced testing procedures.
|
||||
|
||||
See @api-docs/README.md for information about the API reference documentation, how to
|
||||
|
|
|
|||
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)
|
||||
- Documentation: https://docs.influxdata.com/influxdb/v1/
|
||||
- Query languages: v1.8+ supports InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v1 client libraries
|
||||
InfluxDB Enterprise (v1)
|
||||
- Documentation: https://docs.influxdata.com/enterprise_influxdb/v1/
|
||||
- Query languages: v1.8+ supports InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v1 client libraries
|
||||
InfluxDB OSS 2.x (v2)
|
||||
Use the following information to help determine which InfluxDB version and product the user is asking about:
|
||||
|
||||
InfluxDB OSS v2:
|
||||
- Documentation: https://docs.influxdata.com/influxdb/v2/
|
||||
- Query languages: InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v2 client libraries
|
||||
InfluxDB Cloud (v2, multi-tenant)
|
||||
- Clients: Telegraf, influx CLI, v1/v2 client libraries
|
||||
|
||||
InfluxDB OSS v1:
|
||||
- Documentation: https://docs.influxdata.com/influxdb/v1/
|
||||
- Query languages: InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v1/v2 client libraries
|
||||
|
||||
InfluxDB Enterprise:
|
||||
- Documentation: https://docs.influxdata.com/enterprise_influxdb/v1.12/
|
||||
- Query languages: InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v1/v2 client libraries
|
||||
|
||||
InfluxDB Cloud (TSM):
|
||||
- Documentation: https://docs.influxdata.com/influxdb/cloud/
|
||||
- Query languages: InfluxQL and Flux
|
||||
- Clients: Telegraf, influx CLI, v2 client libraries
|
||||
InfluxDB Clustered (v3, 3.0, self-managed distributed)
|
||||
- Documentation: https://docs.influxdata.com/influxdb/clustered/
|
||||
|
||||
InfluxDB Cloud Serverless:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/cloud-serverless/
|
||||
- Query languages: SQL and InfluxQL and Flux
|
||||
- Clients: Telegraf, influxctl CLI, v3 client libraries
|
||||
|
||||
InfluxDB Cloud Dedicated:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/cloud-dedicated/
|
||||
- Query languages: SQL and InfluxQL
|
||||
- Clients: Telegraf, influxctl CLI, v3 client libraries
|
||||
InfluxDB Cloud Dedicated (3.0, v3, InfluxData-managed single tenant)
|
||||
- Documentation: https://docs.influxdata.com/influxdb/cloud-dedicated/
|
||||
|
||||
InfluxDB Clustered:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/clustered/
|
||||
- Query languages: SQL and InfluxQL
|
||||
- Clients: Telegraf, influxctl CLI, v3 client libraries
|
||||
InfluxDB Cloud Serverless (v3, 3.0, InfluxData-managed multi-tenant)
|
||||
- Documentation: https://docs.influxdata.com/influxdb/clustered/
|
||||
|
||||
InfluxDB 3 Core:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/core/
|
||||
- Query languages: SQL and InfluxQL
|
||||
- Clients: Telegraf, influx CLI, v3 client libraries
|
||||
- Clients: Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer
|
||||
|
||||
InfluxDB 3 Enterprise:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/enterprise/
|
||||
- Query languages: SQL and InfluxQL
|
||||
- Clients: Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer
|
||||
|
||||
InfluxDB 3 Explorer:
|
||||
- Documentation: https://docs.influxdata.com/influxdb3/explorer/
|
||||
|
||||
Telegraf:
|
||||
- Documentation: https://docs.influxdata.com/telegraf/v1.36/
|
||||
|
||||
Chronograf:
|
||||
- Documentation: https://docs.influxdata.com/chronograf/v1.10/
|
||||
|
||||
Kapacitor:
|
||||
- Documentation: https://docs.influxdata.com/kapacitor/v1.8/
|
||||
|
||||
Flux:
|
||||
- Documentation: https://docs.influxdata.com/flux/v0.x/
|
||||
|
||||
|
|
|
|||
22
README.md
22
README.md
|
|
@ -9,11 +9,27 @@ This repository contains the InfluxDB 2.x documentation published at [docs.influ
|
|||
## Contributing
|
||||
|
||||
We welcome and encourage community contributions.
|
||||
For information about contributing to the InfluxData documentation, see [Contribution guidelines](CONTRIBUTING.md).
|
||||
For information about contributing to the InfluxData documentation, see [Contribution guidelines](DOCS-CONTRIBUTING.md).
|
||||
|
||||
## Testing
|
||||
|
||||
For information about testing the documentation, including code block testing, link validation, and style linting, see [Testing guide](TESTING.md).
|
||||
For information about testing the documentation, including code block testing, link validation, and style linting, see [Testing guide](DOCS-TESTING.md).
|
||||
|
||||
## Documentation
|
||||
|
||||
Comprehensive reference documentation for contributors:
|
||||
|
||||
- **[Contributing Guide](DOCS-CONTRIBUTING.md)** - Workflow and contribution guidelines
|
||||
- **[Shortcodes Reference](DOCS-SHORTCODES.md)** - Complete Hugo shortcode documentation
|
||||
- [Working examples](content/example.md) - Test shortcodes in the browser
|
||||
- **[Frontmatter Reference](DOCS-FRONTMATTER.md)** - Complete page metadata documentation
|
||||
- **[Testing Guide](DOCS-TESTING.md)** - Testing procedures and requirements
|
||||
- **[API Documentation](api-docs/README.md)** - API reference generation
|
||||
|
||||
### Quick Links
|
||||
- [Style guidelines](DOCS-CONTRIBUTING.md#style-guidelines)
|
||||
- [Commit guidelines](DOCS-CONTRIBUTING.md#commit-guidelines)
|
||||
- [Code block testing](DOCS-TESTING.md#code-block-testing)
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
|
|
@ -42,7 +58,7 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
|
|||
yarn install
|
||||
```
|
||||
|
||||
_**Note:** The most recent version of Hugo tested with this documentation is **0.123.8**._
|
||||
_**Note:** The most recent version of Hugo tested with this documentation is **0.149.0**._
|
||||
|
||||
3. To generate the API docs, see [api-docs/README.md](api-docs/README.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -10,315 +10,228 @@ import process from 'process';
|
|||
import { execSync } from 'child_process';
|
||||
|
||||
// Get the current file path and directory
|
||||
export { buildContributingInstructions };
|
||||
export { buildPlatformReference };
|
||||
|
||||
(async () => {
|
||||
try {
|
||||
buildContributingInstructions();
|
||||
await buildPlatformReference();
|
||||
} catch (error) {
|
||||
console.error('Error generating agent instructions:', error);
|
||||
}
|
||||
})();
|
||||
|
||||
/** Build instructions from CONTRIBUTING.md
|
||||
* This script reads CONTRIBUTING.md, formats it appropriately,
|
||||
* and saves it to .github/instructions/contributing.instructions.md
|
||||
* Includes optimization to reduce file size for better performance
|
||||
/**
|
||||
* Build PLATFORM_REFERENCE.md from data/products.yml
|
||||
* This generates a reference document for AI agents to understand
|
||||
* the different InfluxDB versions and products
|
||||
*/
|
||||
function buildContributingInstructions() {
|
||||
// Paths
|
||||
const contributingPath = path.join(process.cwd(), 'CONTRIBUTING.md');
|
||||
const instructionsDir = path.join(process.cwd(), '.github', 'instructions');
|
||||
const instructionsPath = path.join(
|
||||
instructionsDir,
|
||||
'contributing.instructions.md'
|
||||
);
|
||||
async function buildPlatformReference() {
|
||||
const yaml = await import('js-yaml');
|
||||
|
||||
// Ensure the instructions directory exists
|
||||
if (!fs.existsSync(instructionsDir)) {
|
||||
fs.mkdirSync(instructionsDir, { recursive: true });
|
||||
// Paths
|
||||
const productsPath = path.join(process.cwd(), 'data', 'products.yml');
|
||||
const referencePath = path.join(process.cwd(), 'PLATFORM_REFERENCE.md');
|
||||
|
||||
// Read and parse the products.yml file
|
||||
const productsContent = fs.readFileSync(productsPath, 'utf8');
|
||||
const products = yaml.load(productsContent);
|
||||
|
||||
// Generate markdown content
|
||||
let content = `<!-- 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
|
||||
let content = fs.readFileSync(contributingPath, 'utf8');
|
||||
// Query languages
|
||||
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
|
||||
content = optimizeContentForContext(content);
|
||||
// Clients/Tools
|
||||
const clients = generateClientsInfo(productKey, product);
|
||||
if (clients) {
|
||||
content += ` - Clients: ${clients}\n`;
|
||||
}
|
||||
|
||||
// Format the content for Copilot instructions with applyTo attribute
|
||||
content = `---
|
||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
||||
---
|
||||
content += '\n';
|
||||
}
|
||||
} 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
|
||||
by creating clear, accurate technical content with proper
|
||||
code examples, frontmatter, shortcodes, and formatting.
|
||||
// Clients/Tools
|
||||
const clients = generateClientsInfo(productKey, product);
|
||||
if (clients) {
|
||||
content += ` - Clients: ${clients}\n`;
|
||||
}
|
||||
|
||||
${content}`;
|
||||
content += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
// Write the formatted content to the instructions file
|
||||
fs.writeFileSync(instructionsPath, content);
|
||||
// Write the file
|
||||
fs.writeFileSync(referencePath, content);
|
||||
|
||||
const fileSize = fs.statSync(instructionsPath).size;
|
||||
const fileSize = fs.statSync(referencePath).size;
|
||||
const sizeInKB = (fileSize / 1024).toFixed(1);
|
||||
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
|
||||
try {
|
||||
const gitStatus = execSync(
|
||||
`git status --porcelain "${instructionsPath}"`
|
||||
`git status --porcelain "${referencePath}"`
|
||||
).toString();
|
||||
if (gitStatus.trim()) {
|
||||
execSync(`git add "${instructionsPath}"`);
|
||||
console.log('✅ Added instructions file to git staging');
|
||||
}
|
||||
|
||||
// Also add any extracted files to git
|
||||
const extractedFiles = execSync(
|
||||
`git status --porcelain "${instructionsDir}/*.md"`
|
||||
).toString();
|
||||
if (extractedFiles.trim()) {
|
||||
execSync(`git add "${instructionsDir}"/*.md`);
|
||||
console.log('✅ Added extracted files to git staging');
|
||||
execSync(`git add "${referencePath}"`);
|
||||
console.log('✅ Added platform reference to git staging');
|
||||
}
|
||||
} 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
|
||||
* while preserving essential documentation guidance and structure
|
||||
* Generate documentation URL for a product
|
||||
*/
|
||||
function optimizeContentForContext(content) {
|
||||
// Split content into sections based on agent:instruct tags
|
||||
const sections = [];
|
||||
const tagRegex =
|
||||
/<!-- agent:instruct: (essential|condense|remove|extract\s+\S+) -->/g;
|
||||
function generateDocUrl(productKey, product) {
|
||||
const baseUrl = 'https://docs.influxdata.com';
|
||||
|
||||
let lastIndex = 0;
|
||||
let matches = [...content.matchAll(tagRegex)];
|
||||
|
||||
// Process each tagged section
|
||||
for (let i = 0; i < matches.length; i++) {
|
||||
const match = matches[i];
|
||||
|
||||
// Add untagged content before this tag
|
||||
if (match.index > lastIndex) {
|
||||
sections.push({
|
||||
type: 'untagged',
|
||||
content: content.slice(lastIndex, match.index),
|
||||
});
|
||||
}
|
||||
|
||||
// Find the end of this section (next tag or end of content)
|
||||
const nextMatch = matches[i + 1];
|
||||
const endIndex = nextMatch ? nextMatch.index : content.length;
|
||||
|
||||
sections.push({
|
||||
type: match[1],
|
||||
content: content.slice(match.index, endIndex),
|
||||
});
|
||||
|
||||
lastIndex = endIndex;
|
||||
}
|
||||
|
||||
// Add any remaining untagged content
|
||||
if (lastIndex < content.length) {
|
||||
sections.push({
|
||||
type: 'untagged',
|
||||
content: content.slice(lastIndex),
|
||||
});
|
||||
}
|
||||
|
||||
// Process sections based on their tags
|
||||
let processedContent = '';
|
||||
|
||||
sections.forEach((section) => {
|
||||
switch (section.type) {
|
||||
case 'essential':
|
||||
processedContent += cleanupSection(section.content);
|
||||
break;
|
||||
case 'condense':
|
||||
processedContent += condenseSection(section.content);
|
||||
break;
|
||||
case 'remove':
|
||||
// Skip these sections entirely
|
||||
break;
|
||||
switch (productKey) {
|
||||
case 'influxdb':
|
||||
return `${baseUrl}/influxdb/${product.latest}/`;
|
||||
case 'enterprise_influxdb':
|
||||
return `${baseUrl}/enterprise_influxdb/${product.latest}/`;
|
||||
case 'influxdb_cloud':
|
||||
return `${baseUrl}/influxdb/cloud/`;
|
||||
case 'influxdb3_cloud_serverless':
|
||||
return `${baseUrl}/influxdb3/cloud-serverless/`;
|
||||
case 'influxdb3_cloud_dedicated':
|
||||
return `${baseUrl}/influxdb3/cloud-dedicated/`;
|
||||
case 'influxdb3_clustered':
|
||||
return `${baseUrl}/influxdb3/clustered/`;
|
||||
case 'influxdb3_core':
|
||||
return `${baseUrl}/influxdb3/core/`;
|
||||
case 'influxdb3_enterprise':
|
||||
return `${baseUrl}/influxdb3/enterprise/`;
|
||||
case 'influxdb3_explorer':
|
||||
return `${baseUrl}/influxdb3/explorer/`;
|
||||
case 'telegraf':
|
||||
return `${baseUrl}/telegraf/${product.latest}/`;
|
||||
case 'chronograf':
|
||||
return `${baseUrl}/chronograf/${product.latest}/`;
|
||||
case 'kapacitor':
|
||||
return `${baseUrl}/kapacitor/${product.latest}/`;
|
||||
case 'flux':
|
||||
return `${baseUrl}/flux/${product.latest}/`;
|
||||
default:
|
||||
if (section.type.startsWith('extract ')) {
|
||||
const filename = section.type.substring(8); // Remove 'extract ' prefix
|
||||
processedContent += processExtractSection(section.content, filename);
|
||||
} else {
|
||||
processedContent += processUntaggedSection(section.content);
|
||||
return null;
|
||||
}
|
||||
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) {
|
||||
// Remove the tag comment itself
|
||||
content = content.replace(/<!-- agent:instruct: essential -->\n?/g, '');
|
||||
function generateDocUrlForVersion(productKey, product, version) {
|
||||
const baseUrl = 'https://docs.influxdata.com';
|
||||
|
||||
// Only basic cleanup for essential sections
|
||||
content = content.replace(/\n{4,}/g, '\n\n\n');
|
||||
|
||||
return content;
|
||||
switch (productKey) {
|
||||
case 'influxdb':
|
||||
return `${baseUrl}/influxdb/${version}/`;
|
||||
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) {
|
||||
// Remove the tag comment
|
||||
content = content.replace(/<!-- agent:instruct: condense -->\n?/g, '');
|
||||
function generateClientsInfo(productKey, product) {
|
||||
const v3Products = [
|
||||
'influxdb3_core',
|
||||
'influxdb3_enterprise',
|
||||
'influxdb3_cloud_dedicated',
|
||||
'influxdb3_cloud_serverless',
|
||||
'influxdb3_clustered',
|
||||
];
|
||||
|
||||
// Extract section header
|
||||
const headerMatch = content.match(/^(#+\s+.+)/m);
|
||||
if (!headerMatch) return content;
|
||||
|
||||
// Condense very long code examples
|
||||
content = content.replace(/```[\s\S]{300,}?```/g, (match) => {
|
||||
const firstLines = match.split('\n').slice(0, 3).join('\n');
|
||||
return `${firstLines}\n# ... (see full CONTRIBUTING.md for complete example)\n\`\`\``;
|
||||
});
|
||||
|
||||
// Keep first paragraph and key bullet points
|
||||
const lines = content.split('\n');
|
||||
const processedLines = [];
|
||||
let inCodeBlock = false;
|
||||
let paragraphCount = 0;
|
||||
|
||||
for (const line of lines) {
|
||||
if (line.startsWith('```')) {
|
||||
inCodeBlock = !inCodeBlock;
|
||||
processedLines.push(line);
|
||||
} else if (inCodeBlock) {
|
||||
processedLines.push(line);
|
||||
} else if (line.startsWith('#')) {
|
||||
processedLines.push(line);
|
||||
} else if (line.trim() === '') {
|
||||
processedLines.push(line);
|
||||
if (productKey === 'influxdb3_core') {
|
||||
return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer';
|
||||
} else if (productKey === 'influxdb3_enterprise') {
|
||||
return 'Telegraf, influxdb3 CLI, v3 client libraries, InfluxDB 3 Explorer';
|
||||
} else if (v3Products.includes(productKey)) {
|
||||
return 'Telegraf, influxctl CLI, v3 client libraries';
|
||||
} else if (
|
||||
line.startsWith('- ') ||
|
||||
line.startsWith('* ') ||
|
||||
line.match(/^\d+\./)
|
||||
productKey === 'influxdb' ||
|
||||
productKey === 'enterprise_influxdb'
|
||||
) {
|
||||
processedLines.push(line);
|
||||
} else if (paragraphCount < 2 && line.trim() !== '') {
|
||||
processedLines.push(line);
|
||||
if (line.trim() !== '' && !line.startsWith(' ')) {
|
||||
paragraphCount++;
|
||||
}
|
||||
}
|
||||
return 'Telegraf, influx CLI, v1/v2 client libraries';
|
||||
} else if (productKey === 'influxdb_cloud') {
|
||||
return 'Telegraf, influx CLI, v2 client libraries';
|
||||
}
|
||||
|
||||
return (
|
||||
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;
|
||||
return null;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,12 +10,12 @@ pre-commit:
|
|||
run: yarn eslint {staged_files}
|
||||
fail_text: "Debug helpers found! Remove debug imports and calls before committing."
|
||||
build-agent-instructions:
|
||||
glob: "CONTRIBUTING.md"
|
||||
glob: "data/products.yml"
|
||||
run: yarn build:agent:instructions
|
||||
# Report linting warnings and errors, don't output files to stdout
|
||||
lint-markdown:
|
||||
tags: lint
|
||||
glob: "{CONTRIBUTING.md,content/*.md}"
|
||||
glob: "{README.md,DOCS-*.md,api-docs/README.md,content/*.md}"
|
||||
run: |
|
||||
docker compose run --rm --name remark-lint remark-lint '{staged_files}'
|
||||
cloud-lint:
|
||||
|
|
|
|||
Loading…
Reference in New Issue