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

14 KiB
Raw Permalink Blame History

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.

Contributing to InfluxData Documentation

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.

Make suggested updates

Fork and clone InfluxData Documentation Repository

Fork this repository and clone it to your local machine.

Install project dependencies

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 Docker and Node.js dependencies.

_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, enter the following command in your terminal:

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

You probably don't want to display this syntax in the docs, which unfortunately means you'd need to include the test block separately from the displayed code block. To hide it from users, wrap the code block inside an HTML comment. pytest-codeblocks will still collect and run the code block.

Mark tests to skip

pytest-codeblocks has features for skipping tests and marking blocks as failed. To learn more, see the pytest-codeblocks README and tests.

Vale style linting

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

To run Vale, use the Vale extension for your editor or the included Docker configuration. For example, the following command runs Vale in a container and lints *.md (Markdown) files in the path ./content/influxdb/cloud-dedicated/write-data/ using the specified configuration for cloud-dedicated:

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

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:

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 to add the same content to all children pages as well.

md {{% note %}} Insert note markdown content here. {{% /note %}}

{{% warn %}} Insert warning markdown content here. {{% /warn %}}

This is content that references {{< enterprise-name >}}. This is content that references {{< enterprise-name "short" >}}. md {{< latest-patch >}}

{{< latest-patch product="telegraf" >}}

{{< latest-patch product="chronograf" version="1.7" >}} md {{< api-endpoint method="get" endpoint="/api/v2/tasks" api-ref="/influxdb/cloud/api/#operation/GetTasks">}} 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 >}}

{{% /code-tab-content %}}

{{% code-tab-content %}}

md {{< req >}} md {{< req type="key" >}}

  • {{< req "*" >}} This element is required
  • {{< req "*" >}} This element is also required
  • This element is NOT required md

{{ page-nav prev="/path/to/prev/" next="/path/to/next" >}}

{{ page-nav prev="/path/to/prev/" prevText="Previous" next="/path/to/next" nextText="Next" >}}

{{ page-nav prev="/path/to/prev/" next="/path/to/next" keepTab=true>}} md {{< diagram >}} flowchart TB This --> That That --> There {{< /diagram >}} html {{< img-hd src="/path/to/image" alt="Alternate title" />}} md {{% truncate %}} Truncated markdown content here. {{% /truncate %}}

Use the optional {{< expand-wrapper >}} shortcode around a group of {{% expand %}} shortcodes to ensure proper spacing around the expandable elements:

Generate a list of children articles

Section landing pages often contain just a list of articles with links and descriptions for each. This can be cumbersome to maintain as content is added. To automate the listing of articles in a section, use the {{< children >}} shortcode.

md {{< children readmore=true >}} md /shared/text/example1/example.js /shared/text/example1/example.py md content | |--- api | query.pdmc | query.sh | _index.md yaml list_query_example: cumulative_sum md {{% token-link "database" "resource/" }}

database token

{{< icon "icon-name" "v2" >}}

{{< nav-icon "tasks" "v2" >}} md {{< flex >}} {{% flex-content %}} Column 1 {{% /flex-content %}} {{% flex-content %}} Column 2 {{% /flex-content %}} {{< /flex >}}

The rendered output is "I like butterflies" with "butterflies" highlighted. When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!"

Flux sample data tables

The Flux sample package provides basic sample datasets that can be used to illustrate how Flux functions work. To quickly display one of the raw sample datasets, use the {{% flux/sample %}} shortcode.

The flux/sample shortcode has the following arguments that can be specified by name or positionally.

set

Sample dataset to output. Use either set argument name or provide the set as the first argument. The following sets are available:

  • float
  • int
  • uint
  • string
  • bool
  • numericBool

includeNull

Specify whether or not to include null values in the dataset. Use either includeNull argument name or provide the boolean value as the second argument.

includeRange

Specify whether or not to include time range columns (_start and _stop) in the dataset. This is only recommended when showing how functions that require a time range (such as window()) operate on input data. Use either includeRange argument name or provide the boolean value as the third argument.

Duplicate OSS content in Cloud

Docs for InfluxDB OSS and InfluxDB Cloud share a majority of content. To prevent duplication of content between versions, use the following shortcodes:

  • {{< duplicate-oss >}}
  • {{% oss-only %}}
  • {{% cloud-only %}}

[Similar patterns apply - see full CONTRIBUTING.md for complete examples]}` shortcode. Use the shortcode on both inline and content blocks:

cloud-only

Wrap content that should only appear in the Cloud version of the doc with the {{% cloud-only %}} shortcode. Use the shortcode on both inline and content blocks:

Show or hide content blocks in shared content

The source frontmatter lets you source page content from another file and is used to share content across InfluxDB products. Within the shared content, you can use the show-in and hide-in shortcodes to conditionally show or hide content blocks based on the InfluxDB "version." Valid "versions" include:

  • v2
  • cloud
  • cloud-serverless
  • cloud-dedicated
  • clustered
  • core
  • enterprise

show-in

The show-in shortcode accepts a comma-delimited string of InfluxDB "versions" to show the content block in. The version is the second level of the page path--for example: /influxdb/<version>/....

All-Caps

Clockface v3 introduces many buttons with text formatted as all-caps. Use the {{< caps >}} shortcode to format text to match those buttons.

html

{{< influxdbu >}}

{{< influxdbu "influxdb-101" >}}

{{< influxdbu title="Course title" summary="Short course summary." action="Take the course" link="https://university.influxdata.com/" >}} yaml

Pattern

menu: _ref: # ...

Example

menu: influxdb_2_0_ref: # ...

`

{{< influxdb/host >}}

{{< influxdb/host "serverless" >}}

{{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME and RETENTION_POLICY{{% /code-placeholder-key %}}: the database and retention policy mapping (DBRP) for the InfluxDB v2 bucket that you want to write to
  • {{% code-placeholder-key %}

[Similar patterns apply - see full CONTRIBUTING.md for complete examples]}USERNAME{{% /code-placeholder-key %}}: your InfluxDB 1.x username

  • {{% code-placeholder-key %}}PASSWORD_OR_TOKEN{{% /code-placeholder-key %}}: your InfluxDB 1.x password or InfluxDB API token

  • {{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: your InfluxDB API token html

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

  1. Start Hugo in development mode--for example:

    yarn hugo server

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