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

7.4 KiB
Raw Permalink Blame History

GitHub Copilot Instructions for InfluxData Documentation

Purpose and scope

GitHub Copilot should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting.

Documentation structure

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 each page:

    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