Markdown Repository

Use markdown files like a database. Read directories of .md or .mdx files, query them by frontmatter fields, sort, filter, and limit — with an API modeled after Firestore.

$ npm install markdown-repository

Examples

import { MarkdownRepository, get } from "markdown-repository";

const posts = new MarkdownRepository("posts");
const all = get(posts);

Query Operators

All Firestore comparison operators, applied to frontmatter fields.

==Equal

!=Not equal

<Less than

<=Less than or equal

>Greater than

>=Greater than or equal

array-containsArray includes value

array-contains-anyArray includes any of values

inValue is one of

not-inValue is none of

Features

Firestore-style API

Functional query builder with where, orderBy, limit — compose constraints naturally.

.md and .mdx

Both extensions supported by default. No configuration needed.

Recursive directories

Nested folder structures with path-based slugs like discovery/worth-building.

TypeScript generics

Full type safety with custom validators. Generics flow through repository to query to get.

Zero config

Point at a directory, start querying. Sensible defaults for extensions and behavior.

Sync and lightweight

One dependency (gray-matter). Synchronous reads — perfect for static site generation.

Item Shape

interface MarkdownItem {
  slug: string;       // filename without extension
  content: string;    // markdown body after frontmatter
  excerpt: string;    // auto-extracted excerpt
  [key: string]: any; // all frontmatter fields
}

How It Works

Point at a directory

Create a MarkdownRepository with the path to your .md or .mdx files. Both extensions are supported by default.

Build a query

Compose constraints with where(), orderBy(), and limit() — the same pattern as Firestore's modular SDK.

Execute with get()

Call get() to read files, parse frontmatter, and return typed results. Get all items, one by slug, or query results.

Firestore-Style Query Builder for Markdown

markdown-repository brings Firestore's functional query pattern to local markdown files. Constraints are standalone functions that compose via query() and execute via get(). Filter by any frontmatter field using 10 operators: equality, comparison, array membership, and value membership.

where() with ==, !=, <, <=, >, >=, array-contains, array-contains-any, in, not-in
orderBy() with ascending or descending direction, multiple sort keys
limit() applied after filtering and sorting
Dynamic composition — build constraint arrays conditionally

Built for Static Sites and Content-Heavy Apps

Designed for Next.js, Astro, and any framework that reads content at build time. Synchronous reads work with generateStaticParams and getStaticProps. One dependency (gray-matter), TypeScript generics for type-safe frontmatter access, and recursive directory support for nested content structures.

FAQ

Markdown (.md) and MDX (.mdx) files with YAML frontmatter. Both extensions are included by default — no configuration needed.

Yes. The synchronous API works directly in generateStaticParams, route handlers, and server components. See the README for App Router examples with both flat and nested slug patterns.

The current API is synchronous, which is ideal for static site generation where all files are on disk. Async support may come in a future version.

Set recursive: true in the constructor options. Files in subdirectories get path-based slugs — for example, discovery/worth-building.mdx becomes the slug "discovery/worth-building".

Yes. Pass a TypeScript type guard as the validator option. Files that fail validation are excluded from getAll results, and getBySlug throws MarkdownRepositoryInvalidTypeError.

get(repo, "nonexistent-slug") throws MarkdownRepositoryNotFoundError. You can catch it to render a 404 page.

Built & Maintained by Varstatt

Varstatt is a one-person product studio run by Jurij Tokarski, product engineer since 2011. These tools are free and open — no signup, no catch.