mdbase

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

用于操作mdbase集合：基于YAML frontmatter schema的可查询、带类型的markdown文件数据库。

Monorepo vault setup

Monorepo知识库配置

This vault is configured as an mdbase collection:

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

本知识库已配置为mdbase集合：

配置文件：
```
./mdbase.yaml
```
类型定义：
```
./90-system/_types/
```
Schema文档：
```
./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

命名空间	类型
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` , 以及所有临时类型

Type matching

类型匹配

All types use

global-type

field for matching:

yaml

global-type: zettel-source

Duck-typing fallback available for migration (e.g., files with

source-url

+

source-title

match

zettel-source

).

所有类型使用

global-type

字段进行匹配：

yaml

global-type: zettel-source

迁移期间可使用鸭子类型作为兜底（例如，同时包含

source-url

和

source-title

的文件会匹配

zettel-source

类型）。

CLI usage

CLI使用方法

Run from monorepo root:

bash

undefined

在monorepo根目录执行：

bash

undefined

Run from repo root

在仓库根目录执行

npx mdbase <command> [options]

undefined

npx mdbase <command> [options]

undefined

Create notes

创建笔记

bash

undefined

bash

undefined

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

undefined

npx mdbase create --type zettel-publication
--pub-title "Episode Title"
--pub-type podcast
--zettel-status drafted

undefined

Query notes

查询笔记

bash

undefined

bash

undefined

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

YouTube来源

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"

undefined

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

undefined

Validate

验证

bash

undefined

bash

undefined

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

undefined

npx mdbase validate 30-para/31-projects/example-project.md

undefined

Update notes

更新笔记

bash

undefined

bash

undefined

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"

undefined

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

undefined

Read and inspect

读取与检查

bash

undefined

bash

undefined

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

undefined

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

undefined

Export and import

导入导出

bash

undefined

bash

undefined

Export projects to CSV

导出项目为CSV格式

npx mdbase export . --type para-project --format csv -o projects.csv

Export sources to JSON

导出来源为JSON格式

npx mdbase export . --type zettel-source --format json -o sources.json

Import tasks from CSV

从CSV导入任务

npx mdbase import tasks.csv --type para-task

undefined

npx mdbase import tasks.csv --type para-task

undefined

Rename with link updates

重命名并同步更新链接

bash

undefined

bash

undefined

Rename file and update all [[wikilinks]]

重命名文件并更新所有[[wikilinks]]链接

npx mdbase rename old-name.md new-name.md

undefined

npx mdbase rename old-name.md new-name.md

undefined

Run Obsidian bases

运行Obsidian base查询

bash

undefined

bash

undefined

Execute a .base query file

执行一个.base查询文件

npx mdbase base run 90-system/bases/zettel-sources.base npx mdbase base run 90-system/bases/para-tasks.base

undefined

npx mdbase base run 90-system/bases/zettel-sources.base npx mdbase base run 90-system/bases/para-tasks.base

undefined

Adding new types

添加新类型

Quick ad-hoc type

快速临时类型

Use
```
misc-*
```
prefix in frontmatter:

yaml

global-type: misc-recipe

No schema needed initially - mdbase allows unknown types

在frontmatter中使用
```
misc-*
```
前缀：

yaml

global-type: misc-recipe

初始不需要schema - mdbase允许未知类型

Formal type definition

正式类型定义

Create

90-system/_types/misc-example.md

:

yaml

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

创建

90-system/_types/misc-example.md

：

yaml

---
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.

undefined

该类型的使用场景说明。

undefined

Common workflows

常用工作流

Process inbox item

处理收件箱条目

bash

undefined

bash

undefined

Query inbox items (untyped files in 00-inbox)

查询收件箱条目（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

undefined

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

undefined

Weekly review queries

周复盘查询

bash

undefined

bash

undefined

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

undefined

npx mdbase query "zettel-sources = []" --types zettel-idea

undefined

Bulk operations

批量操作

bash

undefined

bash

undefined

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"

undefined

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"

undefined

Troubleshooting

问题排查

Node.js version

Node.js版本

mdbase-cli requires Node.js 22+:

bash

node --version

mdbase-cli要求Node.js 22及以上版本：

bash

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

检查以下项：

YAML frontmatter格式合法（包裹在
```
---
```
标记之间）
类型要求的必填字段都已存在
枚举值与允许的取值范围匹配
日期格式为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

确认
```
global-type
```
字段值与类型名称完全匹配
检查
```
90-system/_types/
```
目录下的合法类型名称
若使用鸭子类型，确保特征字段都已存在

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

Schema文档：
```
90-system/docs/mdbase-schema.md
```
类型定义：
```
90-system/_types/
```
Obsidian base查询：
```
90-system/bases/
```
mdbase规范：https://github.com/callumalpass/mdbase-spec
mdbase CLI：https://github.com/callumalpass/mdbase-cli

tools-mdbase

Original

Translation

mdbase

mdbase

Monorepo vault setup

Monorepo知识库配置

Available types

可用类型

Type matching

类型匹配

CLI usage

CLI使用方法

Run from repo root

在仓库根目录执行

Create notes

创建笔记

Create a source note

创建一条来源笔记

Create with fields

携带字段创建

Create a task

创建一个任务

Create a project

创建一个项目

Create a person entity

创建一个人物实体

Create a publication

创建一个出版物

Query notes

查询笔记

All active projects

所有进行中的项目

Unreviewed sources

未审核的来源

Tasks by priority

按优先级查询任务

Overdue tasks

逾期任务

YouTube sources

YouTube来源

Projects sorted by deadline

按截止日期排序的项目

Limit results

限制返回结果数量

Validate

验证

Validate entire vault

验证整个知识库

Validate specific folder

验证指定文件夹

Validate single file

验证单个文件

Update notes

更新笔记

Mark source as reviewed

标记来源为已审核

Complete a task

标记任务为已完成

Update project deadline

更新项目截止日期

Read and inspect

读取与检查

Read a file

读取文件内容

Get vault statistics

获取知识库统计数据

Visualize links

可视化链接关系

Export and import

导入导出

Export projects to CSV

导出项目为CSV格式

Export sources to JSON

导出来源为JSON格式

Import tasks from CSV

从CSV导入任务

Rename with link updates

重命名并同步更新链接

Rename file and update all [[wikilinks]]