5.7 KiB
5.7 KiB
InfluxData Documentation Repository (docs-v2)
This is the primary instruction file for working with the InfluxData documentation site.
For detailed information on specific topics, refer to the specialized instruction files in .github/instructions/.
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 |
| Test All | yarn test:codeblocks:all |
15-45m | NEVER CANCEL |
| Lint | yarn lint |
~1m | Pre-commit checks |
Working Effectively
Collaboration approach
Be a critical thinking partner, provide honest feedback, and identify potential issues.
Setup Steps
- Install dependencies (see Quick Reference table above)
- Build the static site
- Start development server at http://localhost:1313/
- Alternative: Use
docker compose up local-devif local setup fails
Testing
For comprehensive testing procedures, see DOCS-TESTING.md.
Quick reference (NEVER CANCEL long-running tests):
- Code blocks:
yarn test:codeblocks:all(15-45 minutes) - Links:
yarn test:links(1-5 minutes, requires link-checker binary) - Style:
docker compose run -T vale content/**/*.md(30-60 seconds) - Pre-commit:
yarn lint(or skip with--no-verify)
Validation
Test these after changes:
# 1. Server renders pages (check 200 status)
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/
# 2. Build outputs exist (~529MB)
npx hugo --quiet && du -sh public/
# 3. Shortcodes work
yarn test:links content/example.md
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
- Product versions:
/data/products.yml - Query languages: SQL, InfluxQL, Flux (per product version)
- Site: https://docs.influxdata.com
Writing Documentation
For detailed guidelines, see:
- Workflow: DOCS-CONTRIBUTING.md - Contribution guidelines and workflow
- Shortcodes: DOCS-SHORTCODES.md - Complete shortcode reference
- Examples: content/example.md - Working examples for testing
- Frontmatter: DOCS-FRONTMATTER.md - Complete page metadata reference
- Testing: DOCS-TESTING.md - Testing procedures
- API Docs: api-docs/README.md - API documentation workflow
Code Examples
Use pytest annotations for testable examples:
print("Hello, world!")
Hello, world!
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 errors | Check .ci/vale/styles/config/vocabularies |
Specialized Instructions
For detailed information on specific topics:
| Topic | File | Description |
|---|---|---|
| Content | content.instructions.md | Lightweight pointer to frontmatter and shortcode references |
| Layouts | layouts.instructions.md | Shortcode implementation patterns and testing |
| API Docs | api-docs.instructions.md | OpenAPI spec workflow |
| Assets | assets.instructions.md | TypeScript/JavaScript and CSS development |
| Testing | DOCS-TESTING.md | Comprehensive testing procedures |
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)