{"id":38281026,"url":"https://github.com/radleta/mdite","last_synced_at":"2026-01-20T16:57:32.314Z","repository":{"id":318751576,"uuid":"1076337892","full_name":"radleta/mdite","owner":"radleta","description":"Markdown documentation toolkit: Treats your docs as a connected graph. Validates links, detects orphans, maps dependencies. Refactor with confidence.","archived":false,"fork":false,"pushed_at":"2025-11-04T19:02:00.000Z","size":572,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T20:14:59.126Z","etag":null,"topics":["ci-cd","cli-tool","dependency-analysis","developer-tools","devops","documentation","documentation-graph","documentation-management","documentation-tools","link-checker","markdown","markdown-linter","markdown-validator","nodejs","static-analysis","technical-documentation","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radleta.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T18:06:53.000Z","updated_at":"2025-11-04T18:52:32.000Z","dependencies_parsed_at":"2025-10-18T08:40:23.883Z","dependency_job_id":null,"html_url":"https://github.com/radleta/mdite","commit_stats":null,"previous_names":["radleta/doc-lint","radleta/mdite"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/radleta/mdite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fmdite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fmdite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fmdite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fmdite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radleta","download_url":"https://codeload.github.com/radleta/mdite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fmdite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T00:50:05.742Z","status":"ssl_error","status_checked_at":"2026-01-17T00:43:11.982Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci-cd","cli-tool","dependency-analysis","developer-tools","devops","documentation","documentation-graph","documentation-management","documentation-tools","link-checker","markdown","markdown-linter","markdown-validator","nodejs","static-analysis","technical-documentation","typescript"],"created_at":"2026-01-17T01:58:43.101Z","updated_at":"2026-01-17T01:58:43.820Z","avatar_url":"https://github.com/radleta.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdite\n\n---\n\n\u003e ⚙️ **Built with AI-Paired Development**\n\u003e This project was rapidly developed using AI-assisted workflows (Claude Code, Gemini, ChatGPT) under my direction. While it contains known bugs and rough edges due to scope and velocity, it reflects real-world utility and has been validated through integration tests and end-user use. Architecture and system behavior were guided and owned by me.\n\n---\n\n[![CI](https://github.com/radleta/mdite/actions/workflows/ci.yml/badge.svg)](https://github.com/radleta/mdite/actions/workflows/ci.yml)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Markdown documentation toolkit** - Work with your documentation as a connected system, not scattered files.\n\nmdite treats your markdown documentation as a cohesive whole. Map dependencies, validate structure, search across files, and pipe content—all while understanding how your docs connect together.\n\nThis version:\n\n* Sets accurate expectations: the project is pragmatic, not polished\n* Signals you're aware of trade-offs and made deliberate choices\n* Keeps the tone professional and confident—you're owning the process, not apologizing for it\n\nYou could also link to an optional `KNOWN_ISSUES.md` file if you want to invite community feedback or show a roadmap.\n\nLet me know if you want a shorter or badge-friendly variant.\n\n**Next best move →** Replace or add this updated banner to the top of your AI-assisted project READMEs.\n\n\n---\n\n## The Vision\n\nMost tools treat markdown files as isolated documents. mdite treats them as a **connected system**.\n\n### Current Reality\n\n- 📄 Edit files one at a time\n- 🔍 grep individual files, hope you find everything\n- 🤷 No idea what's connected to what\n- 💥 Break things when refactoring\n- 🗑️ Afraid to delete anything\n\n### With mdite\n\n- 🕸️ **See the whole system** - Your docs are a graph, visualize it\n- 🔍 **Search the system** - Query across all connected docs\n- 📊 **Understand dependencies** - Know what links to what\n- ✅ **Validate structure** - Catch broken links and orphans\n- 🎯 **Work confidently** - Refactor and clean up without fear\n\n---\n\n## What mdite Does\n\nmdite is a toolkit for working with markdown documentation as a unified system:\n\n### 📊 Map \u0026 Analyze (`deps`)\n\n```bash\n# See what connects to what\nmdite deps docs/api.md --incoming\n\n# Understand your doc structure\nmdite deps README.md --format tree\n```\n\n### ✅ Validate \u0026 Lint (`lint`)\n\n```bash\n# Catch broken links and orphans\nmdite lint\n\n# CI/CD integration\nmdite lint --format json\n```\n\n### 📋 List Files (`files`)\n\n```bash\n# List all reachable files\nmdite files\n\n# Filter by depth\nmdite files --depth 2\n\n# Search with ripgrep (Unix composition)\nmdite files | xargs rg \"authentication\"\n\n# Filter by frontmatter and process\nmdite files --frontmatter \"status=='published'\" | xargs prettier --write\n```\n\n### 📤 Export \u0026 Pipe (`cat`)\n\n```bash\n# Output entire doc system\nmdite cat | less\n\n# Pipe to shell tools\nmdite cat docs/api/*.md | grep \"function\"\n\n# Combine with other tools\nmdite cat --order deps | pandoc -o book.pdf\n```\n\n**The key:** mdite understands how your docs connect, so it can treat them as a unified system.\n\n---\n\n## Quick Start\n\n### Installation\n\n\u003e **Note:** mdite will be published to npm with the first release. Once published, install via:\n\n```bash\nnpm install -g mdite\n```\n\n\u003e For now, you can clone and build from source: `git clone https://github.com/radleta/mdite.git \u0026\u0026 cd mdite \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 npm link`\n\n### Three Core Workflows\n\n#### 1. Understand Your Docs (Graph Analysis)\n\n```bash\n# Map the structure\nmdite deps README.md\n\n# What references this file?\nmdite deps docs/api.md --incoming\n\n# What does this file reference?\nmdite deps docs/guide.md --outgoing\n```\n\n**Use case:** Before changing anything, understand the impact.\n\n#### 2. Validate Your Docs (Linting)\n\n```bash\n# Check for issues\nmdite lint\n\n# Find orphaned files\nmdite lint --verbose\n\n# CI/CD integration\nmdite lint --format json\n```\n\n**Use case:** Catch broken links and structural issues.\n\n#### 3. Configure (Optional)\n\n```bash\n# Create custom config\nmdite init\n\n# See merged config\nmdite config\n```\n\n**Use case:** Customize for your project's needs.\n\n---\n\n## Core Features\n\n### 🕸️ Documentation as a Graph\n\nmdite builds a complete dependency graph of your documentation starting from an entrypoint (usually `README.md`), following all internal links.\n\n**Why this matters:** You can see exactly how your docs connect. No more guessing about structure or dependencies.\n\n```bash\nmdite deps README.md\n# Output:\n# README.md\n# ├── docs/getting-started.md\n# │   ├── docs/installation.md\n# │   └── docs/configuration.md\n# ├── docs/api-reference.md\n# └── docs/guides/\n```\n\n**This graph is the foundation** for everything mdite does - validation, analysis, search, export.\n\n### 📊 Dependency Analysis\n\nUnderstand what connects to what before making changes:\n\n```bash\n# Impact analysis: What will break if I change this?\nmdite deps docs/api.md --incoming\n# Shows: README.md, guide.md, tutorial.md all reference it\n\n# Scope analysis: What does this file depend on?\nmdite deps docs/guide.md --outgoing\n# Shows: Links to setup.md, api.md, troubleshooting.md\n```\n\n**Real-world use cases:**\n\n- 🔧 **Refactoring:** Know the impact before renaming/moving files\n- 🧹 **Cleanup:** Find files that nothing depends on (safe to delete)\n- 📖 **Documentation:** Understand your doc structure\n- 🎯 **Navigation:** Find central hub documents\n\n### ✅ Structure Validation\n\nCatch issues before they reach users:\n\n**Orphan Detection:**\nFind markdown files that aren't linked from anywhere—dead weight in your repo.\n\n```bash\nmdite lint\n# ✗ Found 3 orphaned files:\n#   - old-guide.md\n#   - deprecated-api.md\n#   - scratch-notes.md\n```\n\n**Link Validation:**\nValidates three types of links:\n\n- **File links:** `[guide](./setup.md)` → validates file exists\n- **Anchor links:** `[intro](#getting-started)` → validates heading exists\n- **Cross-file anchors:** `[api](./api.md#methods)` → validates both\n\n**Benefit:** Zero 404s in your documentation.\n\n### 🔍 System-Wide Operations\n\nBecause mdite understands your docs as a system, it can do things other tools can't:\n\n**Export the system:**\n\n```bash\n# Output entire doc system in dependency order\nmdite cat --order deps\n\n# Output in alphabetical order\nmdite cat --order alpha\n\n# Pipe to shell tools\nmdite cat | grep -n \"TODO\"\nmdite cat | wc -l  # Total lines in doc system\n\n# Export as single file\nmdite cat --order deps | pandoc -o documentation.pdf\n\n# JSON format with metadata\nmdite cat --format json | jq '.[] | {file, wordCount}'\n```\n\n**Coming Soon:**\n\n\u003e ⚠️ **Note:** The following features are planned but not yet implemented. They are shown here to illustrate the project's vision.\n\n**Search across the system:**\n\n```bash\n# FUTURE FEATURE - not yet available\n# Find all docs mentioning \"authentication\"\nmdite query \"authentication\" --content\n\n# Find docs matching name pattern\nmdite query \"api-*\" --names\n\n# Search in a specific section of the graph\nmdite query \"config\" --from docs/reference/\n```\n\n**Transform the system:**\n\n```bash\n# FUTURE FEATURE - not yet available\n# Generate table of contents from graph\nmdite toc --depth 2\n\n# Validate external links (HTTP/HTTPS)\nmdite lint --external\n```\n\n---\n\n## Why mdite?\n\n### The Problem: Documentation is a System, But Tools Treat It Like Files\n\nYou have 50 markdown files that form a cohesive documentation site, but:\n\n- ❌ You edit them one at a time (disconnected)\n- ❌ You search them one at a time (`grep file1.md`, `grep file2.md`...)\n- ❌ You have no idea how they connect\n- ❌ Refactoring is terrifying (what will break?)\n- ❌ You don't know what's safe to delete\n\n**mdite solves this by treating your docs as a connected graph.**\n\n### What Makes mdite Different?\n\n| Capability                | Traditional Tools                | mdite                           |\n| ------------------------- | -------------------------------- | ------------------------------- |\n| **Link validation**       | ❌ Can't detect broken links     | ✅ Validates all internal links |\n| **Orphan detection**      | ❌ No concept of reachability    | ✅ Finds unreachable files      |\n| **Dependency analysis**   | ❌ No understanding of structure | ✅ Maps entire graph            |\n| **System-wide search**    | ❌ Search files individually     | ✅ Query the whole system       |\n| **Structural operations** | ❌ File-by-file only             | ✅ Operates on connected docs   |\n\n### vs. Traditional Markdown Linters\n\n**markdownlint / remark-lint:**\n\n- ✅ Check style (formatting, syntax)\n- ❌ Don't understand document relationships\n- ❌ Can't detect orphaned files\n- ❌ Miss structural issues\n- ❌ File-centric, not system-centric\n\n**mdite:**\n\n- ✅ Validates structure and relationships\n- ✅ Detects orphaned files\n- ✅ Maps dependencies\n- ✅ System-centric operations\n- ✅ Understands your docs as a connected whole\n\n**Use both:** Traditional linters for style, mdite for structure and system operations.\n\n---\n\n## Real-World Workflows\n\n### 1. Safe Refactoring\n\n```bash\n# Step 1: Understand the impact\nmdite deps docs/old-api.md --incoming\n# Shows: README.md, tutorial.md, guide.md reference it\n\n# Step 2: Rename the file\nmv docs/old-api.md docs/api-reference.md\n\n# Step 3: Update the 3 files that link to it\n\n# Step 4: Validate\nmdite lint\n# ✅ All links valid\n```\n\n**Benefit:** Refactor with confidence, not fear.\n\n### 2. Documentation Spring Cleaning\n\n```bash\n# Find orphaned files\nmdite lint\n# ✗ Found 5 orphaned files\n\n# Review each one\nmdite deps old-guide.md --incoming\n# Shows: nothing links to it\n\n# Safe to delete!\nrm old-guide.md deprecated-api.md scratch-notes.md\n\n# Verify\nmdite lint\n# ✅ All clean, only connected docs remain\n```\n\n**Benefit:** Clean repos, confident deletions.\n\n### 3. Pre-Release Documentation Check\n\n```bash\n# Validate structure\nmdite lint\n\n# Check for orphans (incomplete docs)\nmdite lint --verbose | grep \"orphan\"\n\n# Verify all API docs are reachable\nmdite deps README.md --format list | grep \"api\"\n\n# Green light to release\nmdite lint --format json\n# Exit code 0 = ship it\n```\n\n**Benefit:** Never ship broken documentation.\n\n### 4. Understanding a New Codebase\n\n```bash\n# Start at the entry point\nmdite deps README.md --depth 1\n# Shows: Top-level structure\n\n# Explore a section\nmdite deps docs/architecture.md\n# Shows: What it connects to\n\n# Find all API docs\nmdite deps README.md --format list | grep api\n# Lists all API documentation files\n```\n\n**Benefit:** Quickly understand documentation structure.\n\n### 5. CI/CD Quality Gate\n\n```yaml\n# .github/workflows/docs.yml\nname: Documentation Quality\n\non: [pull_request]\n\njobs:\n  validate-docs:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - run: npm install -g mdite\n      - run: mdite lint --format json\n      # Fails if broken links or orphans detected\n```\n\n**Benefit:** Documentation quality is enforced, not hoped for.\n\n### 6. Unix Tool Integration (Piping \u0026 Scripting)\n\n```bash\n# Find all files with broken links\nmdite lint | grep \"Dead link\" | cut -d: -f1 | sort | uniq\n\n# Count errors by type\nmdite lint | grep -o \"\\\\[.*\\\\]\" | sort | uniq -c\n\n# Get JSON summary with jq\nmdite lint --format json | jq '[.[] | .severity] | group_by(.) | map({severity: .[0], count: length})'\n\n# List all orphaned files\nmdite lint --format json | jq -r '.[] | select(.rule==\"orphan-files\") | .file'\n\n# Check if specific file has errors\nmdite lint | grep \"docs/api.md\" \u0026\u0026 echo \"API docs need fixing\"\n\n# Quiet mode for scripting (no progress messages)\nERRORS=$(mdite lint --quiet 2\u003e/dev/null)\nif [ -n \"$ERRORS\" ]; then\n  echo \"$ERRORS\" | mail -s \"Doc errors\" team@example.com\nfi\n\n# Analyze dependencies\nmdite deps README.md --format json | jq '.stats.totalFiles'\n\n# Find deeply nested docs\nmdite deps README.md --format json | jq '.outgoing[] | select(.depth \u003e 3) | .file'\n\n# Export dependency graph as CSV\nmdite deps README.md --format json | jq -r '.outgoing[] | [.file, .depth] | @csv'\n```\n\n**Benefit:** Full integration with Unix ecosystem (grep, jq, awk, sed, mail, etc.)\n\n### 7. Automated Link Fixing with Grep Format\n\n```bash\n# Find all dead links with literal paths (grep format)\nmdite lint --format grep \u003e dead-links.tsv\n\n# Extract just the literal link text (field 7)\nmdite lint --format grep | cut -d$'\\t' -f7\n\n# Extract file, line, and literal for manual fixing\nmdite lint --format grep | awk -F'\\t' '{print $1 \":\" $2 \" → \" $7}'\n\n# Automated fix workflow example\nmdite lint --format grep | while IFS=$'\\t' read file line col endCol severity rule literal resolved; do\n  if [ \"$rule\" = \"dead-link\" ]; then\n    echo \"Fix: $file:$line - Replace '$literal' with correct path\"\n    # Add your automated fix logic here (sed, etc.)\n  fi\ndone\n\n# Extract broken links by file\nmdite lint --format grep | awk -F'\\t' '$6==\"dead-link\" {print $1, $7}' | sort\n\n# Count broken links by type\nmdite lint --format grep | cut -d$'\\t' -f6 | sort | uniq -c\n```\n\n**Benefit:** Automated fix scripts can locate and replace broken links using exact text from source files, no path reverse-engineering needed.\n\n### 8. Progressive Validation\n\n```bash\n# Start with core docs only\nmdite lint --depth 1\n\n# Gradually expand validation\nmdite lint --depth 2\nmdite lint --depth 3\n\n# Finally, full validation\nmdite lint\n```\n\n**Benefit:** Incremental adoption of mdite in large doc repos, validate core docs first.\n\n---\n\n## Commands\n\n### Global Options\n\nThese options work with all commands:\n\n- `--config \u003cpath\u003e` - Path to custom config file\n- `--colors` - Force colored output (even when piped)\n- `--no-colors` - Disable colored output\n- `-q, --quiet` - Quiet mode (suppress informational output, show only data/errors)\n- `--verbose` - Enable verbose/debug output\n- `-V, --version` - Output the version number\n- `-h, --help` - Display help for command\n\n**Usage:**\n\n```bash\n# Use verbose mode with any command\nmdite lint --verbose\nmdite deps README.md --verbose\n\n# Quiet mode for scripting (only data/errors, no info messages)\nmdite lint --quiet\nmdite deps README.md --quiet --format json | jq '.stats'\n\n# Use custom config with any command\nmdite lint --config custom-config.js\nmdite init --config .mditerc.json\n\n# Control colors\nmdite lint --no-colors              # Disable colors\nmdite lint --colors | less -R       # Force colors even when piped\n```\n\n**Color Detection:**\n\nmdite automatically detects whether colors should be used:\n\n- **Auto-enabled** when output is a terminal (TTY)\n- **Auto-disabled** when piped to other tools\n- **Force with `--colors`** to override detection\n- **Disable with `--no-colors`** or `NO_COLOR=1` env var\n\n**Environment Variables:**\n\n- `NO_COLOR` - Disable colors (respects [no-color.org](https://no-color.org) standard)\n- `FORCE_COLOR` - Force colors even when not a TTY\n- `CI=true` - Disables colors in CI environments (unless `FORCE_COLOR` is set)\n\n### `mdite deps \u003cfile\u003e` - Analyze Dependencies\n\nVisualize and analyze documentation structure.\n\n```bash\n# Tree view of dependencies\nmdite deps README.md\n\n# What references this file? (incoming)\nmdite deps docs/api.md --incoming\n\n# What does this file reference? (outgoing)\nmdite deps docs/guide.md --outgoing\n\n# Limit depth\nmdite deps README.md --depth 2\n\n# JSON output for tooling\nmdite deps docs/api.md --format json\n\n# List format\nmdite deps README.md --format list\n```\n\n**Options:**\n\n- `--incoming` - Show what references this file\n- `--outgoing` - Show what this file references\n- `--depth \u003cn\u003e` - Limit traversal depth\n- `--format \u003ctype\u003e` - Output: `tree` (default), `list`, or `json`\n\n**Use cases:**\n\n- 🔍 Impact analysis before refactoring\n- 🧹 Finding safe-to-delete files\n- 📊 Understanding documentation structure\n- 🎯 Identifying central hub documents\n\n### `mdite lint [path]` - Validate Structure\n\nCheck documentation for structural issues.\n\n```bash\n# Lint from current directory\nmdite lint\n\n# Lint specific directory\nmdite lint ./docs\n\n# JSON output for CI/CD (auto-disables colors)\nmdite lint --format json\n\n# Grep format for automated fixes (tab-delimited)\nmdite lint --format grep\n\n# Extract all literal paths\nmdite lint --format grep | cut -d$'\\t' -f7\n\n# Extract file and literal for processing\nmdite lint --format grep | awk -F'\\t' '{print $1, $7}'\n\n# Pipe JSON to jq for analysis\nmdite lint --format json | jq '.[] | select(.severity==\"error\")'\n\n# Quiet mode for scripting (only errors shown)\nmdite lint --quiet\n\n# Verbose output (shows debug info to stderr)\nmdite lint --verbose\n\n# NEW: Lint multiple files as entry points\nmdite lint README.md docs/api.md docs/guide.md --depth 1\n\n# Perfect for pre-commit hooks (lint only changed files)\nCHANGED=$(git diff --cached --name-only --diff-filter=ACM | grep '\\.md$')\nmdite lint $CHANGED --depth 1\n```\n\n#### Multi-File Validation (NEW)\n\nLint multiple specific files as independent entry points:\n\n```bash\n# Lint multiple entry points\nmdite lint core/api.md core/cli.md core/config.md\n\n# Each file starts at depth 0\n# Results are merged and deduplicated\n# Orphans = files not reachable from ANY entry point\n```\n\n**Use Cases:**\n\n- **Pre-commit hooks:** Lint only changed markdown files\n- **Selective validation:** Check specific docs without full traversal\n- **CI/CD:** Parallel validation of independent sections\n- **Author workflow:** Work on multiple related docs\n\n**Example:**\n\n```bash\n# Pre-commit: validate changed files and their immediate links\nmdite lint $(git diff --cached --name-only | grep '\\.md$') --depth 1\n```\n\n**Options:**\n\n- `--format \u003ctype\u003e` - Output: `text` (default), `json`, or `grep`\n- `--entrypoint \u003cfile\u003e` - Entrypoint file (overrides config, cannot be used with multiple files)\n- `--depth \u003cn\u003e` - Maximum depth of traversal (default: unlimited, applies to all files)\n- `-q, --quiet` - Suppress informational output (only show errors)\n\n**Global options** (apply to all commands):\n\n- `--config \u003cpath\u003e` - Custom config file\n- `--no-colors` - Disable colored output\n- `--verbose` - Detailed output\n\n**Output Streams:**\n\n- **stdout** - Validation results (errors, warnings)\n- **stderr** - Informational messages (progress, summaries)\n\nThis separation makes mdite pipe-friendly:\n\n```bash\n# Grep for specific errors\nmdite lint | grep \"Dead link\"\n\n# Count errors\nmdite lint | wc -l\n\n# Process JSON with jq\nmdite lint --format json | jq '.[] | .file' | sort | uniq\n\n# Suppress progress messages, keep only errors\nmdite lint 2\u003e/dev/null\n```\n\n**What it validates:**\n\n- ✅ All files reachable from entrypoint\n- ✅ No orphaned files\n- ✅ All file links are valid\n- ✅ All anchor references exist\n- ✅ No broken cross-file anchor links\n\n### `mdite cat [files...]` - Output Documentation Content\n\nOutput documentation content in various formats and orderings.\n\n```bash\n# Output all files in dependency order (default)\nmdite cat\n\n# Output in alphabetical order\nmdite cat --order alpha\n\n# Use custom separator between files\nmdite cat --separator \"\\\\n---\\\\n\"\n\n# Output as JSON with metadata\nmdite cat --format json\n\n# Pipe to other tools\nmdite cat | grep \"TODO\"\nmdite cat | wc -l\n\n# Export as single file\nmdite cat --order deps | pandoc -o docs.pdf\n\n# Combine with jq for analysis\nmdite cat --format json | jq '.[] | {file, wordCount}'\n```\n\n**Options:**\n\n- `[files...]` - Specific files to output (optional, defaults to all files in graph)\n- `--order \u003ctype\u003e` - Output order: `deps` (dependency order, default) or `alpha` (alphabetical)\n- `--separator \u003ctext\u003e` - Text between files (default: `\\n\\n`). Supports escape sequences like `\\n`, `\\t`\n- `--format \u003ctype\u003e` - Output format: `markdown` (default) or `json`\n- `--exclude \u003cpattern...\u003e` - Exclude file patterns (gitignore-style)\n- `--respect-gitignore` - Respect .gitignore patterns\n- `--no-exclude-hidden` - Don't exclude hidden directories\n\n**Output Formats:**\n\n**Markdown (default):**\n\n- Outputs raw file content concatenated with separators\n- Perfect for piping to other tools\n- Streams to stdout for efficiency\n\n**JSON:**\n\n- Structured output with metadata for each file\n- Includes: file path, depth, content, word count, line count\n- Ideal for programmatic processing\n\n**Use cases:**\n\n- 📤 **Export:** Create single-file documentation artifacts\n- 🔄 **Transform:** Pipe to pandoc, markdown processors, or custom tools\n- 📊 **Analyze:** Extract statistics, search patterns, or validate content\n- 🎯 **Integration:** Build documentation pipelines and workflows\n\n**Examples:**\n\n````bash\n# Generate PDF documentation\nmdite cat --order deps | pandoc --toc -o documentation.pdf\n\n# Count total words in documentation\nmdite cat | wc -w\n\n# Find all TODOs across documentation\nmdite cat | grep -n \"TODO\"\n\n# Get statistics from JSON\nmdite cat --format json | jq '[.[] | .wordCount] | add'\n\n# Extract code blocks\nmdite cat | awk '/```/,/```/'\n````\n\n### `mdite files` - List Files in Documentation Graph\n\n**Unix Philosophy Approach:** mdite provides graph-filtered file lists that compose with the Unix ecosystem.\n\n```bash\n# List all reachable files\nmdite files\n\n# Filter by depth\nmdite files --depth 2\n\n# List orphaned files only\nmdite files --orphans\n\n# Output absolute paths\nmdite files --absolute\n\n# Filter by frontmatter metadata (JMESPath query)\nmdite files --frontmatter \"status=='published'\"\nmdite files --frontmatter \"contains(tags, 'api')\"\n\n# JSON output with metadata\nmdite files --format json\n\n# Annotate with depth information\nmdite files --with-depth\n\n# Null-separated for xargs -0\nmdite files --print0 | xargs -0 ls -l\n\n# Sort by depth, incoming, outgoing links, or alphabetically\nmdite files --sort depth\nmdite files --sort incoming\nmdite files --sort outgoing\nmdite files --sort alpha  # default\n```\n\n**Unix Composition (The Power of Files):**\n\nThe `files` command is designed to compose with standard Unix tools via pipes:\n\n````bash\n# Search with ripgrep (graph-filtered search)\nmdite files --depth 2 | xargs rg \"authentication\" -C 2\n\n# Update published docs only\nmdite files --frontmatter \"status=='published'\" | xargs sed -i 's/v1/v2/g'\n\n# Lint reachable docs\nmdite files | xargs markdownlint\nmdite files | xargs prettier --write\n\n# Generate stats\nmdite files | xargs wc -w | tail -1  # Total words\n\n# Archive orphaned files\nmdite files --orphans | xargs -I {} mv {} archive/\n\n# Complex pipeline: find API docs, extract code blocks, count languages\nmdite files --frontmatter \"contains(tags, 'api')\" | \\\n  xargs rg '```(\\w+)' -o -r '$1' | \\\n  sort | uniq -c | sort -rn\n\n# Custom processing\nmdite files | xargs ./my-script.sh\n````\n\n**Options:**\n\n- `--depth \u003cn\u003e` - Limit to files at depth N or less (default: unlimited)\n- `--orphans` - List only orphaned files\n- `--no-orphans` - Exclude orphaned files (default)\n- `--absolute` - Output absolute paths (default: relative)\n- `--frontmatter \u003cquery\u003e` - Filter by frontmatter metadata (JMESPath query)\n- `--format \u003ctype\u003e` - Output format: `list` (default) or `json`\n- `--with-depth` - Annotate output with depth information (list format only)\n- `--print0` - Use null character as separator (for `xargs -0`)\n- `--sort \u003ctype\u003e` - Sort by: `alpha` (default), `depth`, `incoming`, `outgoing`\n- `--exclude \u003cpattern...\u003e` - Exclude file patterns (gitignore-style)\n- `--respect-gitignore` - Respect .gitignore patterns\n- `--no-exclude-hidden` - Don't exclude hidden directories\n\n**Why `files` instead of `query`?**\n\nFollowing Unix philosophy, mdite focuses on what it does best: graph operations. Instead of reimplementing search (ripgrep is better), mdite provides graph-filtered file lists that compose with ANY tool:\n\n- ✅ **Use ripgrep for search** - It's faster and more feature-rich\n- ✅ **Use sed/awk for transformation** - They're mature and powerful\n- ✅ **Use custom scripts** - Unlimited flexibility\n- ✅ **Infinite combinations** - Not locked into mdite's features\n\n**Use cases:**\n\n- 🔍 **Graph-aware search** - Filter files by graph/metadata, search with ripgrep\n- 🔄 **Bulk operations** - Process graph-filtered files with any tool\n- 📊 **Metadata filtering** - JMESPath queries on frontmatter combined with graph\n- 🧹 **Cleanup** - Find and archive orphaned files\n- 🎯 **Targeted operations** - Work on specific subsets of your documentation\n\n### `mdite init` - Initialize Configuration\n\nCreate a configuration file.\n\n```bash\n# Create default config file (mdite.config.js)\nmdite init\n\n# Create config file with custom path\nmdite init --config .mditerc.json\n```\n\n**Options:**\n\n- `--config \u003cpath\u003e` - Config file path (default: `mdite.config.js`)\n\n### `mdite config` - Explore Configuration\n\nDisplay or explore mdite configuration.\n\n```bash\n# View current merged configuration\nmdite config\n\n# View all available options\nmdite config --schema\n\n# Learn about specific option\nmdite config --explain maxConcurrency\n\n# Generate comprehensive template\nmdite config --template \u003e mdite.config.js\n\n# See where each value comes from (Phase 2 - not yet implemented)\nmdite config --sources\n```\n\n**Options:**\n\n- `--schema` - Display all configuration options with descriptions, types, defaults\n- `--explain \u003ckey\u003e` - Show detailed explanation of a specific option\n- `--template` - Generate comprehensive config template\n- `--sources` - Show which layer provides each value (planned for Phase 2)\n- `--format \u003ctype\u003e` - Output format: `text` (default), `json`, `js`, `yaml`, `md`\n\n**Use cases:**\n\n- 🔍 **Discover options:** See what's configurable without leaving terminal\n- 📖 **Learn about options:** Get detailed help for specific configuration keys\n- 🎯 **Generate templates:** Create well-documented config files quickly\n- 🐛 **Debug config:** Understand where values come from (planned)\n\n### Future Commands\n\n\u003e ⚠️ **Note:** These commands are planned for future releases and are not yet available.\n\nComing soon as mdite expands:\n\n#### `mdite toc` - Generate Table of Contents\n\n```bash\n# FUTURE FEATURE - not yet available\n# Generate TOC from graph\nmdite toc --depth 2\n```\n\n#### `mdite stats` - Documentation Metrics\n\n```bash\n# FUTURE FEATURE - not yet available\n# Analyze documentation metrics\nmdite stats --depth 2\n```\n\n---\n\n## Configuration\n\n### Zero Config\n\nmdite works out of the box:\n\n```bash\nmdite lint  # Just works\nmdite deps README.md  # Just works\n```\n\n**Defaults:**\n\n- Entrypoint: `README.md`\n- All rules: `error`\n- Output: colored text\n\n### Discovering Options\n\nmdite provides built-in help for configuration:\n\n```bash\n# See all available options\nmdite config --schema\n\n# Learn about specific option\nmdite config --explain maxConcurrency\n\n# Generate comprehensive template\nmdite config --template \u003e mdite.config.js\n```\n\n**All configuration options are self-documented** - no need to search docs!\n\n### Custom Configuration\n\nCreate `mdite.config.js` for project-specific settings:\n\n```javascript\nmodule.exports = {\n  // Start traversal from a different file\n  entrypoint: 'docs/index.md',\n\n  // Customize rule severity\n  rules: {\n    'orphan-files': 'error', // Block build on orphans\n    'dead-link': 'error', // Block build on broken links\n    'dead-anchor': 'warn', // Warn but don't block\n  },\n};\n```\n\n### Configuration Formats\n\n| Format       | File              | Use Case                  |\n| ------------ | ----------------- | ------------------------- |\n| JavaScript   | `mdite.config.js` | Comments, computed values |\n| JSON         | `.mditerc`        | Simple, no comments       |\n| YAML         | `.mditerc.yaml`   | Human-readable, comments  |\n| package.json | `\"mdite\": {}`     | Keep config in one place  |\n\n**Priority:** CLI flags \u003e Project config \u003e Defaults\n\nSee [examples/06-config-variations](./examples/06-config-variations/) for working examples.\n\n### Rules\n\n| Rule           | What It Detects                   | Default |\n| -------------- | --------------------------------- | ------- |\n| `orphan-files` | Files unreachable from entrypoint | `error` |\n| `dead-link`    | Broken relative file links        | `error` |\n| `dead-anchor`  | Broken `#heading` references      | `error` |\n\n**Severity levels:**\n\n- `error` - Fail (exit code 1)\n- `warn` - Show warning, don't fail\n- `off` - Disable rule\n\n### Exit Codes\n\nmdite follows Unix conventions for exit codes:\n\n| Code  | Meaning          | When                                                        |\n| ----- | ---------------- | ----------------------------------------------------------- |\n| `0`   | Success          | No validation errors found                                  |\n| `1`   | Validation Error | Orphaned files, broken links, or validation failures        |\n| `2`   | Usage Error      | Invalid arguments, unknown options, or configuration errors |\n| `130` | Interrupted      | Process interrupted (Ctrl+C, SIGINT, SIGTERM)               |\n\n**Usage in scripts:**\n\n```bash\n# Check exit code\nif mdite lint; then\n  echo \"Documentation is valid\"\nelse\n  echo \"Documentation has errors\"\n  exit 1\nfi\n\n# CI/CD pipeline\nmdite lint --format json || exit 1\n\n# Conditional logic\nmdite lint \u0026\u0026 npm run deploy\n\n# Capture exit code\nmdite lint\nEXIT_CODE=$?\nif [ $EXIT_CODE -eq 1 ]; then\n  echo \"Validation errors found\"\nelif [ $EXIT_CODE -eq 2 ]; then\n  echo \"Usage error - check your command\"\nfi\n```\n\n**Signal Handling:**\n\nmdite gracefully handles Unix signals:\n\n- **SIGINT** (Ctrl+C) - Clean exit with code 130\n- **SIGTERM** - Clean exit with code 130\n- **SIGPIPE** - Gracefully exits when pipe is closed (e.g., `mdite lint | head`)\n\n---\n\n## Example Output\n\n### `mdite lint` - Validation\n\n```\nmdite\n──────────────────────────────────────────────────\nℹ Linting: ./docs\nℹ Entrypoint: README.md\n\nℹ Building dependency graph...\n✓ Found 24 reachable files\n\nℹ Checking for orphaned files...\n✗ Found 3 orphaned files\n\nℹ Validating links...\n✗ Found 2 link errors\n\n\nFound 5 issue(s)\n──────────────────────────────────────────────────\n\ndocs/old-guide.md\n  - error Orphaned file: not reachable from entrypoint [orphan-files]\n\ndocs/setup.md\n  7:3 error Dead link: installation.md [dead-link]\n\n✗ 5 error(s), 0 warning(s)\n```\n\n### `mdite deps` - Dependency Analysis\n\n```bash\n$ mdite deps README.md --depth 2\n\nDependencies for README.md\n──────────────────────────────────────────────────\n\nOutgoing (what this file references):\n├── docs/getting-started.md\n│   ├── docs/installation.md\n│   └── docs/configuration.md\n├── docs/api-reference.md\n│   ├── docs/api/methods.md\n│   └── docs/api/types.md\n└── CONTRIBUTING.md\n\nIncoming (what references this file):\n(none - this is the entrypoint)\n\nCycles detected: 0\n```\n\n---\n\n## Examples\n\nThe `examples/` directory contains 12 runnable demonstrations (68 files) showing mdite in action:\n\n```bash\n# Valid documentation\ncd examples/01-valid-docs \u0026\u0026 mdite lint\n\n# Orphan detection\ncd examples/02-orphan-files \u0026\u0026 mdite lint\n\n# Broken links\ncd examples/03-broken-links \u0026\u0026 mdite lint\n\n# Dependency analysis\ncd examples/01-valid-docs \u0026\u0026 mdite deps README.md\n```\n\n**Run all examples:**\n\n```bash\ncd examples \u0026\u0026 ./run-all-examples.sh\n```\n\nSee [examples/README.md](./examples/README.md) for complete documentation.\n\n---\n\n## How It Works\n\n### The Graph Model\n\nmdite treats your documentation as a directed graph:\n\n- **Nodes:** Markdown files\n- **Edges:** Links between files\n- **Root:** Entrypoint file (default: `README.md`)\n\n```\nREADME.md (root)\n├─→ docs/guide.md\n│   ├─→ docs/setup.md\n│   └─→ docs/api.md\n└─→ CONTRIBUTING.md\n    └─→ docs/development.md\n```\n\n### Graph Building Algorithm\n\n1. **Start** at entrypoint (`README.md`)\n2. **Parse** markdown to extract links\n3. **Follow** each relative `.md` link\n4. **Recursively** build graph (with cycle detection)\n5. **Result:** Complete map of connected documentation\n\n**What gets included:**\n\n- ✅ Relative links: `[guide](./setup.md)`\n- ✅ Links with anchors: `[api](./api.md#methods)`\n- ✅ Anchor-only: `[intro](#getting-started)`\n\n**What gets skipped:**\n\n- ❌ External URLs: `https://example.com`\n- ❌ Absolute paths outside project\n- ❌ Non-markdown files\n\n### Validation Using the Graph\n\nOnce the graph is built, mdite can:\n\n- **Detect orphans:** Files NOT in the graph\n- **Validate links:** Check edges point to existing nodes\n- **Analyze dependencies:** Traverse graph in any direction\n- **Future:** Query, search, export the graph\n\n**This graph foundation** enables all current and future mdite features.\n\n---\n\n## Roadmap\n\nmdite is evolving from a linter into a complete **documentation toolkit**.\n\n### ✅ Current\n\n- Graph-based dependency analysis (`deps`)\n- Structural validation (`lint`)\n- Orphan detection\n- Link validation (file + anchor)\n- Configuration system\n- **Content output (`cat`)** - Export documentation content\n  - Dependency-order and alphabetical output\n  - JSON format with metadata\n  - Pipe-friendly for Unix workflows\n\n### 🚧 Future Features\n\n\u003e ⚠️ **Note:** These features are planned for future releases and are not yet implemented.\n\n- **`mdite query`** - Search across documentation system\n  - Content search\n  - Filename pattern matching\n  - Scope to graph sections\n- **`mdite toc`** - Generate table of contents from graph\n- **`mdite stats`** - Documentation metrics and analysis\n- **External link validation** - Check HTTP/HTTPS URLs\n- **Watch mode** - Auto-validate on file changes\n- **LSP server** - Editor integration\n- **Custom rule API** - Write your own validation rules\n- **Export formats** - PDF, HTML, etc. with graph awareness\n\n**The vision:** A complete toolkit for working with markdown documentation as a unified, connected system.\n\n---\n\n## Integration\n\n### Pre-Commit Hook (Husky)\n\n```json\n{\n  \"husky\": {\n    \"hooks\": {\n      \"pre-commit\": \"mdite lint\"\n    }\n  }\n}\n```\n\n### GitHub Actions\n\n```yaml\nname: Documentation\n\non:\n  pull_request:\n    paths:\n      - 'docs/**'\n      - '*.md'\n\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - run: npm install -g mdite\n      - run: mdite lint --format json\n```\n\n### Package.json Scripts\n\n```json\n{\n  \"scripts\": {\n    \"docs:lint\": \"mdite lint\",\n    \"docs:deps\": \"mdite deps README.md\",\n    \"docs:check\": \"mdite lint \u0026\u0026 echo '✓ Documentation valid'\",\n    \"predeploy\": \"mdite lint\"\n  }\n}\n```\n\n---\n\n## Contributing\n\nmdite is evolving rapidly. Contributions welcome!\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Development setup\n- Testing guidelines\n- Pull request process\n- Roadmap and feature ideas\n\n---\n\n## License\n\nMIT © 2025 Richard Adleta\n\n---\n\n## About\n\n**mdite** (markdown documentation toolkit) is built for developers and teams who work with interconnected markdown documentation.\n\nBorn from the frustration of broken docs and the realization that documentation is a **system**, not a collection of files, mdite provides the tools to work with that system effectively.\n\n**Built with:**\n\n- [TypeScript](https://www.typescriptlang.org/)\n- [Commander.js](https://github.com/tj/commander.js)\n- [unified/remark](https://unifiedjs.com/)\n- [Zod](https://github.com/colinhacks/zod)\n\n**Issues \u0026 Ideas:** [GitHub Issues](https://github.com/radleta/mdite/issues)\n\n---\n\n**Work with your documentation as a system, not scattered files.**\n\n```bash\nnpm install -g mdite\nmdite deps README.md    # Understand structure\nmdite lint              # Validate integrity\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradleta%2Fmdite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradleta%2Fmdite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradleta%2Fmdite/lists"}