Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/DOCS-CONTRIBUTING.md

15 KiB
Raw Permalink Blame History

Contributing to InfluxData Documentation

Quick Start

Ready to contribute?

  1. Sign the InfluxData CLA (for substantial changes)
  2. Fork and clone this repository
  3. Install dependencies (Node.js, Yarn, Docker)
  4. Make your changes following style guidelines
  5. Test your changes (pre-commit and pre-push hooks run automatically)
  6. Submit a pull request

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

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 and clone InfluxData Documentation Repository

Fork this repository and clone it to your local machine.

Development Environment Setup

Prerequisites

docs-v2 automatically runs format (Markdown, JS, and CSS) linting and code block tests for staged files that you try to commit.

For the linting and tests to run, you need to install:

  • Node.js and Yarn: For managing dependencies and running build scripts
  • Docker: For running Vale linter and code block tests
  • VS Code extensions (optional): For enhanced editing experience

_Note: The git pre-commit and pre-push hooks are configured to run linting and tests automatically when you commit or push changes. We strongly recommend letting them run, but you can skip them (and avoid installing related dependencies) by including the --no-verify flag with your commit--for example:

git commit -m "<COMMIT_MESSAGE>" --no-verify

Install Node.js dependencies

To install dependencies listed in package.json:

  1. Install Node.js for your system.
  2. Install Yarn 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: configures and manages git pre-commit and pre-push hooks for linting and testing Markdown content.
  • prettier: 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 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.

docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .

Run the documentation locally (optional)

To run the documentation locally, follow the instructions provided in the README.

Install Visual Studio Code extensions

If you use Microsoft Visual Studio (VS) Code, you can install extensions to help you navigate, check, and edit files.

docs-v2 contains a ./.vscode/settings.json that configures the following extensions:

  • Comment Anchors: recognizes tags (for example, //SOURCE) and makes links and filepaths clickable in comments.
  • Vale: shows linter errors and suggestions in the editor.
  • YAML Schemas: validates frontmatter attributes.

Making Changes

Style Guidelines

Content Guidelines

Content follows Google Developer Documentation Style Guide and YouTube API documentation patterns with a few InfluxData-specific adaptations.

Markdown

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.

Semantic line feeds

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.

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:

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.

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:

source: /shared/path/to/content.md

For complete details including examples and best practices, see the Source section in DOCS-FRONTMATTER.md.

Common Shortcodes Reference

Callouts (notes and warnings)

> [!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

{{< 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

{{< 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.

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 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.

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:

git commit -m "<COMMIT_MESSAGE>" --no-verify

Quick Testing Reference

# 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.

Submission Process

Commit Guidelines

When creating commits, follow these guidelines:

  • Use a clear, descriptive commit message that explains the change
  • Start with a type prefix: fix(), feat(), style(), refactor(), test(), chore()
  • For product-specific changes, include the product in parentheses: fix(enterprise), fix(influxdb3), fix(core)
  • Keep the first line under 72 characters
  • Reference issues with "closes" or "fixes": closes #123 or closes influxdata/DAR#123
  • For multiple issues, use comma separation: closes influxdata/DAR#517, closes influxdata/DAR#518

Examples:

fix(enterprise): correct Docker environment variable name for license email
fix(influxdb3): correct Docker environment variable and compose examples for monolith
feat(telegraf): add new plugin documentation
chore(ci): update Vale configuration

Submit a pull request

Push your changes up to your forked repository, then create a new pull request.

Reference Documentation

For detailed reference documentation, see:

  • DOCS-FRONTMATTER.md - Complete frontmatter field reference with all available options
  • DOCS-SHORTCODES.md - Complete shortcodes reference with usage examples for all available shortcodes

Advanced Configuration

Vale style linting configuration

docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms.

Advanced Vale usage:

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.

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:

    <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.

  4. 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:

    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:

    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.