Skip to content

CLAUDE.md

Latest commit

 

History

History
179 lines (120 loc) · 7.51 KB

CLAUDE.md

File metadata and controls

179 lines (120 loc) · 7.51 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Netwrix Product Documentation — Claude Code Guide

A Docusaurus v3.8.1 site serving documentation for 27+ Netwrix security products across 6 categories, with multi-version support and a centralized configuration system.

Development Commands

npm run start          # Dev server on port 4500
npm run build          # Production build (16 GB heap pre-configured)
npm run clear          # Clear Docusaurus cache
npm run serve          # Serve production build after build

# Build/run a single product for faster iteration:
export DOCS_PRODUCT="pingcastle"
npm run start

# WSL or Docker (polling-based file watcher):
npm run start-chok

Available product IDs are defined in src/config/products.js.

KB script commands

npm run kb:dry         # Preview KB distribution without writing files
npm run kb:clean       # Remove all copied KB folders

# Filter to specific products or versions during local dev:
COPY_KB_PRODUCTS=accessanalyzer COPY_KB_VERSIONS=12.0 npm run start

Architecture

Single Source of Truth: src/config/products.js

All product and version configuration lives here. Never manually edit docusaurus.config.js to add products, routes, or plugins — products.js auto-generates all of that. Changing a product means changing this file.

Each product entry follows this structure:

{
  id: "accessanalyzer",           // URL-safe identifier, matches docs/<id>/ folder
  name: "Access Analyzer",        // Display name
  description: "...",
  path: "docs/accessanalyzer",
  versions: [
    { version: "12.0", label: "12.0", isLatest: true },
    { version: "11.6", label: "11.6", isLatest: false },
  ],
  categories: ["Data Security"],  // Must match a title in PRODUCT_CATEGORIES
}

Single-version (SaaS) products use version: "current" and docs/<product>/ without a version subfolder.

Versioned Documentation

Docs live at docs/<product>/<version>/ (for example, docs/accessanalyzer/12.0/). Edits to one version do not propagate to others — update each version that needs the change explicitly.

Sidebars

Each product version has a sidebar config in sidebars/<product>/<version>.js (or sidebars/<product>.js for single-version). These are separate from the doc content. Most use autogenerated and don't need manual editing unless custom ordering is required.

KB (Knowledge Base) System

docs/kb/ is the canonical source for KB articles. The script scripts/copy-kb-to-versions.mjs distributes articles into versioned product folders at build time (runs automatically as a pre-build step). The script uses a lockfile to prevent concurrent runs — if the build hangs after a crash, delete .kb-copy.lock.

Never manually copy KB articles into versioned product folders. Edit the source in docs/kb/ and control distribution via kb_allowlist.json.

Adding Content

New product

  1. Add an entry to the PRODUCTS array in src/config/products.js
  2. Create docs/<id>/
  3. Create sidebars/<id>.js

New version of an existing product

  1. Update the versions array for that product in src/config/products.js — set isLatest: true on the new version and isLatest: false on the previous one
  2. Create docs/<product>/<version>/
  3. Create sidebars/<product>/<version>.js

New product category

Add to the PRODUCT_CATEGORIES array in src/config/products.js.

Writing Style

The full standards are in netwrix_style_guide.md at the project root. Read it when in doubt.

Always run Vale before finishing any documentation edit. Run it iteratively — fix all reported issues, then run again until Vale reports zero errors. Fixes can occasionally introduce new violations.

vale <file>

Vale enforces 26 Netwrix-specific rules in CI. Rules are in .vale/styles/Netwrix/.

If Vale isn't installed, install it first:

# macOS
brew install vale

# Windows
choco install vale
# or download from https://github.com/errata-ai/vale/releases

# Linux
snap install vale --edge

Fixing Vale errors

Most errors are simple substitutions — Vale reports the exact file, line, and column. Three rules require extra care:

  • NoteThat — Replace inline "Note that..." or "Please note..." with a Docusaurus admonition block:

    :::note
Content here.
:::

    Use :::warning for warnings and :::tip for tips.

  • BoilerplateCrossRef and WeakLinkText — Read the surrounding context and the link destination before rewriting. The fix must reflect what the reader will actually find at the destination.

  • ImpersonalConstructions — Read the full sentence before rewriting. Restructure with an active subject rather than simply removing the flagged phrase.

Rules Vale doesn't catch

Vale handles pattern-based violations automatically — run it and fix everything it reports. The following rules require judgment that Vale can't apply:

Voice and structure

  • Active voice and present tense throughout
  • Second person ("you") or imperative mood for procedures and instructions — third person ("users") is acceptable in overviews and conceptual descriptions
  • Contractions are encouraged: don't, can't, you'll
  • Write for a global audience — avoid metaphors, idioms, and culturally specific references that don't translate
  • Omit "currently", "presently", and "as of this writing" — documentation should read as permanently accurate

Document structure

  • Order: overview → prerequisites → procedures
  • Task headings use imperative verbs: "Configure the monitoring plan"
  • Concept/overview headings use gerunds: "Configuring the monitoring plan"
  • Examples immediately follow the concept they illustrate
  • Images: store in static/img/product_docs/<product>/, use .webp, reference with absolute paths (/img/product_docs/...)

Terminology

  • Spell out acronyms on first use: "group Managed Service Account (gMSA)"
  • Use angle brackets for placeholders: <report-name> not [report-name]
  • Sentence case for feature names; capitalize Netwrix product names correctly
  • Oxford comma required in lists

CI/CD Context

Vale linter — runs on every PR touching .md files, posts inline review comments. Does not block merges but issues are visible.

Doc reviewer (Claude Sonnet 4.5) — runs on every PR, reads this CLAUDE.md first, then categorizes issues as "in PR changes" vs "preexisting" and posts inline suggestions reviewers can apply with one click.

Doc fixer — triggered by an @claude comment on a PR. Claude applies fixes and pushes. Fork PRs cannot be pushed to and receive a notice instead.

Docusaurus developer — triggered when an issue receives the AI:docusaurus label. Claude implements the requested change (JS/TS/CSS/JSON only — not markdown), creates a branch from dev, and opens a PR linked to the issue.

Auto-sync — dev merges to main automatically each day at 8 AM PST if the build passes. Production deployment follows automatically.

Branch workflow — PRs target dev. Merges to main trigger production deployment.

Common Mistakes to Avoid

  • Don't add products or routes by editing docusaurus.config.js — use src/config/products.js
  • Don't copy KB content manually into versioned product folders — it's managed by the KB script
  • Don't skip Vale before submitting — it will catch issues in CI anyway
  • Don't commit directly to dev or main — if not already on a feature branch, create one from dev first
  • Don't target main in PRs — use dev