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/copilot-instructions.md

8.7 KiB
Raw Permalink Blame History

Instructions for InfluxData Documentation

Purpose and scope

Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting.

Documentation structure

Abbreviations and shortcuts

  • gdd: Google Developer Documentation style
  • 3core: InfluxDB 3 Core
  • 3ent: InfluxDB 3 Enterprise

Style guidelines

  • Follow Google Developer Documentation style guidelines
  • For API references, follow YouTube Data API style
  • Use semantic line feeds (one sentence per line)
  • Format code examples to fit within 80 characters
  • Command line examples:
    • Should be formatted as code blocks
    • Should use long options (e.g., --option instead of -o)
  • Use cURL for API examples
    • Format to fit within 80 characters
    • Should use --data-urlencode for query parameters
    • Should use --header for headers
  • Use only h2-h6 headings in content (h1 comes from frontmatter title properties)
  • Use sentence case for headings
  • Use GitHub callout syntax
  • Image naming: project/version-context-description.png
  • Use appropriate product names and versions consistently
  • Follow InfluxData vocabulary guidelines

Markdown and shortcodes

  • Include proper frontmatter for Markdown pages in content/**/*.md (except for shared content files in content/shared/):

    title: # Page title (h1)
seotitle: # SEO title
list_title: # Title for article lists
description: # SEO description
menu:
  product_version:
weight: # Page order (1-99, 101-199, etc.)

  • Follow the shortcode examples in content/example.md and the documentation for docs-v2 contributors in CONTRIBUTING.md

  • Use provided shortcodes correctly:

    • Notes/warnings: {{% note %}}, {{% warn %}}
    • Product-specific: {{% enterprise %}}, {{% cloud %}}
    • Tabbed content: {{< tabs-wrapper >}}, {{% tabs %}}, {{% tab-content %}}
    • Tabbed content for code examples (without additional text): {{< code-tabs-wrapper >}}, {{% code-tabs %}}, {{% code-tab-content %}}
    • Version links: {{< latest >}}, {{< latest-patch >}}
    • API endpoints: {{< api-endpoint >}}
    • Required elements: {{< req >}}
    • Navigation: {{< page-nav >}}
    • Diagrams: {{< diagram >}}, {{< filesystem-diagram >}}

Code examples and testing

  • Provide complete, working examples with proper testing annotations:
print("Hello, world!")

Hello, world!
  • CLI command example:
influx query 'from(bucket:"example") |> range(start:-1h)'

Table: keys: [_start, _stop, _field, _measurement]
           _start:time                      _stop:time           _field:string     _measurement:string                      _time:time                  _value:float
------------------------------  ------------------------------  ----------------------  ----------------------  ------------------------------  ----------------------------
  • Include necessary environment variables
  • Show proper credential handling for authenticated commands

API documentation

  • /api-docs contains OpenAPI spec files used for API reference documentation
  • Follow OpenAPI specification patterns
  • Match REST API examples to current implementation
  • Include complete request/response examples
  • Document required headers and authentication

Versioning and product differentiation

  • Clearly distinguish between different InfluxDB versions (1.x, 2.x, 3.x)
  • Use correct terminology for each product variant
  • Apply appropriate UI descriptions and screenshots
  • Reference appropriate query language per version

Development tools

  • Vale.sh linter for style checking
    • Configuration file: .vale.ini
  • Docker for local development and testing
  • pytest and pytest-codeblocks for validating code examples
  • Use cypress for testing documentation UI and links
  • Prettier for code formatting
  • ESLint for JavaScript and TypeScript linting
  • Lefthook (NPM package) for managing pre-commit hooks for quality assurance

Code style

  • Use modern JavaScript (ES6+) syntax

Related repositories

Additional instruction files

For specific workflows and content types, also refer to:

  • InfluxDB 3 code placeholders: .github/instructions/influxdb3-code-placeholders.instructions.md - Guidelines for placeholder formatting, descriptions, and shortcode usage in InfluxDB 3 documentation
  • Contributing guidelines: .github/instructions/contributing.instructions.md - Detailed style guidelines, shortcode usage, frontmatter requirements, and development workflows
  • Content-specific instructions: Check .github/instructions/ directory for specialized guidelines covering specific documentation patterns and requirements

Integration with specialized instructions

When working on InfluxDB 3 documentation (Core/Enterprise), prioritize the placeholder guidelines from influxdb3-code-placeholders.instructions.md.

For general documentation structure, shortcodes, and development workflows, follow the comprehensive guidelines in contributing.instructions.md.