kb-lint 0.1.2

Markdown knowledge base linter for Obsidian, Foam, Dendron & Quartz: finds broken wiki-links, orphan notes, and missing frontmatter

kb-lint

A linter for your LLM-compiled knowledge base.

TL;DR

kb-lint is a fast, dependency-free markdown knowledge base linter. It checks Obsidian vaults, Foam workspaces, Dendron notes, and any wiki of markdown files for broken wiki-links, missing frontmatter, orphan pages, thin articles, and structural inconsistencies. No LLM required.

Run health checks over markdown wikis to catch broken links, missing metadata, orphan pages, thin articles, and structural inconsistencies, all without requiring an LLM.

Inspired by Andrej Karpathy's LLM Knowledge Bases workflow, he runs "health checks" over his wiki to "find inconsistent data, impute missing data, find interesting connections for new article candidates."

Use Cases

• Lint an Obsidian vault for broken wiki-links and orphan pages
• Check Foam or Dendron notes for missing frontmatter
• Validate a Quartz or Jekyll markdown wiki before publishing
• Find thin or stub articles in a personal knowledge base
• Detect inconsistent tags and casing across markdown files
• Run health checks on an LLM-compiled wiki (Karpathy workflow)
• Add markdown wiki linting to CI/CD with kb-lint --format json

Installation

pip install kb-lint

Quick Start

# Lint the current directory
kb-lint .

# Generate a health report
kb-lint ./my-wiki --report

# Auto-fix simple issues
kb-lint ./my-wiki --fix

Example Output

 Knowledge Base Health Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Path:     ./wiki
  Articles: 47
  Links:    203

  3 errors  7 warnings  2 info

┌─────┬──────────────────────┬───────┬──────────────┬─────────────────────────────────────┐
│ Sev │ File                 │  Line │ Check        │ Message                             │
├─────┼──────────────────────┼───────┼──────────────┼─────────────────────────────────────┤
│ E   │ concepts/rlhf.md     │    23 │ links        │ Broken wiki-link: [[ppo-training]]  │
│ E   │ concepts/scaling.md  │     1 │ frontmatter  │ Missing required field: title         │
│ W   │ concepts/new-idea.md │     - │ content      │ Thin article: only 42 words (min 100)│
│ W   │ sources/paper-x.md   │     - │ orphans      │ Orphan page: no incoming links        │
│ I   │ concepts/nlp.md      │     - │ consistency  │ Inconsistent tag casing for 'nlp'     │
└─────┴──────────────────────┴───────┴──────────────┴─────────────────────────────────────┘

  2 issues can be auto-fixed with --fix

Health Score: 82/100

Checks Reference

Check	What it catches	Default severity	Auto-fixable?
links	Broken [[wiki-links]] (wiki-links only, no external URLs)	Error	No
frontmatter	Missing/invalid YAML frontmatter	Error/Info	Yes (add defaults)
orphans	Articles with no incoming links	Warning	No
structure	Non-kebab-case filenames, spaces	Error/Warning	Yes (rename)
content	Thin articles, {{PLACEHOLDERS}}, duplicate titles, empty sections	Error/Warning	No
index	Missing/extra entries in _index.md	Warning/Error	Yes (update index)
consistency	Inconsistent tags, dates, confidence levels	Warning	No

CLI Reference

# Basic lint
kb-lint [path]

# Output formats
kb-lint [path] --format terminal    # Rich colored output (default)
kb-lint [path] --format markdown    # Markdown report
kb-lint [path] --format json        # Machine-readable JSON

# Filter by severity
kb-lint [path] --severity error     # Only show errors
kb-lint [path] --severity warning   # Warnings and errors

# Run specific checks
kb-lint [path] --check links,frontmatter

# List available checks
kb-lint --list-checks

# Health report with score
kb-lint [path] --report

# CI mode (exit 1 on errors)
kb-lint [path] --ci

# Auto-fix
kb-lint [path] --fix

# Preview fixes without applying them
kb-lint [path] --fix --dry-run

--ci Mode

In CI mode, kb-lint exits with code 1 if any errors are found:

kb-lint [path] --ci

--fix Behavior

--fix creates .bak backup files before modifying any file. Use --fix --dry-run to preview what would be changed without writing to disk.

Exit Codes

