chore(instructions): Agents file initial commit (#6492)
Jason Stirnaman
GitHub
parent
a43a880f2f
commit
e3bfd39489
|
|
@ -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="<PLACEHOLDER>" }`
|
||||||
|
|
||||||
|
**📖 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!")
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--pytest-codeblocks:expected-output-->
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
Loading…
Reference in New Issue