From a3d2a3c9c0493d148f8b2640d1657018f4544066 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 20 May 2026 17:27:10 +0000 Subject: [PATCH 1/3] docs: add polished 'What is MarkdownDB?' concept page Refines the raw vision notes from issue #7 into a clean, structured document covering the pattern/library duality, core idea, concrete example, differentiators, and ideal use cases. Intended as the basis for an about page and/or landing page vision section. https://claude.ai/code/session_019sRzuSwYVt5MMiTK1Mj2gD --- site/docs/what-is-markdowndb.md | 92 +++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 site/docs/what-is-markdowndb.md diff --git a/site/docs/what-is-markdowndb.md b/site/docs/what-is-markdowndb.md new file mode 100644 index 0000000..f63aad0 --- /dev/null +++ b/site/docs/what-is-markdowndb.md @@ -0,0 +1,92 @@ +--- +title: What is MarkdownDB? +--- + +# What is MarkdownDB? + +MarkdownDB is two things: a **pattern** and a **library**. + +**The pattern**: treat a collection of markdown files as a database — each file is a record, its frontmatter and tags are structured fields, and you can query across them as you would any SQL database. + +**The library**: a JavaScript tool that implements that pattern. It indexes your markdown files into SQLite (or MySQL/PostgreSQL), extracts structured data like frontmatter, tags, links, and tasks, and gives you a clean API to query that data. + +## The Core Idea + +Markdown files are unusual: they combine unstructured prose with structured metadata. Most tools treat them as documents to be rendered. MarkdownDB treats them as *records in a database*. + +This turns out to be surprisingly powerful. A folder of markdown files becomes a queryable collection. You can ask: + +- *Get all blog posts tagged "tutorial" published in the last six months* +- *Find all documents that link back to this page* +- *List every unfinished task across my notes* + +## The Pattern: Markdown Files as Records + +A MarkdownDB has two components — just like any database: + +1. **The data**: your markdown files +2. **The index**: an SQLite database generated from those files + +The mapping is simple: + +- Each markdown file is a **record** +- Each directory can be a **table** (if you want it to be) +- Frontmatter fields become **queryable columns** +- Tags, links, and tasks are extracted into **related tables** + +### Example + +``` +my-collection/ + movies/ + return-of-the-jedi.md + a-new-hope.md + blog/ + first-post.md +``` + +`movies/return-of-the-jedi.md`: + +```md +--- +year: 1983 +budget: 32.7 +director: Richard Marquand +--- + +# Return of the Jedi + +Return of the Jedi is a 1983 American epic space opera film directed +by Richard Marquand... +``` + +After indexing, you can query with SQL: + +```sql +SELECT * FROM files +WHERE json_extract(metadata, '$.year') < 1985; +``` + +Or via the JavaScript API: + +```js +const films = await mddb.getFiles({ folder: "movies" }); +``` + +## What Makes MarkdownDB Different + +MarkdownDB has a deliberately narrow scope: build an index, provide an API. It does not get involved in rendering or site generation. + +- **Stack-agnostic** — works with Next.js, Astro, Nuxt, or no framework at all. Unlike Nuxt Content or Astro's content collections, it is not tied to a particular stack. +- **SQL-native** — standard SQL rather than a bespoke query language; no reinventing the wheel. +- **Extracts more than frontmatter** — inline body tags (`#mytag`), wikilinks (`[[page]]`), tasks (`- [ ] item`), forward links, and backlinks. +- **Open source** — your content stays in plain files; no vendor lock-in. +- **Focused** — it gives you data; it does not own your render pipeline. + +## When to Use MarkdownDB + +MarkdownDB is a good fit when: + +- Records mix rich text with structured metadata — blogs, wikis, personal notes, documentation, digital gardens +- Your collection is up to roughly 10,000 files +- You want to keep content in plain text but query it programmatically From 08641513f41d2f2361fbbb4496ee3593710cd643 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 21 May 2026 00:57:30 +0000 Subject: [PATCH 2/3] site: add about page and sharpen homepage vision section Adds site/about.md covering why MarkdownDB exists, what makes it different, the vision, and a link to the Markdown Database Pattern. Replaces the rambling homepage vision paragraph with tighter copy and a link out to markdownisawesome.com/markdown-database. https://claude.ai/code/session_019sRzuSwYVt5MMiTK1Mj2gD --- site/about.md | 39 +++++++++++++++++++++++++++++++++++++++ site/index.md | 6 ++++-- 2 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 site/about.md diff --git a/site/about.md b/site/about.md new file mode 100644 index 0000000..c4be6fb --- /dev/null +++ b/site/about.md @@ -0,0 +1,39 @@ +--- +title: About MarkdownDB +--- + +# About MarkdownDB + +MarkdownDB is a JavaScript library that turns a folder of markdown files into a queryable database. It extracts structured data — frontmatter, tags, links, tasks — indexes it into SQLite, and gives you a clean API to query across your content. + +Your files stay as plain text. You get the power of a database. + +## Why it exists + +Most content lives in one of two places: a CMS (structured and queryable, but locked in a platform) or plain markdown files (free and portable, but unqueryable). That's a false choice. + +Markdown files already contain structured data. Frontmatter fields, inline tags, links between pages, tasks — it's all there, sitting unused. MarkdownDB extracts it, indexes it, and makes it queryable. + +The underlying idea has a name: the [Markdown Database Pattern](https://markdownisawesome.com/markdown-database). MarkdownDB is its implementation in JavaScript. + +## What makes it different + +Other tools in this space — Contentlayer, Nuxt Content, Astro content collections — mix content indexing with rendering and tie you to a particular framework. MarkdownDB does one thing: build the index and provide the API. What you do with the data is up to you. + +- **Stack-agnostic** — works with any JavaScript framework, or none at all +- **SQL-native** — standard SQL on a real SQLite database, no custom query language +- **Focused** — does not own your render pipeline +- **Extracts more than frontmatter** — inline tags, wikilinks, backlinks, tasks +- **Open source** — MIT licensed, your content never locked in + +## The vision + +We believe content should be owned, open, and durable. + +Markdown is the closest thing the web has to a universal content format — plain text, readable without tools, writable in anything, storable in git. But choosing markdown has always meant giving up queryability. MarkdownDB closes that gap. + +The goal is a world where you never have to choose between the freedom of plain text and the power of structured data. + +## Built by Flowershow + +MarkdownDB is built and maintained by [Flowershow](https://flowershow.app), a team working on markdown-native tools for publishing and managing content. It is open source and contributions are welcome on [GitHub](https://github.com/flowershow/markdowndb). diff --git a/site/index.md b/site/index.md index 5462dc5..e6e0ce6 100644 --- a/site/index.md +++ b/site/index.md @@ -177,10 +177,12 @@ client.indexFolder({

