diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..dba21ffa6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,232 @@ +# InfluxData Documentation (docs-v2) + +> **For AI agents working with the InfluxData documentation repository** + +## Project Overview + +This repository powers [docs.influxdata.com](https://docs.influxdata.com), a Hugo-based static documentation site covering InfluxDB 3, InfluxDB v2/v1, Telegraf, and related products. + +**Key Characteristics:** +- **Scale**: 5,359+ pages +- **Build time**: ~75 seconds (NEVER cancel Hugo builds) +- **Tech stack**: Hugo, Node.js, Docker, Vale, Pytest, Cypress +- **Test time**: 15-45 minutes for full code block tests + +## Quick Commands + +| Task | Command | Time | +|------|---------|------| +| Install dependencies | `CYPRESS_INSTALL_BINARY=0 yarn install` | ~4s | +| Build site | `npx hugo --quiet` | ~75s | +| Dev server | `npx hugo server` | ~92s | +| Test code blocks | `yarn test:codeblocks:all` | 15-45m | +| Lint | `yarn lint` | ~1m | + +## Repository Structure + +``` +docs-v2/ +├── content/ # Documentation content +│ ├── influxdb3/ # InfluxDB 3 (core, enterprise, cloud-*) +│ ├── influxdb/ # InfluxDB v2 and v1 +│ ├── enterprise_influxdb/ # InfluxDB Enterprise v1 +│ ├── telegraf/ # Telegraf docs +│ ├── shared/ # Shared content across products +│ └── example.md # Shortcode testing playground +├── layouts/ # Hugo templates and shortcodes +├── assets/ # JS, CSS, TypeScript +├── api-docs/ # OpenAPI specifications +├── data/ # YAML/JSON data files +├── public/ # Build output (gitignored, ~529MB) +└── .github/ + └── copilot-instructions.md # Primary AI instructions +``` + +**Content Paths**: See [copilot-instructions.md](.github/copilot-instructions.md#content-organization) + +## Common Workflows + +### Editing a page in your browser + +1. Navigate to the desired page on [docs.influxdata.com](https://docs.influxdata.com) +2. Click the "Edit this page" link at the bottom +3. Make changes in the GitHub web editor +4. Commit changes via a pull request + +### Creating/Editing Content Manually + +**Frontmatter** (page metadata): +```yaml +title: Page Title # Required - becomes h1 +description: Brief desc # Required - for SEO +menu: + influxdb_2_0: + name: Nav Label # Optional - nav display name + parent: Parent Node # Optional - for nesting +weight: 1 # Required - sort order +``` + +**Shared Content** (avoid duplication): +```yaml +source: /shared/path/to/content.md +``` + +Shared content files (`/shared/path/to/content.md`): +- Don't store frontmatter +- Can use `{{% show-in %}}`, `{{% hide-in %}}`, and the `version` keyword (`/influxdb3/version/content.md`) + +**Common Shortcodes**: +- Callouts: `> [!Note]`, `> [!Warning]`, `> [!Important]`, `> [!Tip]` +- Tabs: `{{< tabs-wrapper >}}` + `{{% tabs %}}` + `{{% tab-content %}}` +- Required: `{{< req >}}` or `{{< req type="key" >}}` +- Code placeholders: `{ placeholders="" }` + +**📖 Complete Reference**: [DOCS-SHORTCODES.md](DOCS-SHORTCODES.md) | [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md) + +### Testing Changes + +**Always test before committing**: +```bash +# Verify server renders (check 200 status) +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/ + +# Test specific content +yarn test:links content/influxdb3/core/**/*.md + +# Run style linting +docker compose run -T vale content/**/*.md +``` + +**📖 Complete Reference**: [DOCS-TESTING.md](DOCS-TESTING.md) + +### Committing Changes + +**Commit Message Format**: +``` +type(scope): description + +Examples: +- fix(enterprise): correct Docker environment variable +- feat(influxdb3): add new plugin documentation +- docs(core): update configuration examples +``` + +**Types**: `fix`, `feat`, `style`, `refactor`, `test`, `chore` + +**Scopes**: `enterprise`, `influxdb3`, `core`, `cloud`, `telegraf`, etc. + +**Pre-commit hooks** run automatically (Vale, Prettier, tests). Skip with: +```bash +git commit -m "message" --no-verify +``` + +**📖 Complete Reference**: [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md#commit-guidelines) + +## Key Patterns + +### Content Organization + +- **Product versions**: Managed in `/data/products.yml` +- **Semantic line feeds**: One sentence per line for better diffs +- **Heading hierarchy**: Use h2-h6 only (h1 auto-generated from frontmatter) +- **Image naming**: `project/version-context-description.png` + +### Code Examples + +**Testable code blocks** (pytest): +```python +print("Hello, world!") +``` + + + +``` +Hello, world! +``` + +**Language identifiers**: Use `python` not `py`, `bash` not `sh` (for pytest collection) + +### API Documentation + +- **Location**: `/api-docs/` directory +- **Format**: OpenAPI 3.0 YAML +- **Generation**: Uses Redoc + custom processing +- **📖 Workflow**: [api-docs/README.md](api-docs/README.md) + +### JavaScript/TypeScript + +- **Entry point**: `assets/js/main.js` +- **Pattern**: Component-based with `data-component` attributes +- **Debugging**: Source maps or debug helpers available +- **📖 Details**: [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md#javascript-in-the-documentation-ui) + +## Important Constraints + +### Performance +- **NEVER cancel Hugo builds** - they take ~75s normally +- **NEVER cancel test runs** - code block tests take 15-45 minutes +- **Set timeouts**: Hugo (180s+), tests (30+ minutes) + +### Style Guidelines +- Use Google Developer Documentation style +- Active voice, present tense, second person for instructions +- No emojis unless explicitly requested +- Use long options in CLI examples (`--option` vs `-o`) +- Format code blocks within 80 characters + +### Network Restrictions +Some operations may fail in restricted environments: +- Docker builds requiring external repos +- `docker compose up local-dev` (Alpine packages) +- Cypress installation (use `CYPRESS_INSTALL_BINARY=0`) + +## Documentation References + +| Document | Purpose | +|----------|---------| +| [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md) | Contribution workflow, style guidelines | +| [DOCS-TESTING.md](DOCS-TESTING.md) | Testing procedures (code blocks, links, linting) | +| [DOCS-SHORTCODES.md](DOCS-SHORTCODES.md) | Complete shortcode reference | +| [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md) | Complete frontmatter field reference | +| [.github/copilot-instructions.md](.github/copilot-instructions.md) | Primary AI assistant instructions | +| [api-docs/README.md](api-docs/README.md) | API documentation workflow | +| [content/example.md](content/example.md) | Live shortcode examples for testing | + +## Specialized Topics + +### Working with Specific Products + +| Product | Content Path | Special Notes | +|---------|-------------|---------------| +| InfluxDB 3 Core | `/content/influxdb3/core/` | Latest architecture | +| InfluxDB 3 Enterprise | `/content/influxdb3/enterprise/` | Core + licensed features, clustered | +| InfluxDB Cloud Dedicated | `/content/influxdb3/cloud-dedicated/`, `/content/influxdb3/cloud-serverless/` | Managed and distributed | +| InfluxDB Clustered | `/content/influxdb3/clustered/` | Self-managed and distributed | +| InfluxDB Cloud | `/content/influxdb/cloud/` | Legacy but active | +| InfluxDB v2 | `/content/influxdb/v2/` | Legacy but active | +| InfluxDB Enterprise v1 | `/content/enterprise_influxdb/v1/` | Legacy but active enterprise, clustered | + +### Advanced Tasks + +- **Vale configuration**: `.ci/vale/styles/` for custom rules +- **Link checking**: Uses custom `link-checker` binary +- **Docker testing**: `compose.yaml` defines test services +- **Lefthook**: Git hooks configuration in `lefthook.yml` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Pytest collected 0 items | Use `python` not `py` for code block language | +| Hugo build errors | Check `/config/_default/` configuration | +| Link validation slow | Test specific files: `yarn test:links content/file.md` | +| Vale errors | Check `.ci/vale/styles/config/vocabularies` | + +## Critical Reminders + +1. **Be a critical thinking partner** - Challenge assumptions, identify issues +2. **Test before committing** - Run relevant tests locally +3. **Reference, don't duplicate** - Link to detailed docs instead of copying +4. **Respect build times** - Don't cancel long-running operations +5. **Follow conventions** - Use established patterns for consistency +