Code	Meaning
0	Success - no errors found (warnings/info may still be present)
1	Errors found (only in --ci mode)

Configuration

Configure via .kblintrc.yml in your wiki directory:

required_frontmatter:
  - title
recommended_frontmatter:
  - tags
  - sources
  - created
  - confidence
min_article_words: 100
ignore_patterns:
  - _templates/**
  - drafts/**
recognized_directories:
  - concepts
  - sources
  - comparisons
allowed_confidence_levels:
  - high
  - medium
  - low
severity_threshold: info

Or in pyproject.toml:

[tool.kb-lint]
required_frontmatter = ["title"]
min_article_words = 100

CI Integration

GitHub Actions

- name: Lint knowledge base
  run: |
    pip install kb-lint
    kb-lint ./wiki --ci

Part of the LLM KB Ecosystem

• awesome-llm-knowledge-bases - Curated list of LLM knowledge base tools
• karpathy-kb-template - Ready-to-use wiki template
• wiki-compiler - CLI to compile raw docs into structured wikis (uses kb-lint internally)

FAQ

How do I lint a markdown knowledge base?

Install kb-lint with pip install kb-lint, then run kb-lint ./your-wiki to scan all markdown files. Use --report to get a health score, or --ci for CI pipelines that should fail on errors. As a markdown knowledge base linter, kb-lint covers broken links, frontmatter, orphans, and structural checks in a single pass.

What does kb-lint check?

kb-lint checks for broken [[wiki-links]], missing YAML frontmatter, orphan pages with no incoming links, thin articles below a word count threshold, structural issues like non-kebab-case filenames, and inconsistencies in tags, dates, and confidence levels. Think of it as an end-to-end personal knowledge management quality check.

Can kb-lint auto-fix issues?

Yes. Run kb-lint ./your-wiki --fix to auto-fix supported issues like missing frontmatter defaults, non-kebab-case filenames, and out-of-date index files. Use --fix --dry-run to preview changes before applying them.

How do I lint an Obsidian vault?

Point kb-lint at your vault root: kb-lint ~/path/to/your-vault --report. It walks every .md file (including nested folders), resolves [[wiki-links]] across the whole graph, and produces an Obsidian vault health check covering broken links, orphan notes, missing frontmatter, and tag inconsistencies. No plugins required.

Does kb-lint work with Obsidian vaults?

kb-lint works with any folder of markdown files that uses [[wiki-links]]. Obsidian vaults fit this pattern well. Just point kb-lint at your vault directory and it will scan all .md files, including nested folders.

Does kb-lint work with Foam, Dendron, and Quartz?

Yes. kb-lint is intentionally tool-agnostic. If your notes are plain markdown files with [[wiki-links]] and optional YAML frontmatter, kb-lint works as a wiki-link validator for Foam workspaces, Dendron hierarchies, Quartz digital gardens, Jekyll wikis, and custom setups. Configure ignore_patterns in .kblintrc.yml to skip tool-specific folders like .obsidian/ or _layouts/.

How do I detect orphan pages in my knowledge base?

Run kb-lint ./your-wiki --check orphans to list every article that has zero incoming wiki-links. Combine with --format json to pipe results into other tools, or with --report to see orphan counts next to your overall health score. This is one of the most useful checks for cleaning up a personal knowledge base.

What's the best linter for a markdown wiki?

For pure markdown syntax (heading style, line length), use markdownlint. For knowledge base structure (broken wiki-links, orphans, frontmatter, thin content, tag consistency), use kb-lint. They are complementary, most teams run both in CI.

Can I use kb-lint in a GitHub Actions workflow?

Yes. kb-lint is designed for CI/CD. Install it in a workflow step and run kb-lint ./wiki --ci to fail the build on errors, or kb-lint ./wiki --format json > report.json to archive a machine-readable report. See the CI Integration section above for a ready-to-paste GitHub Actions snippet.

How is kb-lint different from markdownlint?

markdownlint checks markdown syntax and formatting (heading style, line length, etc.). kb-lint checks knowledge base structure, broken wiki-links, orphan pages, missing metadata, thin content, and cross-article consistency. They complement each other.

Development

git clone https://github.com/SingggggYee/kb-lint
cd kb-lint
pip install -e ".[dev]"
pytest -v
ruff check src/ tests/

License

MIT