mdbase

Work with mdbase collections: typed, queryable markdown file databases with YAML frontmatter schemas.

Monorepo vault setup

This vault is configured as an mdbase collection:

Config: ./mdbase.yaml
Types: ./90-system/_types/
Schema docs: ./90-system/docs/mdbase-schema.md

Available types

Namespace	Types
journals-*	`journals-daily`, `journals-weekly`, `journals-quarterly`, `journals-yearly`
zettel-*	`zettel-source`, `zettel-publication`, `zettel-idea`, `zettel-fleeting`
entity-*	`entity-person`, `entity-organization`
para-*	`para-project`, `para-area`, `para-resource`, `para-task`
misc-*	`misc-software`, `misc-workflow`, and any ad-hoc types

Type matching

All types use global-type field for matching:

global-type: zettel-source

Duck-typing fallback available for migration (e.g., files with source-url + source-title match zettel-source).

CLI usage

Run from monorepo root:

# Run from repo root
npx mdbase <command> [options]

Create notes

# Create a source note
npx mdbase create --type zettel-source

# Create with fields
npx mdbase create --type zettel-source \
  --source-title "Article Title" \
  --source-url "https://example.com" \
  --zettel-status drafted

# Create a task
npx mdbase create --type para-task \
  --para-status todo \
  --para-priority p2

# Create a project
npx mdbase create --type para-project \
  --para-status active \
  --para-area "[[Career]]"

# Create a person entity
npx mdbase create --type entity-person \
  --entity-name "Jane Doe"

# Create a publication
npx mdbase create --type zettel-publication \
  --pub-title "Episode Title" \
  --pub-type podcast \
  --zettel-status drafted

Query notes

# All active projects
npx mdbase query "global-type = para-project AND para-status = active"

# Unreviewed sources
npx mdbase query "global-type = zettel-source AND zettel-status = drafted"

# Tasks by priority
npx mdbase query "global-type = para-task AND para-priority = p1"

# Overdue tasks
npx mdbase query "global-type = para-task AND para-due-date < 2026-02-06"

# YouTube sources
npx mdbase query "source-platform = youtube" --types zettel-source

# Projects sorted by deadline
npx mdbase query "para-status = active" --types para-project --sort para-deadline

# Limit results
npx mdbase query "global-type = zettel-source" --limit 10 --sort "-source-fetched-date"

Validate

# Validate entire vault
npx mdbase validate .

# Validate specific folder
npx mdbase validate 20-zettel/
npx mdbase validate 30-para/

# Validate single file
npx mdbase validate 30-para/31-projects/example-project.md

Update notes

# Mark source as reviewed
npx mdbase update 20-zettel/sources/article.md --set "zettel-status=reviewed"

# Complete a task
npx mdbase update 30-para/tasks/my-task.md --set "para-status=completed"

# Update project deadline
npx mdbase update 30-para/31-projects/project.md --set "para-deadline=2026-03-01"

Read and inspect

# Read a file
npx mdbase read 30-para/31-projects/example-project.md

# Get vault statistics
npx mdbase stats .

# Visualize links
npx mdbase links . --format dot > graph.dot

Export and import

# Export projects to CSV
npx mdbase export . --type para-project --format csv -o projects.csv

# Export sources to JSON
npx mdbase export . --type zettel-source --format json -o sources.json

# Import tasks from CSV
npx mdbase import tasks.csv --type para-task

Rename with link updates

# Rename file and update all [[wikilinks]]
npx mdbase rename old-name.md new-name.md

Run Obsidian bases

# Execute a .base query file
npx mdbase base run 90-system/bases/zettel-sources.base
npx mdbase base run 90-system/bases/para-tasks.base

Adding new types

Quick ad-hoc type

Use misc-* prefix in frontmatter:

global-type: misc-recipe

No schema needed initially - mdbase allows unknown types

Formal type definition

Create 90-system/_types/misc-example.md:

---
name: misc-example
matchFields: [global-type]
fields:
  global-type:
    type: enum
    values: [misc-example]
    required: true
  custom-field:
    type: string
    required: false
---

# misc-example

Description of when to use this type.

Common workflows

Process inbox item

# Query inbox items (untyped files in 00-inbox)
ls 00-inbox/

# Create typed note from inbox content
npx mdbase create --type zettel-source --source-title "..." --source-url "..."

# Or create task
npx mdbase create --type para-task --para-status todo

Weekly review queries

# Unreviewed sources
npx mdbase query "zettel-status = drafted" --types zettel-source

# Active projects
npx mdbase query "para-status = active" --types para-project

# Todo tasks
npx mdbase query "para-status = todo" --types para-task --sort para-priority

# Orphan ideas (no sources linked)
npx mdbase query "zettel-sources = []" --types zettel-idea

Bulk operations

# Archive old drafted sources
npx mdbase query "zettel-status = drafted AND source-fetched-date < 2025-01-01" \
  --types zettel-source --format paths | \
  xargs -I {} npx mdbase update {} --set "zettel-status=archived"

Troubleshooting

Node.js version

mdbase-cli requires Node.js 22+:

node --version

Validation errors

Check:

Valid YAML frontmatter (between --- markers)
Required fields present for the type
Enum values match allowed values
Date format is YYYY-MM-DD

Type not matching

Verify global-type field value matches type name exactly
Check 90-system/_types/ for valid type names
For duck-typing, ensure characteristic fields are present

References

Schema docs: 90-system/docs/mdbase-schema.md
Type definitions: 90-system/_types/
Obsidian bases: 90-system/bases/
mdbase spec: https://github.com/callumalpass/mdbase-spec
mdbase CLI: https://github.com/callumalpass/mdbase-cli

tools-mdbase