---
title: Markdown Repository — Query MDX Files with a Firestore-Style API
url: https://varstatt.com/toolkit/markdown-repository
description: Query .md and .mdx files by frontmatter with a Firestore-style API. Works with Next.js App Router and server components.
section: Developer Toolkit (https://varstatt.com/toolkit)
tags: markdown
---
# Markdown Repository

Query .md and .mdx files by frontmatter with a Firestore-style API. Works with Next.js App Router and server components.

## How It Works

1. **Point at a directory** — Create a MarkdownRepository with the path to your .md or .mdx files. Both extensions are supported by default.
2. **Build a query** — Compose constraints with where(), orderBy(), and limit() — the same pattern as Firestore's modular SDK.
3. **Execute with get()** — Call get() to read files, parse frontmatter, and return typed results. Get all items, one by slug, or query results.

## FAQ

### What file formats does it support?

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

### Does it work with Next.js?

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.

### Is it async?

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.

### How does recursive mode work?

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

### Can I validate frontmatter types?

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

### What happens if a file doesn't exist?

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

## Usage

This tool runs entirely in the browser — visit the URL above to use it.