DOCS-CONTRIBUTING.md
Ready to contribute?
For detailed setup and reference information, see the sections below.
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.
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.
Fork this repository and clone it to your local machine.
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:
_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:
git commit -m "<COMMIT_MESSAGE>" --no-verify
To install dependencies listed in package.json:
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:
The .ci/vale/vale.sh wrapper runs Vale for style linting.
It uses a local vale binary if available, otherwise falls back to Docker.
brew install vale (or see Vale installation guide)Docker is required for code block tests (compose.yaml and Dockerfile.pytest).
docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .
To run the documentation locally, follow the instructions provided in the README.
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:
//SOURCE) and makes links and filepaths clickable in comments.Content follows Google Developer Documentation Style Guide and YouTube API documentation patterns with a few InfluxData-specific adaptations.
Most docs-v2 documentation content uses Markdown.
Some parts of the documentation, such as ./api-docs, contain Markdown within YAML and rely on additional tooling.
Use semantic line feeds. Separating each sentence with a new line makes it easy to parse diffs with the human eye.
Diff without semantic line feeds:
-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:
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.
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.
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.
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:
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.
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:
source: /shared/path/to/content.md
For complete details including examples and best practices, see the Source section in DOCS-FRONTMATTER.md.
When documenting CLI commands, you may encounter internal flags or variable names from the source code that aren't intended for end-user documentation. Use structured HTML comments to mark these flags as excluded from documentation audits.
Place the comment immediately before the Options section in CLI reference documentation:
## Options
<!--docs:exclude
--internal-flag-name: reason for exclusion
--another-internal-flag: reason for exclusion
-->
| Option | Description |
Exclude flags and options that are:
Example 1: Internal variable name
## Options
<!--docs:exclude
--database-name: internal variable, use positional <DATABASE_NAME>
-->
Example 2: Multiple exclusions
## Options
<!--docs:exclude
--table-name: internal variable, use positional <TABLE_NAME>
--trigger-name: internal variable, use positional <TRIGGER_NAME>
-->
Example 3: Hidden test flags
## Options
<!--docs:exclude
--test-mode: hidden test flag, not for production use
--serve-invocation-method: internal implementation detail
-->
Documentation audit tools should:
docs:exclude identifier--flag-name: reason> [!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.
{{< 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 >}}
{{< 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.
Test shortcodes with working examples in content/example.md.
docs-v2 includes the InfluxDB API reference documentation in the /api-docs directory. The files are written in YAML and use OpenAPI 3.0 standard.
InfluxData uses 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.
Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed:
git commit -m "<COMMIT_MESSAGE>" --no-verify
# Test code blocks
yarn test:codeblocks:all
# Test links
yarn test:links content/influxdb3/core/**/*.md
# Run style linting
.ci/vale/vale.sh content/**/*.md
For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see DOCS-TESTING.md.
When creating commits, follow these guidelines:
fix(), feat(), style(), refactor(), test(), chore()fix(enterprise), fix(influxdb3), fix(core)closes #123 or closes influxdata/DAR#123closes influxdata/DAR#517, closes influxdata/DAR#518Examples:
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
Push your changes up to your forked repository, then create a new pull request.
For detailed reference documentation, see:
Run Vale with .ci/vale/vale.sh:
.ci/vale/vale.sh content/influxdb3/core/**/*.md.ci/vale/vale.sh --config=content/influxdb/cloud-dedicated/.vale.ini content/path/.ci/vale/vale.sh --minAlertLevel=error content/path/Vale raises the following alert levels:
<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.
<!-- agent:instruct: condense -->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:
In your HTML file, add a data-component attribute to the element that
should be initialized by your JavaScript code. For example:
<div data-component="my-component"></div>
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.
In assets/js/main.js, import the module and register the component to ensure
the component is initialized on page load.
To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods:
In VS Code, select Run > Start Debugging.
Select the "Debug Docs (source maps)" configuration.
Click the play button to start the debugger.
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:
assets/js/ns-hugo-imp: namespace.js/ns-hugo-imp:/<YOUR_WORKSPACE_ROOT>/assets/js/.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.
Insert debug statements by calling the helper functions in your code--for example:
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...
}
Start Hugo in development mode--for example:
yarn hugo server
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.