Docs Heading Drift Watch

Detects heading depth jumps and duplicate headings that break docs navigation.

Archetype: docs.qa (docs-quality)

Usage

Use the Command Palette (Ctrl/Cmd+Shift+P) and run the commands listed below.

Command surface

• docs-heading-drift-watch.auditHeadings - Audit heading structure: Find heading depth jumps and duplicate heading names.
• docs-heading-drift-watch.insertToc - Insert TOC from headings: Generate and insert a markdown TOC in the active file.

Why this extension exists

This archetype focuses on docs QA loops where broken links and heading drift hurt onboarding and release docs quality.

Checks included

• Broken local markdown link detection
• Heading hierarchy and duplicate heading checks
• TOC insertion for long documents

Recommended workflow

1. Run heading audit before merging docs-heavy PRs.
2. Run link audit before creating releases.
3. Insert TOC after large section edits.

Local development

npm install
npm run build
npm test

Use F5 in VS Code to launch an Extension Development Host.

Packaging

npm run package

Module notes

• UI settings are exposed in workspace settings under this extension namespace.
• Local run metadata uses ExtensionContext.globalState only.
• Analytics is local-only and disabled unless FOF_ANALYTICS_OPT_IN=true.

Marketplace submission notes

• Set a real publisher in package.json.
• Replace placeholder assets in assets/ (icon + screenshots).
• Upload .vsix or release source archive from dist-submission/.

Support

For support, contact support@example.com.