Efficient Docs Handler

Process, validate, and organize project documentation with automated quality checks and cross-reference verification.

When to Use This Command

Run this command when you need to:

• Audit existing documentation for broken links, outdated references, and formatting issues
• Organize scattered documentation files into a consistent structure with navigation
• Validate that code examples in documentation actually compile and run correctly

Consider alternatives when:

• You need to write new documentation content from scratch rather than organize existing docs
• You are working with a documentation platform that has its own validation tools

Quick Start

Configuration

Copy
name: efficient-docs-handler
type: command
category: documentation

Example Invocation

Copy
claude command:run efficient-docs-handler --action validate --path docs/

Example Output

Documentation Audit: docs/ (34 files, 12,800 words)

Validation Results:
  [PASS] Markdown formatting: 34/34 files valid
  [FAIL] Broken links: 7 found
         - docs/api.md:42 -> /guides/auth.md (file not found)
         - docs/setup.md:18 -> https://old-domain.com/install (404)
         - docs/faq.md:55 -> #troubleshooting (anchor not found)
  [WARN] Outdated code examples: 3 found
         - docs/quickstart.md:23 uses deprecated API v1 syntax
  [PASS] Image references: 12/12 images accessible
  [WARN] No table of contents in 8 files over 500 words

Summary: 27 passed, 5 warnings, 7 failures
Auto-fixable: 4 broken internal links (relative path corrections)

Core Concepts

Documentation Quality Overview

Aspect	Details
Link Validation	Checks internal file links, anchor links, and external URLs
Code Verification	Validates that code blocks use correct syntax and current APIs
Format Consistency	Enforces heading hierarchy, list formatting, and spacing rules
Structure Analysis	Evaluates table of contents, navigation, and cross-references
Freshness Check	Compares doc modification dates against source code changes

Documentation Processing Workflow

  Documentation Files
        |
        v
  +-------------------+
  | Parse Markdown    |---> Extract links, code, headings
  +-------------------+
        |
        v
  +-------------------+
  | Validate Links    |---> Internal, external, anchors
  +-------------------+
        |
        v
  +-------------------+
  | Check Code Blocks |---> Syntax, API version, runnable
  +-------------------+
        |
        v
  +-------------------+
  | Assess Structure  |---> TOC, navigation, hierarchy
  +-------------------+
        |
        v
  +-------------------+
  | Generate Report   |---> PASS / WARN / FAIL per file
  +-------------------+

Configuration

Parameter	Type	Default	Description
action	string	validate	Action to perform: validate, organize, fix, report
path	string	docs/	Directory containing documentation files to process
check_external	boolean	true	Whether to validate external URLs (slower but thorough)
auto_fix	boolean	false	Automatically fix correctable issues like broken relative links
max_age_days	integer	90	Flag documents not updated within this many days as stale

Best Practices

1. Run Validation in CI - Add documentation validation to your CI pipeline so broken links and formatting issues are caught before merging. Treating docs as code prevents documentation rot.

2. Fix Broken Links Immediately - A developer who clicks a broken documentation link loses trust in all documentation. Fix link issues as soon as they are reported rather than letting them accumulate.

3. Keep Code Examples Executable - Documentation code blocks should be tested against the current version of the API. Consider extracting code examples into test files that are verified during the build process.

4. Add Last-Updated Metadata - Include a last-updated date in each documentation file. This helps readers gauge whether information is current and helps maintainers identify stale content.

5. Use Relative Links for Internal Docs - Always use relative paths for links between documentation files. Absolute paths break when the documentation is hosted at different base URLs or read locally.

Common Issues

1. External Link Checks Time Out - Validating hundreds of external URLs takes too long. Run external link checks on a nightly schedule rather than on every commit, and cache results to avoid redundant requests.

2. False Positives on Authenticated URLs - Links behind authentication (Jira, Confluence, internal wikis) report as 404 or 403. Maintain a whitelist of known-authenticated domains that should be skipped during validation.

3. Markdown Formatter Conflicts - The auto-fix reformats documentation in ways that conflict with the project's prettier or markdownlint configuration. Ensure the handler uses the same formatting rules as the project's existing tools.