Our vision

-

Unified Content Management

+

Your content, your database

- Imagine a world where Markdown isn't just text – it's a source of structured and unstructured data. With MarkdownDB, we aim to balance the simplicity and accessibility of writing in Markdown with the ability to query your collection of markdown files like a database – think get me all files "with type Blog" or "all documents created in the last week" or "all documents with 'hello world' in the title" or find "all tasks (i.e. - [ ]) in all documents". + Markdown files already contain structured data — frontmatter fields, tags, links, tasks. Most tools ignore it. MarkdownDB extracts it, indexes it, and makes it queryable, without touching your files or locking you into a platform.

+

Plain text in. Rich queryable data out.

+

Learn more about the Markdown Database Pattern →

From b641df33f5ae607e64139f482118035869e7f992 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 21 May 2026 02:09:22 +0000 Subject: [PATCH 3/3] site: remove what-is-markdowndb doc, superseded by about page https://claude.ai/code/session_019sRzuSwYVt5MMiTK1Mj2gD --- site/docs/what-is-markdowndb.md | 92 --------------------------------- 1 file changed, 92 deletions(-) delete mode 100644 site/docs/what-is-markdowndb.md diff --git a/site/docs/what-is-markdowndb.md b/site/docs/what-is-markdowndb.md deleted file mode 100644 index f63aad0..0000000 --- a/site/docs/what-is-markdowndb.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: What is MarkdownDB? ---- - -# What is MarkdownDB? - -MarkdownDB is two things: a **pattern** and a **library**. - -**The pattern**: treat a collection of markdown files as a database — each file is a record, its frontmatter and tags are structured fields, and you can query across them as you would any SQL database. - -**The library**: a JavaScript tool that implements that pattern. It indexes your markdown files into SQLite (or MySQL/PostgreSQL), extracts structured data like frontmatter, tags, links, and tasks, and gives you a clean API to query that data. - -## The Core Idea - -Markdown files are unusual: they combine unstructured prose with structured metadata. Most tools treat them as documents to be rendered. MarkdownDB treats them as *records in a database*. - -This turns out to be surprisingly powerful. A folder of markdown files becomes a queryable collection. You can ask: - -- *Get all blog posts tagged "tutorial" published in the last six months* -- *Find all documents that link back to this page* -- *List every unfinished task across my notes* - -## The Pattern: Markdown Files as Records - -A MarkdownDB has two components — just like any database: - -1. **The data**: your markdown files -2. **The index**: an SQLite database generated from those files - -The mapping is simple: - -- Each markdown file is a **record** -- Each directory can be a **table** (if you want it to be) -- Frontmatter fields become **queryable columns** -- Tags, links, and tasks are extracted into **related tables** - -### Example - -``` -my-collection/ - movies/ - return-of-the-jedi.md - a-new-hope.md - blog/ - first-post.md -``` - -`movies/return-of-the-jedi.md`: - -```md ---- -year: 1983 -budget: 32.7 -director: Richard Marquand ---- - -# Return of the Jedi - -Return of the Jedi is a 1983 American epic space opera film directed -by Richard Marquand... -``` - -After indexing, you can query with SQL: - -```sql -SELECT * FROM files -WHERE json_extract(metadata, '$.year') < 1985; -``` - -Or via the JavaScript API: - -```js -const films = await mddb.getFiles({ folder: "movies" }); -``` - -## What Makes MarkdownDB Different - -MarkdownDB has a deliberately narrow scope: build an index, provide an API. It does not get involved in rendering or site generation. - -- **Stack-agnostic** — works with Next.js, Astro, Nuxt, or no framework at all. Unlike Nuxt Content or Astro's content collections, it is not tied to a particular stack. -- **SQL-native** — standard SQL rather than a bespoke query language; no reinventing the wheel. -- **Extracts more than frontmatter** — inline body tags (`#mytag`), wikilinks (`[[page]]`), tasks (`- [ ] item`), forward links, and backlinks. -- **Open source** — your content stays in plain files; no vendor lock-in. -- **Focused** — it gives you data; it does not own your render pipeline. - -## When to Use MarkdownDB - -MarkdownDB is a good fit when: - -- Records mix rich text with structured metadata — blogs, wikis, personal notes, documentation, digital gardens -- Your collection is up to roughly 10,000 files -- You want to keep content in plain text but query it programmatically