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

11 KiB
Raw Permalink Blame History

InfluxData Documentation Repository (docs-v2)

For GitHub Copilot and other AI coding agents

This is the primary instruction file for GitHub Copilot working with the InfluxData documentation site.

Instruction resources:

Quick Reference

Task Command Time Details
Install CYPRESS_INSTALL_BINARY=0 yarn install ~4s Skip Cypress for CI
Build npx hugo --quiet ~75s NEVER CANCEL
Dev Server npx hugo server ~92s Port 1313
Create Docs docs create <draft> --products <keys> varies AI-assisted scaffolding
Create & Open docs create <draft> --products <keys> --open instant Non-blocking (background)
Create & Wait docs create <draft> --products <keys> --open --wait varies Blocking (interactive)
Edit Docs docs edit <url> instant Non-blocking (background)
Edit Docs (wait) docs edit <url> --wait varies Blocking (interactive)
List Files docs edit <url> --list instant Show files without opening
Add Placeholders docs placeholders <file> instant Add placeholder syntax to code blocks
Audit Docs docs audit --products <keys> varies Audit documentation coverage
Release Notes docs release-notes <v1> <v2> --products <keys> varies Generate release notes from commits
Test All yarn test:codeblocks:all 15-45m NEVER CANCEL
Lint yarn lint ~1m Pre-commit checks

CLI Tools

For when to use CLI vs direct editing, see docs-cli-workflow skill.

# Create new documentation (AI-assisted scaffolding)
docs create <draft> --products <key-or-path>
docs create <draft> --products influxdb3_core --open        # Non-blocking
docs create <draft> --products influxdb3_core --open --wait # Blocking

# Find and edit documentation by URL
docs edit <url>               # Non-blocking (agent-friendly)
docs edit <url> --list        # List files only
docs edit <url> --wait        # Wait for editor

# Other tools
docs placeholders <file>      # Add placeholder syntax to code blocks
docs audit --products <keys>  # Audit documentation coverage
docs release-notes <v1> <v2> --products <keys>

# Get help
docs --help
docs create --help

Key points:

  • Accepts both product keys (influxdb3_core) and paths (/influxdb3/core)
  • Non-blocking by default (agent-friendly)
  • Use --wait for interactive editing
  • --products and --repos are mutually exclusive for audit/release-notes

Workflows

Content Editing

See content-editing skill for complete workflow:

  • Creating/editing content with CLI
  • Shared content management
  • Testing and validation

Testing

See DOCS-TESTING.md and cypress-e2e-testing skill.

Quick tests (NEVER CANCEL long-running):

yarn test:codeblocks:all  # 15-45m
yarn test:links           # 1-5m
yarn lint                 # 1m

InfluxDB 3 Setup

See influxdb3-test-setup skill.

Quick setup:

./test/scripts/init-influxdb3.sh core        # Per-worktree, port 8282
./test/scripts/init-influxdb3.sh enterprise  # Shared, port 8181
./test/scripts/init-influxdb3.sh all         # Both

Hugo Template Development

See hugo-template-dev skill for template syntax, data access, and testing strategies.

Repository Structure

Content Organization

  • InfluxDB 3: /content/influxdb3/ (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer)
  • InfluxDB v2: /content/influxdb/ (v2, cloud)
  • InfluxDB v1: /content/influxdb/v1
  • InfluxDB Enterprise (v1): /content/enterprise_influxdb/v1/
  • Telegraf: /content/telegraf/v1/
  • Kapacitor: /content/kapacitor/
  • Chronograf: /content/chronograf/
  • Flux: /content/flux/
  • Examples: /content/example.md (comprehensive shortcode reference)
  • Shared content: /content/shared/

Key Files

  • Config: /config/_default/, package.json, compose.yaml, lefthook.yml
  • Testing: cypress.config.js, pytest.ini, .vale.ini
  • Assets: /assets/ (JS, CSS), /layouts/ (templates), /data/ (YAML/JSON)
  • Build output: /public/ (~529MB, gitignored)

Technology Stack

  • Hugo - Static site generator
  • Node.js/Yarn - Package management
  • Testing: Pytest, Cypress, link-checker, Vale
  • Tools: Docker, ESLint, Prettier, Lefthook

Common Issues

Network Restrictions

Commands that may fail in restricted environments:

  • Docker builds (external repos)
  • docker compose up local-dev (Alpine packages)
  • Cypress installation (use CYPRESS_INSTALL_BINARY=0)

Pre-commit Validation

# Quick validation before commits
yarn prettier --write "**/*.{css,js,ts,jsx,tsx}"
yarn eslint assets/js/**/*.js
npx hugo --quiet

Documentation Coverage

  • InfluxDB 3: Core, Enterprise, Cloud (Dedicated/Serverless), Clustered, Explorer, plugins
  • InfluxDB v2/v1: OSS, Cloud, Enterprise
  • Tools: Telegraf, Kapacitor, Chronograf, Flux
  • API Reference: All InfluxDB editions

Content Guidelines

Style guide: Google Developer Documentation Style Guide
Voice: Active, present tense, second person
Line breaks: Semantic line feeds (one sentence per line)
Files: lowercase-with-hyphens.md

Quick Shortcodes

# Callouts (GitHub-style alerts)
> [!Note] / [!Warning] / [!Tip] / [!Important] / [!Caution]

# Required elements
{{< req >}}
{{< req type="key" >}}

# Code placeholders
```sh { placeholders="DATABASE_NAME|API_TOKEN" }
curl https://example.com/api?db=DATABASE_NAME


**Complete reference**: [DOCS-SHORTCODES.md](../DOCS-SHORTCODES.md)

### Required Frontmatter

```yaml
title:       # Required
description: # Required
menu:
  product_menu_key:
    name:    # Optional
    parent:  # Optional
weight:      # Required: 1-99, 101-199, 201-299...

Shared content: Add source: /shared/path/to/file.md

Complete reference: DOCS-FRONTMATTER.md

Resources

Troubleshooting

Issue Solution
Pytest collected 0 items Use python not py for language identifier
Hugo build errors Check /config/_default/
Docker build fails Expected in restricted networks - use local Hugo
Cypress install fails Use CYPRESS_INSTALL_BINARY=0 yarn install
Link validation slow Test specific files: yarn test:links content/file.md
Vale "0 errors in stdin" File is outside repo - Vale Docker can only access repo files
Vale false positives Add terms to .ci/vale/styles/InfluxDataDocs/Terms/ignore.txt
Vale duration warnings Duration literals (30d) are valid - check InfluxDataDocs.Units

Specialized Instructions

File Pattern-Specific Instructions

These instructions are automatically loaded by GitHub Copilot based on the files you're working with:

Pattern File Description
content/**/*.md content.instructions.md Content file guidelines, frontmatter, shortcodes
layouts/**/*.html layouts.instructions.md Shortcode implementation patterns and testing
api-docs/**/*.yml api-docs.instructions.md OpenAPI spec workflow
assets/js/**/*.{js,ts} assets.instructions.md TypeScript/JavaScript and CSS development

Specialized Resources

Custom Agents (.github/agents/):

Claude Skills (.claude/skills/ - detailed workflows):

Documentation:

Important Notes

  • This is a large site (5,359+ pages) with complex build processes
  • NEVER CANCEL long-running operations (Hugo builds, tests)
  • Set appropriate timeouts: Hugo build (180s+), tests (30+ minutes)