Skip to content

Commit e3bfd39

Browse files
jstirnamanjstirnaman
authored
chore(instructions): Agents file initial commit (#6492)
1 parent a43a880 commit e3bfd39

File tree

1 file changed

+232
-0
lines changed

1 file changed

+232
-0
lines changed

‎AGENTS.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# InfluxData Documentation (docs-v2)
2+
3+
> **For AI agents working with the InfluxData documentation repository**
4+
5+
## Project Overview
6+
7+
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.
8+
9+
**Key Characteristics:**
10+
- **Scale**: 5,359+ pages
11+
- **Build time**: ~75 seconds (NEVER cancel Hugo builds)
12+
- **Tech stack**: Hugo, Node.js, Docker, Vale, Pytest, Cypress
13+
- **Test time**: 15-45 minutes for full code block tests
14+
15+
## Quick Commands
16+
17+
| Task | Command | Time |
18+
|------|---------|------|
19+
| Install dependencies | `CYPRESS_INSTALL_BINARY=0 yarn install` | ~4s |
20+
| Build site | `npx hugo --quiet` | ~75s |
21+
| Dev server | `npx hugo server` | ~92s |
22+
| Test code blocks | `yarn test:codeblocks:all` | 15-45m |
23+
| Lint | `yarn lint` | ~1m |
24+
25+
## Repository Structure
26+
27+
```
28+
docs-v2/
29+
├── content/ # Documentation content
30+
│ ├── influxdb3/ # InfluxDB 3 (core, enterprise, cloud-*)
31+
│ ├── influxdb/ # InfluxDB v2 and v1
32+
│ ├── enterprise_influxdb/ # InfluxDB Enterprise v1
33+
│ ├── telegraf/ # Telegraf docs
34+
│ ├── shared/ # Shared content across products
35+
│ └── example.md # Shortcode testing playground
36+
├── layouts/ # Hugo templates and shortcodes
37+
├── assets/ # JS, CSS, TypeScript
38+
├── api-docs/ # OpenAPI specifications
39+
├── data/ # YAML/JSON data files
40+
├── public/ # Build output (gitignored, ~529MB)
41+
└── .github/
42+
└── copilot-instructions.md # Primary AI instructions
43+
```
44+
45+
**Content Paths**: See [copilot-instructions.md](.github/copilot-instructions.md#content-organization)
46+
47+
## Common Workflows
48+
49+
### Editing a page in your browser
50+
51+
1. Navigate to the desired page on [docs.influxdata.com](https://docs.influxdata.com)
52+
2. Click the "Edit this page" link at the bottom
53+
3. Make changes in the GitHub web editor
54+
4. Commit changes via a pull request
55+
56+
### Creating/Editing Content Manually
57+
58+
**Frontmatter** (page metadata):
59+
```yaml
60+
title: Page Title # Required - becomes h1
61+
description: Brief desc # Required - for SEO
62+
menu:
63+
influxdb_2_0:
64+
name: Nav Label # Optional - nav display name
65+
parent: Parent Node # Optional - for nesting
66+
weight: 1 # Required - sort order
67+
```
68+
69+
**Shared Content** (avoid duplication):
70+
```yaml
71+
source: /shared/path/to/content.md
72+
```
73+
74+
Shared content files (`/shared/path/to/content.md`):
75+
- Don't store frontmatter
76+
- Can use `{{% show-in %}}`, `{{% hide-in %}}`, and the `version` keyword (`/influxdb3/version/content.md`)
77+
78+
**Common Shortcodes**:
79+
- Callouts: `> [!Note]`, `> [!Warning]`, `> [!Important]`, `> [!Tip]`
80+
- Tabs: `{{< tabs-wrapper >}}` + `{{% tabs %}}` + `{{% tab-content %}}`
81+
- Required: `{{< req >}}` or `{{< req type="key" >}}`
82+
- Code placeholders: `{ placeholders="<PLACEHOLDER>" }`
83+
84+
**📖 Complete Reference**: [DOCS-SHORTCODES.md](DOCS-SHORTCODES.md) | [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md)
85+
86+
### Testing Changes
87+
88+
**Always test before committing**:
89+
```bash
90+
# Verify server renders (check 200 status)
91+
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/
92+
93+
# Test specific content
94+
yarn test:links content/influxdb3/core/**/*.md
95+
96+
# Run style linting
97+
docker compose run -T vale content/**/*.md
98+
```
99+
100+
**📖 Complete Reference**: [DOCS-TESTING.md](DOCS-TESTING.md)
101+
102+
### Committing Changes
103+
104+
**Commit Message Format**:
105+
```
106+
type(scope): description
107+
108+
Examples:
109+
- fix(enterprise): correct Docker environment variable
110+
- feat(influxdb3): add new plugin documentation
111+
- docs(core): update configuration examples
112+
```
113+
114+
**Types**: `fix`, `feat`, `style`, `refactor`, `test`, `chore`
115+
116+
**Scopes**: `enterprise`, `influxdb3`, `core`, `cloud`, `telegraf`, etc.
117+
118+
**Pre-commit hooks** run automatically (Vale, Prettier, tests). Skip with:
119+
```bash
120+
git commit -m "message" --no-verify
121+
```
122+
123+
**📖 Complete Reference**: [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md#commit-guidelines)
124+
125+
## Key Patterns
126+
127+
### Content Organization
128+
129+
- **Product versions**: Managed in `/data/products.yml`
130+
- **Semantic line feeds**: One sentence per line for better diffs
131+
- **Heading hierarchy**: Use h2-h6 only (h1 auto-generated from frontmatter)
132+
- **Image naming**: `project/version-context-description.png`
133+
134+
### Code Examples
135+
136+
**Testable code blocks** (pytest):
137+
```python
138+
print("Hello, world!")
139+
```
140+
141+
<!--pytest-codeblocks:expected-output-->
142+
143+
```
144+
Hello, world!
145+
```
146+
147+
**Language identifiers**: Use `python` not `py`, `bash` not `sh` (for pytest collection)
148+
149+
### API Documentation
150+
151+
- **Location**: `/api-docs/` directory
152+
- **Format**: OpenAPI 3.0 YAML
153+
- **Generation**: Uses Redoc + custom processing
154+
- **📖 Workflow**: [api-docs/README.md](api-docs/README.md)
155+
156+
### JavaScript/TypeScript
157+
158+
- **Entry point**: `assets/js/main.js`
159+
- **Pattern**: Component-based with `data-component` attributes
160+
- **Debugging**: Source maps or debug helpers available
161+
- **📖 Details**: [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md#javascript-in-the-documentation-ui)
162+
163+
## Important Constraints
164+
165+
### Performance
166+
- **NEVER cancel Hugo builds** - they take ~75s normally
167+
- **NEVER cancel test runs** - code block tests take 15-45 minutes
168+
- **Set timeouts**: Hugo (180s+), tests (30+ minutes)
169+
170+
### Style Guidelines
171+
- Use Google Developer Documentation style
172+
- Active voice, present tense, second person for instructions
173+
- No emojis unless explicitly requested
174+
- Use long options in CLI examples (`--option` vs `-o`)
175+
- Format code blocks within 80 characters
176+
177+
### Network Restrictions
178+
Some operations may fail in restricted environments:
179+
- Docker builds requiring external repos
180+
- `docker compose up local-dev` (Alpine packages)
181+
- Cypress installation (use `CYPRESS_INSTALL_BINARY=0`)
182+
183+
## Documentation References
184+
185+
| Document | Purpose |
186+
|----------|---------|
187+
| [DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md) | Contribution workflow, style guidelines |
188+
| [DOCS-TESTING.md](DOCS-TESTING.md) | Testing procedures (code blocks, links, linting) |
189+
| [DOCS-SHORTCODES.md](DOCS-SHORTCODES.md) | Complete shortcode reference |
190+
| [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md) | Complete frontmatter field reference |
191+
| [.github/copilot-instructions.md](.github/copilot-instructions.md) | Primary AI assistant instructions |
192+
| [api-docs/README.md](api-docs/README.md) | API documentation workflow |
193+
| [content/example.md](content/example.md) | Live shortcode examples for testing |
194+
195+
## Specialized Topics
196+
197+
### Working with Specific Products
198+
199+
| Product | Content Path | Special Notes |
200+
|---------|-------------|---------------|
201+
| InfluxDB 3 Core | `/content/influxdb3/core/` | Latest architecture |
202+
| InfluxDB 3 Enterprise | `/content/influxdb3/enterprise/` | Core + licensed features, clustered |
203+
| InfluxDB Cloud Dedicated | `/content/influxdb3/cloud-dedicated/`, `/content/influxdb3/cloud-serverless/` | Managed and distributed |
204+
| InfluxDB Clustered | `/content/influxdb3/clustered/` | Self-managed and distributed |
205+
| InfluxDB Cloud | `/content/influxdb/cloud/` | Legacy but active |
206+
| InfluxDB v2 | `/content/influxdb/v2/` | Legacy but active |
207+
| InfluxDB Enterprise v1 | `/content/enterprise_influxdb/v1/` | Legacy but active enterprise, clustered |
208+
209+
### Advanced Tasks
210+
211+
- **Vale configuration**: `.ci/vale/styles/` for custom rules
212+
- **Link checking**: Uses custom `link-checker` binary
213+
- **Docker testing**: `compose.yaml` defines test services
214+
- **Lefthook**: Git hooks configuration in `lefthook.yml`
215+
216+
## Troubleshooting
217+
218+
| Issue | Solution |
219+
|-------|----------|
220+
| Pytest collected 0 items | Use `python` not `py` for code block language |
221+
| Hugo build errors | Check `/config/_default/` configuration |
222+
| Link validation slow | Test specific files: `yarn test:links content/file.md` |
223+
| Vale errors | Check `.ci/vale/styles/config/vocabularies` |
224+
225+
## Critical Reminders
226+
227+
1. **Be a critical thinking partner** - Challenge assumptions, identify issues
228+
2. **Test before committing** - Run relevant tests locally
229+
3. **Reference, don't duplicate** - Link to detailed docs instead of copying
230+
4. **Respect build times** - Don't cancel long-running operations
231+
5. **Follow conventions** - Use established patterns for consistency
232+

0 commit comments

Comments
 (0)