| name | content-editing |
| description | Create, edit, and validate InfluxData documentation. Manages Hugo shared content across InfluxDB products, runs Vale style linting and Hugo builds, validates frontmatter and code blocks, and fact-checks via the documentation MCP server. Use when creating new doc pages, editing markdown .md files, managing shared content, running Vale or Hugo builds, or testing InfluxDB, Telegraf, or Flux documentation. |
Content Editing Workflow
Quick Decision Tree
CLI vs direct editing? → See docs-cli-workflow skill
Shared content changes? → Touch sourcing files (Part 1)
Run tests? → Hugo build, Vale, code-block lint, E2E (Part 2)
Verify technical accuracy? → MCP server (Part 4)
Run/fix Vale? → vale-linting skill. Author Vale rules/regex? → vale-rule-config skill
Using docs create and docs edit
For detailed guidance on when and how to use the docs CLI tools, see the docs-cli-workflow skill, which covers:
- When to suggest
docs create vs direct file creation
- When to suggest
docs edit vs direct file editing
- CLI command syntax and examples
- How to present recommendations to users
- Edge cases and user preference handling
Quick reference for this workflow:
docs create <draft-path> --products <product-key>
docs edit <url-or-path>
docs edit <url-or-path> --list
docs placeholders <file.md>
Part 1: Shared Content Management
What is Shared Content?
Content that appears in multiple products uses Hugo's content adapter pattern:
content/
├── shared/
│ └── influxdb3/
│ └── admin/
│ └── databases.md # Actual content here
├── influxdb3/
│ ├── core/
│ │ └── admin/
│ │ └── databases.md # Frontmatter only, has source:
│ └── enterprise/
│ └── admin/
│ └── databases.md # Frontmatter only, has source:
Frontmatter file example:
---
title: Database Management
source: /shared/influxdb3/admin/databases.md
---
CRITICAL: Touching Sourcing Files
When you edit a shared content file, Hugo does NOT automatically rebuild pages that reference it.
You MUST touch the frontmatter files to trigger a rebuild:
touch content/influxdb3/core/admin/databases.md
touch content/influxdb3/enterprise/admin/databases.md
Automatic (Recommended)
Use docs edit - it handles this automatically:
docs edit /influxdb3/core/admin/databases/
Programmatic Detection
If you need to handle this in code:
import { readFileSync } from 'fs';
import matter from 'gray-matter';
function isSharedContent(filePath) {
const content = readFileSync(filePath, 'utf8');
const { data, content: body } = matter(content);
return data.source && body.trim().length < 50;
}
function getSharedSource(filePath) {
const content = readFileSync(filePath, 'utf8');
const { data } = matter(content);
return data.source;
}
Why This Matters
Failure to touch sourcing files means:
- Hugo won't rebuild the pages
- Your changes won't appear in test/preview
- Tests will fail because content hasn't changed
- Published site won't reflect your edits
Check for Path Differences and Add alt_links
When creating or editing shared content, check if the URL paths differ between products. If they do, add alt_links frontmatter to each product file to cross-reference the equivalent pages.
See DOCS-FRONTMATTER.md for syntax and examples.
Check product resource terms are cross-referenced
Product resource terms often appear inside code-placeholder-key shortcode text and bullet item text.
Example product resource terms:
- "database token"
- "database name"
Part 2: Testing Workflow
After making content changes, run tests to validate:
1. Hugo Build Test (Required)
yarn hugo --quiet
2. Link Validation (Recommended)
Link validation uses the link-checker binary (see
DOCS-TESTING.md § "Link Validation with Link-Checker"
for installation). It validates the rendered HTML, so build the site first.
yarn hugo --quiet
link-checker map content/influxdb3/core/path/*.md | xargs link-checker check
link-checker check public/influxdb3/core/get-started/
3. Code Block Syntax Lint (Fast — Runs on Every PR)
Parse/compile-only check for fenced code blocks. No credentials, no network, no Docker needed.
yarn lint-codeblocks content/influxdb3/core/admin/tokens/*.md
yarn test:lint-codeblocks
Blocking policy (mirrors CI):
| Language | On failure |
|---|
| JSON, YAML, TOML | ::error:: — fails the PR check |
| bash, python, javascript | ::warning:: — informational only |
Normalization: declared placeholders="TOKEN|DURATION" fence attributes and Hugo shortcodes ({{< >}}, {{% %}}) are substituted before parsing. See DOCS-TESTING.md § "Parse/compile code-block lint" for details.
4. Code Block Execution Testing (For Pages with Runnable Examples)
yarn test:codeblocks:all
5. E2E Testing (For Specific Pages)
Use the cypress-e2e-testing skill for comprehensive page testing:
node cypress/support/run-e2e-specs.js content/influxdb3/core/admin/databases/_index.md
node cypress/support/run-e2e-specs.js \
--spec "cypress/e2e/content/api-reference.cy.js" \
content/influxdb3/core/api/_index.md
Important prerequisites:
- API tests: Run
yarn build:api-docs first
- Markdown validation: Run
yarn hugo --quiet && yarn build:md first
See cypress-e2e-testing skill for detailed test workflow.
6. Style Linting (Pre-commit)
Vale style linting runs automatically via pre-commit hooks, but you can run it manually:
.ci/vale/vale.sh --config=.vale.ini content/influxdb3/core/path/to/file.md
.ci/vale/vale.sh --config=.vale.ini --minAlertLevel=warning content/path/
.ci/vale/vale.sh sync
Common issues:
admin flagged → Use "administrator" in prose, or it's in a code context
- Duration literals (
30d) → These are valid InfluxDB syntax
- Technical terms flagged → Add to
.ci/vale/styles/InfluxDataDocs/Terms/ignore.txt
See vale-linting skill for comprehensive Vale workflow.
7. Visual Preview (Optional)
yarn hugo server
Part 3: Vale Style Linting
Vale checks documentation for style guide violations, spelling errors, and branding consistency.
For writing Vale rules and understanding regex patterns, see the vale-rule-config skill.
Running Vale
.ci/vale/vale.sh content/**/*.md
.ci/vale/vale.sh content/influxdb3/core/**/*.md
.ci/vale/vale.sh \
--config=content/influxdb3/cloud-dedicated/.vale.ini \
--minAlertLevel=error \
content/influxdb3/cloud-dedicated/write-data/**/*.md
Understanding Vale Alerts
Vale reports three alert levels:
- Error (red): Critical issues - branding violations, broken style rules, rejected terms
- Warning (yellow): Style guide recommendations - should be fixed
- Suggestion (blue): Optional improvements - consider fixing
Fixing Common Vale Issues
Spelling/vocabulary errors:
echo "YourTerm" >> .ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt
Style violations:
Vale will suggest the correct form. For example:
content/file.md:25:1: Use 'InfluxDB 3' instead of 'InfluxDB v3'
Simply make the suggested change.
False positives:
If Vale incorrectly flags something:
- Check if it's a new technical term that should be in vocabulary
- See if the rule needs refinement (consult vale-rule-config skill)
- Add inline comments to disable specific rules if necessary:
<!-- vale InfluxDataDocs.Spelling = NO -->
This paragraph contains technical terms that Vale might flag.
<!-- vale InfluxDataDocs.Spelling = YES -->
When to Run Vale
- Before committing: Pre-commit hooks run Vale automatically
- After content changes: Run manually to catch issues early
- In CI/CD: Automated on pull requests
Part 4: Fact-Checking with the Documentation MCP Server
The InfluxDB documentation MCP server lets you search InfluxDB documentation (the rendered content managed in this repository) and related InfluxData references (source code READMEs, community forums, and some third-party tool documentation) directly from your AI assistant.
When to Use the Documentation MCP Server
The primary source of content in the Documentation MCP Server is the fully rendered public HTML from this repository.
Use the Documentation MCP Server when the information here is inconclusive, when you need to deepen your understanding of InfluxData products and integrations, or when identifying content gaps in the documentation.
Use for:
- Verifying technical accuracy of claims
- Checking current API syntax
- Confirming feature availability across products
- Understanding complex product behavior
- Finding related documentation and code examples
- Identifying and analyzing content gaps in the documentation
Don't use for:
- Basic style/grammar checks (use Vale)
- Link validation (use
link-checker)
- Testing code examples (use
yarn test:codeblocks)
Setup
The documentation MCP server is hosted at https://influxdb-docs.mcp.kapa.ai—no local installation required.
Already configured in .mcp.json. Two server entries are available:
influxdb-docs (API key) — Set INFLUXDATA_DOCS_KAPA_API_KEY env var. 60 req/min.
influxdb-docs-oauth (OAuth) — No setup. Authenticates via Google or GitHub on first use. 40 req/hr, 200 req/day.
Available Tool
The MCP server exposes a semantic search tool:
search_influxdb_knowledge_sources
What it does:
- Searches all InfluxDB documentation for a given query
- Returns relevant chunks in descending order of relevance
- Each chunk includes
source_url and Markdown content
Example queries:
- "How do I create a database in InfluxDB 3 Core?"
- "What's the difference between InfluxDB 3 Core and Enterprise clustering?"
- "Show me InfluxQL SELECT syntax for filtering by time range"
Example Workflow: Fact-Checking During Editing
## Scenario: Editing database management documentation
1. Draft claims: "InfluxDB 3 supports up to 10,000 databases per instance"
2. Ask your AI assistant to verify using the MCP server:
"What are the database limits in InfluxDB 3 Core and Enterprise?"
3. MCP response returns documentation chunks with actual limits
4. Update draft with accurate information
5. Cite the source_url in documentation if needed
Best Practices
DO:
- Ask specific, focused questions
- Verify claims about features, limits, syntax
- Cross-check answers with source URLs provided
- Use for understanding complex interactions
DON'T:
- Rely solely on MCP without reviewing source docs
- Use for subjective style decisions
- Expect real-time product behavior (it searches documentation, not live systems)
- Use as a replacement for testing (always test code examples)
Part 5: Complete Example Workflows
Example 1: Creating New Multi-Product Documentation
docs create database-tutorial.md --products influxdb3_core,influxdb3_enterprise
yarn hugo --quiet
node cypress/support/run-e2e-specs.js \
content/influxdb3/core/guides/database-tutorial.md
yarn hugo --quiet
link-checker map content/influxdb3/core/guides/database-tutorial.md | \
xargs link-checker check
yarn test:codeblocks:all
Example 2: Editing Shared Content
docs edit https://docs.influxdata.com/influxdb3/core/reference/sql/
yarn hugo --quiet
node cypress/support/run-e2e-specs.js \
content/influxdb3/core/reference/sql/_index.md \
content/influxdb3/enterprise/reference/sql/_index.md
yarn hugo --quiet
link-checker map content/influxdb3/core/reference/sql/_index.md | \
xargs link-checker check
Example 3: Quick Fix Without CLI
yarn hugo --quiet
yarn hugo server
Part 6: Troubleshooting
| Problem | Solution |
|---|
| Hugo build fails | Run yarn hugo (no --quiet) for detailed errors — check frontmatter YAML, shortcode tags, partial refs |
| Shared content edits not appearing | Touch sourcing files: grep -r "source: /shared/path" content/ then touch each, or use docs edit |
| MCP not responding | Verify network allows *.kapa.ai; check rate limits (40 req/hr OAuth, 60 req/min API key); if using API key, verify INFLUXDATA_DOCS_KAPA_API_KEY is set |
| Cypress tests fail | See cypress-e2e-testing skill; check cat /tmp/hugo_server.log | tail -50, run yarn cypress open, run yarn build:api-docs if API content missing |
Part 7: Quick Reference
| Task | Command |
|---|
| Create new content | docs create draft.md --products <key-or-path> |
| Edit by URL | docs edit https://docs.influxdata.com/... |
| List files without editing | docs edit <url> --list |
| Add placeholders to code | docs placeholders file.md or docs placeholders file.md --dry |
| Audit documentation | docs audit --products influxdb3_core or docs audit --products /influxdb3/core |
| Generate release notes | docs release-notes v3.1.0 v3.2.0 --products influxdb3_core |
| Build Hugo site | yarn hugo --quiet |
| Run Vale linting | .ci/vale/vale.sh --config=.vale.ini content/path/ |
| Test links | link-checker map content/path/*.md | xargs link-checker check (build first) |
| Lint code block syntax | yarn lint-codeblocks content/path/*.md |
| Test code blocks | yarn test:codeblocks:all |
| Test specific page | yarn test:e2e content/path/file.md |
| Fact-check with MCP | Ask AI assistant with search_influxdb_knowledge_sources tool configured |
| Preview locally | yarn hugo server (visit localhost:1313) |
| Generate API docs | yarn build:api-docs (before API reference tests) |
Note: --products accepts both product keys (influxdb3_core) and content paths (/influxdb3/core).
Part 8: Security Review for Deployment and Install Docs
Install guides, deployment recipes, and runnable code samples can teach users
an insecure default without anyone intending it. Apply this lens whenever you
write or edit a guide that starts a service, publishes a port, or handles a
credential.
What to flag
- Ports published to all interfaces. A
docker run --publish 8888:8080 or
Compose "8888:8080" binds to 0.0.0.0 (all interfaces). For a UI or admin
service, default the example to the loopback interface
(127.0.0.1:8888:8080) and document how to widen exposure deliberately.
- Credentials entered into a network-reachable service without auth. If a
guide tells users to paste a token, password, or key into a service that has
no built-in authentication, state plainly that reaching the service equals
holding the credential, and recommend least-privilege credentials.
- Firewall assumptions. Docker port publishing adds its own firewall rules
and can bypass
ufw/firewalld. Don't imply a host firewall protects a
published port; tell users to verify reachability from another host.
- "Production" framing. Don't label a setup "production" if it only means
"run locally against a production instance." Say which one you mean.
- Recipes we don't test. Prefer describing a secure pattern (loopback +
authenticating reverse proxy + TLS) and linking to upstream docs over
shipping a full config we'd have to test and maintain in CI.
Apply it consistently for the reader
- Use a GitHub-flavored callout (
> [!Important] or > [!Caution]) with a
short #### sub-heading, placed where the user makes the decision (near the
first exposing example), not buried at the end.
- State the current behavior factually. Don't forecast or discount unreleased
fixes--alarmist or workaround-flavored copy ages badly and gets cached by
search engines and LLMs. Track product-side concerns in a separate issue.
- Make the safe path the copy-paste path. A loopback-bound example does more
than a paragraph of warning.
Related Skills
- docs-cli-workflow - When to use CLI vs direct editing (decision guidance)
- vale-linting - Running Vale, fixing flagged content, vocabulary, and product config (operator workflow)
- vale-rule-config - Authoring and testing custom Vale rules and regex (rule-author workflow)
- cypress-e2e-testing - Detailed Cypress test execution and debugging
- hugo-template-dev - Hugo template syntax and development
Checklist: Before Claiming Content is Complete