Content Editing

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:

# Create new documentation from draft
docs create <draft-path> --products <product-key>

# Edit existing documentation by URL or path
docs edit <url-or-path>

# List files without opening editor (agent-friendly)
docs edit <url-or-path> --list

# Add placeholder syntax to code blocks
docs placeholders <file.md>

# Important: Both commands are non-blocking by default
# - Launch editor in background
# - Return immediately (agent-friendly)
# - Use --wait flag for blocking behavior

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:

# Manual approach
touch content/influxdb3/core/admin/databases.md
touch content/influxdb3/enterprise/admin/databases.md

Automatic (Recommended)

Use docs edit - it handles this automatically:

# This command will:
# 1. Find the shared source file
# 2. Find ALL frontmatter files that reference it
# 3. Open all files for editing
# 4. You edit the shared file
# 5. Hugo sees changes to frontmatter files and rebuilds

docs edit /influxdb3/core/admin/databases/

Programmatic Detection

If you need to handle this in code:

// Check if a file is a sourcing file (frontmatter only)
import { readFileSync } from 'fs';
import matter from 'gray-matter';

function isSharedContent(filePath) {
  const content = readFileSync(filePath, 'utf8');
  const { data, content: body } = matter(content);

  // If has source: frontmatter and minimal/no body content
  return data.source && body.trim().length < 50;
}

function getSharedSource(filePath) {
  const content = readFileSync(filePath, 'utf8');
  const { data } = matter(content);
  return data.source; // e.g., "/shared/influxdb3/admin/databases.md"
}

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)

# Verify Hugo can build the site
yarn hugo --quiet

# Look for errors like:
# - Template errors
# - Missing partials
# - Invalid frontmatter
# - Broken shortcodes

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.

# Build the site (link-checker reads public/ HTML)
yarn hugo --quiet

# Map changed Markdown to public HTML, then check the links
link-checker map content/influxdb3/core/path/*.md | xargs link-checker check

# Or check a built HTML subtree directly
link-checker check public/influxdb3/core/get-started/

# This checks:
# - Internal links (relative paths)
# - Cross-references
# - Anchor links

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.

# Lint changed content files (exits 1 if any JSON/YAML/TOML block fails)
yarn lint-codeblocks content/influxdb3/core/admin/tokens/*.md

# Run the linter's own test suite
yarn test:lint-codeblocks

Blocking policy (mirrors CI):

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)

# Test all code examples in documentation
yarn test:codeblocks:all

# Tests code blocks marked with:
# - testable: true
# - Validates syntax
# - Can execute examples (for supported languages)

5. E2E Testing (For Specific Pages)

Use the cypress-e2e-testing skill for comprehensive page testing:

# Test specific content file
node cypress/support/run-e2e-specs.js content/influxdb3/core/admin/databases/_index.md

# Test API reference pages (requires yarn build:api-docs first)
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:

# Lint specific files
.ci/vale/vale.sh --config=.vale.ini content/influxdb3/core/path/to/file.md

# Lint with minimum alert level
.ci/vale/vale.sh --config=.vale.ini --minAlertLevel=warning content/path/

# Sync Vale packages (after .vale.ini changes)
.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)

# Start Hugo development server
yarn hugo server

# Visit http://localhost:1313
# Preview your changes in browser

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

# Basic linting (all markdown files)
.ci/vale/vale.sh content/**/*.md

# Lint specific product
.ci/vale/vale.sh content/influxdb3/core/**/*.md

# With specific config and alert level
.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:

# If Vale flags a legitimate term, add it to vocabulary
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:

1. Check if it's a new technical term that should be in vocabulary
2. See if the rule needs refinement (consult vale-rule-config skill)
3. 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

# Step 1: Create content from draft
docs create database-tutorial.md --products influxdb3_core,influxdb3_enterprise

# CLI scaffolds files:
# - content/shared/influxdb3/guides/database-tutorial.md
# - content/influxdb3/core/guides/database-tutorial.md (frontmatter)
# - content/influxdb3/enterprise/guides/database-tutorial.md (frontmatter)

# Step 2: Verify technical accuracy
# Ask your AI assistant (with MCP configured) to verify claims:
# "Verify database creation syntax for InfluxDB 3"

# Step 3: Test Hugo build
yarn hugo --quiet

# Step 4: Run E2E tests
node cypress/support/run-e2e-specs.js \
  content/influxdb3/core/guides/database-tutorial.md

# Step 5: Validate links (build first, then map + check)
yarn hugo --quiet
link-checker map content/influxdb3/core/guides/database-tutorial.md | \
  xargs link-checker check

# Step 6: Test code examples (if tutorial has code blocks)
yarn test:codeblocks:all

Example 2: Editing Shared Content

# Step 1: Find and edit the content
docs edit https://docs.influxdata.com/influxdb3/core/reference/sql/

# CLI automatically:
# - Finds content/shared/influxdb3/reference/sql/_index.md
# - Finds ALL frontmatter files referencing it:
#   * content/influxdb3/core/reference/sql/_index.md
#   * content/influxdb3/enterprise/reference/sql/_index.md
#   * content/influxdb3/cloud-dedicated/reference/sql/_index.md
# - Opens all files (sourcing files will be touched when saved)

# Step 2: Make edits to the shared source file

# Step 3: Fact-check changes with MCP
# Ask your AI assistant: "Verify SQL WHERE clause syntax in InfluxDB 3"

# Step 4: Test the build
yarn hugo --quiet

# Step 5: Test affected pages
node cypress/support/run-e2e-specs.js \
  content/influxdb3/core/reference/sql/_index.md \
  content/influxdb3/enterprise/reference/sql/_index.md

# Step 6: Validate links in SQL reference (build first, then map + check)
yarn hugo --quiet
link-checker map content/influxdb3/core/reference/sql/_index.md | \
  xargs link-checker check

Example 3: Quick Fix Without CLI

# Step 1: Fix typo directly (you know the file)
# Edit content/influxdb3/core/get-started/_index.md

# Step 2: Test Hugo build
yarn hugo --quiet

# Step 3: Quick visual check
yarn hugo server
# Visit http://localhost:1313/influxdb3/core/get-started/

# Done! (No need for comprehensive testing on typo fixes)

Part 6: Troubleshooting

Part 7: Quick Reference

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

• Content created/edited using appropriate method (CLI or direct)
• If shared content: Sourcing files touched (or used docs edit)
• If shared content: Check for path differences and add alt_links if paths vary
• Technical accuracy verified (MCP fact-check if needed)
• Hugo builds without errors (yarn hugo --quiet)
• Vale style linting passes (.ci/vale/vale.sh --config=.vale.ini content/path/)
• Links validated (link-checker — see DOCS-TESTING.md)
• Code examples tested (if applicable)
• E2E tests pass for affected pages
• Visual preview confirms changes look correct
• If the guide starts a service, publishes a port, or handles a credential: security review applied (see Part 8)
• Related documentation updated (if needed)