Docs Heading Structure Sentinel

Detects heading depth jumps and duplicate headings in documentation files.

Archetype: docs.qa (docs-quality)

Usage

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

Command surface

• docs-heading-structure-sentinel.auditLinks - Audit markdown links: Scan local markdown links and report unresolved paths.
• docs-heading-structure-sentinel.auditHeadings - Audit heading structure: Find heading depth jumps and duplicate heading names.
• docs-heading-structure-sentinel.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.