Skip to content

README.md

Latest commit

 

History

History
334 lines (239 loc) · 6.99 KB

README.md

File metadata and controls

334 lines (239 loc) · 6.99 KB

@goobits/docs-engine-cli

Command-line tools for managing and validating documentation built with @goobits/docs-engine.

Features

  • ✅ Link validation - Check internal and external links
  • 🔍 Anchor checking - Validate anchor links (#section)
  • 📁 File existence - Ensure linked files exist
  • 🌐 External validation - HTTP requests to validate external URLs
  • 📦 Version management - Manage multiple documentation versions
  • ⚡ Performance - Concurrent checking with configurable limits
  • 🎨 Beautiful output - Color-coded results with chalk
  • ⚙️ Configurable - Support for config files
  • 🔄 CI-friendly - JSON output and non-zero exit codes

Installation

pnpm add -D @goobits/docs-engine-cli
# or
npm install --save-dev @goobits/docs-engine-cli

Commands

Create a New Docs Site

Scaffold a new docs-engine project:

pnpm dlx @goobits/docs-engine-cli create-docs-engine my-docs
# or
npx -y @goobits/docs-engine-cli create-docs-engine my-docs

Link Checker

Check all links in your markdown documentation for broken internal references and optionally validate external URLs.

# Basic usage - check internal links
docs-engine check-links

# Check with external link validation
docs-engine check-links --external

# Custom base directory
docs-engine check-links --base-dir ./documentation

# Quiet mode (only show errors)
docs-engine check-links --quiet

# JSON output for CI integration
docs-engine check-links --json

Options:

  • -b, --base-dir <path> - Base directory for documentation (default: current directory)
  • -p, --pattern <glob> - Glob pattern for files to check (default: **/*.{md,mdx})
  • -e, --external - Validate external links (slower, default: false)
  • -t, --timeout <ms> - External link timeout in milliseconds (default: 5000)
  • -c, --concurrency <number> - Max concurrent external requests (default: 10)
  • -q, --quiet - Only show errors, hide valid links
  • --json - Output results as JSON
  • --config <path> - Path to config file

Exit Codes:

  • 0 - All links valid
  • 1 - Broken links found or error occurred

Version Management

Manage multiple versions of your documentation (similar to Docusaurus versioning).

Create Version

Create a new documentation version from current docs:

# Create version 2.0
docs-engine version create 2.0

# Create with custom docs directory
docs-engine version create 2.0 --docs-dir ./documentation

This will:

  1. Copy current docs to docs/versioned_docs/version-2.0/
  2. Update docs/versions.json with the new version
  3. Mark the new version as "latest"

List Versions

List all available documentation versions:

docs-engine version list

# Output:
#   2.0 [latest]
#   1.5 [stable]
#   1.0 [legacy]

Delete Version

Delete a documentation version:

docs-engine version delete 1.0

# Skip confirmation
docs-engine version delete 1.0 --force

Configuration

Config File

Create .docs-engine.json in your project root:

{
  "baseDir": ".",
  "pattern": "docs/**/*.{md,mdx}",
  "checkExternal": false,
  "timeout": 5000,
  "concurrency": 10,
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.git/**"
  ],
  "skipDomains": [
    "localhost",
    "127.0.0.1",
    "example.com"
  ],
  "validExtensions": [".md", ".mdx"]
}

Configuration Options:

  • baseDir (string): Base directory for documentation
  • pattern (string): Glob pattern for files to check
  • checkExternal (boolean): Whether to validate external links
  • exclude (string[]): Patterns to exclude from checking
  • timeout (number): Timeout for external requests in milliseconds
  • concurrency (number): Maximum concurrent external requests
  • skipDomains (string[]): Domains to skip validation
  • validExtensions (string[]): File extensions to treat as valid

CI Integration

GitHub Actions

name: Check Links

on: [push, pull_request]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install
      - run: pnpm docs-engine check-links

      # Optional: Check external links on schedule
      - name: Check external links
        if: github.event_name == 'schedule'
        run: pnpm docs-engine check-links --external

Pre-commit Hook

#!/bin/sh
docs-engine check-links --quiet || exit 1

Versioning Workflow

1. Initial Setup

Start with your documentation in docs/:

docs/
  getting-started.md
  api-reference.md
  guides/
    ...

2. Create First Version

When releasing v1.0:

docs-engine version create 1.0

This creates:

docs/
  current/              # Development version
  versioned_docs/
    version-1.0/        # v1.0 release
  versions.json         # Version metadata

3. Continue Development

Keep editing files in docs/current/ for the next release.

4. Release Next Version

When releasing v2.0:

docs-engine version create 2.0

Users can now view:

  • /docs/ - Latest (v2.0)
  • /docs/v2.0/ - v2.0 documentation
  • /docs/v1.0/ - v1.0 documentation

Link Validation Details

Internal Links

The link checker validates:

  • Relative links: ./page.md, ../other.md
  • Absolute links: /docs/page.md
  • Anchor links: #section, page.md#section
  • Markdown links: [text](url)
  • HTML links: <a href="url">
  • Image links: ![alt](image.png)

External Links

When --external is enabled:

  • ✅ HTTP/HTTPS URLs validated with HEAD/GET requests
  • ✅ Follow redirects (up to 5 hops)
  • ✅ Configurable timeout and concurrency
  • ✅ Result caching to avoid duplicate requests
  • ✅ Domain skipping for local/test URLs
  • ✅ Rate limiting to avoid overwhelming servers

Error Types

  • File not found - Internal link points to non-existent file
  • Anchor not found - Section anchor doesn't exist in target file
  • External error - HTTP error (404, 500, etc.)
  • Timeout - External URL didn't respond in time
  • Network error - Connection refused or DNS failure

Output Examples

Success Output

✔ Link checker initialized

📊 Checked 127 links across 45 files

✓ Valid: 125
⚠ Warnings: 2

All critical links are valid!

Error Output

✖ Link checker found errors

📊 Checked 127 links across 45 files

✓ Valid: 123
✗ Broken: 4

Broken Links:

src/content/docs/api.md:45
  → /docs/missing-page.md
  ✗ File not found

src/content/docs/guide.md:12
  → ./tutorial.md#non-existent
  ✗ Anchor #non-existent not found

src/content/docs/external.md:8
  → https://example.com/broken
  ✗ 404 Not Found

Development

# Install dependencies
pnpm install

# Build the CLI
pnpm build

# Test locally
node dist/index.js check-links

# Watch mode during development
pnpm dev

# Test the CLI
docs-engine check-links

License

MIT © GooBits