Documentation keyword extraction, validation, and analysis tool. Part of the dev meta-utility family alongside .adr (Architecture Decision Records), .req (Requirements), and .runnote (Development Notes).
- Keyword Extraction: Extract and index keywords from markdown documentation
- Validation: Validate keywords against a project taxonomy
- Search: Search by keyword, content, or cross-references (ADR/req/runnote)
- Visualization: Generate relationship graphs showing keyword co-occurrence
- Statistics: Analyze keyword usage patterns across projects
- Suggestions: AI-powered keyword suggestions based on content
- Multi-Project: Analyze across multiple projects simultaneously
- Cross-Utility Integration: Link to ADRs, requirements, and RunNotes
# Clone or download to ~/.doc
git clone <repo-url> ~/.doc
# Or use install script
curl -sSL <install-url> | bash
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.doc/bin:$PATH"
# Verify installation
doc-validate --help# API Authentication Guide
Keywords: [:api :authentication :security]
This guide covers authentication mechanisms for our API.
Our approach uses JWT tokens [:jwt :tokens] for stateless authentication.Create doc-tools/keyword-taxonomy.md in your project:
# Keyword Taxonomy
## Core Concepts
- `:api` - API design and implementation
- `:authentication` - Authentication mechanisms
- `:security` - Security concerns
## Technical
- `:jwt` - JSON Web Tokens
- `:tokens` - Token-based auth# Validate current project
doc-validate
# Output:
# ✓ All keywords valid (15 files checked)# Find all docs with :api keyword
doc-search keyword :api
# Find docs referencing ADR-00042
doc-search adr 00042
# Get usage statistics
doc-stats
# Generate visualization
doc-graph | dot -Tpng > keywords.pngValidate keywords against taxonomy.
doc-validate [project ...]
# Examples
doc-validate # Current project
doc-validate ~/proj1 # Specific project
doc-validate ~/p1 ~/p2 ~/p3 # Multiple projectsExit codes:
0- All keywords valid1- Invalid keywords found
Search documentation by keyword, content, or cross-references.
doc-search keyword <keyword> [project ...] # Search by keyword
doc-search content <text> [project ...] # Search by content
doc-search adr <id> [project ...] # Search for ADR refs
doc-search req <id> [project ...] # Search for req refs
doc-search runnote <id> [project ...] # Search for RunNotes refs
# Examples
doc-search keyword :architecture
doc-search content "database migration"
doc-search adr 00042
doc-search req REQ-AUTH-001
doc-search runnote RunNotes-2025-01-15-FeatureBuild keyword index in JSON format.
doc-index [project ...]
# Examples
doc-index # Current project
doc-index > keywords.json # Save to file
doc-index ~/p1 ~/p2 > index.json # Cross-project indexOutput format:
{
"architecture": ["guide/arch.md", "adr/ADR-001.md"],
"security": ["security/overview.md"]
}Generate keyword relationship graph in GraphViz DOT format.
doc-graph [options] [project ...]
# Options
--weights # Show co-occurrence counts
--min-weight=N # Only edges with weight >= N
# Examples
doc-graph | dot -Tpng > graph.png
doc-graph --weights --min-weight=3
doc-graph ~/p1 ~/p2 > combined.dotSuggest keywords for a file based on content analysis.
doc-suggest [options] <file>
# Options
--confidence # Show confidence scores
--taxonomy-only # Only suggest from taxonomy
# Examples
doc-suggest doc/new-guide.md
doc-suggest --confidence doc/api.md
doc-suggest --taxonomy-only doc/security.mdShow keyword usage statistics.
doc-stats [options] [project ...]
# Options
--top=N # Show only top N keywords
# Examples
doc-stats
doc-stats --top=10
doc-stats ~/p1 ~/p2 ~/p3Edit ~/.doc/config.edn:
{:doc {:path "doc"
:taxonomy "doc-tools/keyword-taxonomy.md"
:template-dir "~/.doc/template"
:excluded-patterns #{"README.md" "CHANGELOG.md"}
:metadata-mode :hybrid
:validation {:strict false
:require-taxonomy false}
:cross-refs {:enable-adr true
:enable-req true
:enable-runnote true}}}Create .doc.edn in your project root to override global settings:
{:doc {:path "docs"
:taxonomy "docs/keywords.md"
:validation {:strict true
:require-taxonomy true}}}| Key | Type | Default | Description |
|---|---|---|---|
:path |
string | "doc" |
Documentation directory |
:taxonomy |
string | "doc-tools/keyword-taxonomy.md" |
Taxonomy file path |
:excluded-patterns |
set | #{"README.md" "CHANGELOG.md"} |
Files to exclude |
:validation |
map | see below | Validation settings |
:cross-refs |
map | see below | Cross-reference integration |
Validation settings:
:strict(boolean) - Fail on any validation error:require-taxonomy(boolean) - Require taxonomy file to exist
Cross-reference settings:
:enable-adr(boolean) - Enable ADR cross-references:enable-req(boolean) - Enable requirement cross-references:enable-runnote(boolean) - Enable RunNotes cross-references
Keywords: [:architecture :api :security]
Content with inline [:performance :scalability] keywords.- Bracket notation:
[:keyword1 :keyword2] - Colon prefix:
:keywordorkeyword(both accepted) - Kebab-case:
:multi-word-keyword - Space-separated within brackets
The tool automatically detects references to:
- ADRs:
[ADR-00042]orADR-00042 - Requirements:
[REQ-AUTH-001]orREQ-AUTH-001 - RunNotes:
[RunNotes-2025-01-15-Topic]orRunNotes-2025-01-15-Topic
# Find all docs mentioning ADR-00042
doc-search adr 00042
# Find all docs implementing REQ-AUTH-001
doc-search req REQ-AUTH-001
# Find docs related to a RunNotes session
doc-search runnote RunNotes-2025-01-15-AuthAdd to .git/hooks/pre-commit:
#!/bin/bash
doc-validate || exit 1# GitHub Actions example
- name: Validate Documentation Keywords
run: |
doc-validate
doc-stats --top=20# 1. Get suggestions for new doc
doc-suggest --confidence docs/new-guide.md
# 2. Add suggested keywords to doc
# (manually edit file)
# 3. Validate
doc-validate
# 4. Check coverage
doc-stats
# 5. Visualize relationships
doc-graph --weights | dot -Tpng > keywords.png# Validate across all projects
doc-validate ~/proj1 ~/proj2 ~/proj3
# Combined statistics
doc-stats ~/proj1 ~/proj2 ~/proj3
# Cross-project index
doc-index ~/proj1 ~/proj2 > combined-index.json
# Cross-project graph
doc-graph ~/proj1 ~/proj2 --min-weight=5 | dot -Tpng > combined.png# Find docs referencing specific ADR
doc-search adr 00042
# Validate ADR references are valid
# (requires ADR integration enabled)# Find docs implementing requirement
doc-search req REQ-AUTH-001
# Trace requirement to documentation# Find docs mentioned in RunNotes
doc-search runnote RunNotes-2025-01-15-Feature
# Bidirectional linking supportThis is normal if you haven't created a taxonomy yet. The tool will skip validation but still extract keywords.
Solution: Create doc-tools/keyword-taxonomy.md or configure a different path in .doc.edn.
Check your configuration:
# Verify doc directory exists
ls doc/
# Check configuration
cat .doc.ednEnsure taxonomy file is properly formatted with backtick-colon notation:
- `:keyword-name` - DescriptionEnsure ~/.doc/bin is in your PATH:
export PATH="$HOME/.doc/bin:$PATH"~/.doc/
├── bin/ # Executable commands
│ ├── doc-validate
│ ├── doc-search
│ ├── doc-index
│ ├── doc-graph
│ ├── doc-suggest
│ └── doc-stats
├── doc-core.bb # Core library functions
├── config.edn # Global defaults
├── template/ # Document templates
├── test/ # Test suite
├── CLAUDE.md # AI agent quick reference
└── README.md # This file
~/.lib/config-core.bb- Configuration management (shared)~/.lib/metadata-parser.bb- EDN metadata parsing (shared)
- DRY: No code duplication across commands
- Composability: Each command is focused and independent
- Integration: Seamless cross-utility references
- Extensibility: Easy to add new commands and features
We welcome contributions! Areas for improvement:
- Additional suggestion patterns
- Enhanced visualization options
- IDE integrations
- API documentation
- Additional export formats
MIT License - see LICENSE file
- .adr - Architecture Decision Records
- .req - Requirements Management
- .runnote - Development Notes
- CLAUDE.md - AI agent quick reference
v1.0.0 - Normalized architecture (migrated from doc-keywords)
Changelog:
- Migrated from monolithic doc-keywords to decomposed architecture
- Added cross-reference search (ADR/req/runnote)
- Integrated with shared config-core library
- Multi-project support across all commands
- Enhanced visualization with edge weights