@docspack/sheaf

The Sheaf content graph. A directory of Markdown becomes one serializable object that a site, a search index, and an agent-facing docs package can all be built from.

import { buildGraph } from "@docspack/sheaf";

const graph = await buildGraph("./docs");

for (const page of graph.pages) {
  console.log(page.slug, "—", page.title);
}

What it does

Reads every .md file under a directory, recursively, and returns them in reading order with the metadata a documentation site needs: slug, title, one-line summary, headings for a table of contents, and the source Markdown both with and without its leading # Title.

None of that metadata has to be declared. Order comes from a 03- filename prefix, the title from the first # H1, the summary from the first paragraph. Frontmatter overrides any of them:

---
title: An explicit title
description: Shown on the index page.
order: 2
draft: false
---

What it does not do

It does not render HTML. The graph carries Markdown plus structure, so the project that consumes it can use its own renderer — and so the consumers that want Markdown rather than HTML (llms.txt, per-page .md routes, a docspack package) get the source text unchanged.

It has no dependencies. Node builtins only.

API

• buildGraph(root) — read a directory into a ContentGraph. Throws if two pages would serve the same URL, or if a frontmatter block cannot be read.
• extractHeadings(markdown) — headings with anchor slugs, skipping fenced code.
• parseDocument(source, where) — split one document into frontmatter and body.

Full types are exported: ContentGraph, Page, Heading, Frontmatter.

Status

Early. The graph shape is versioned (graphVersion) and treated as a published contract, but it is 0.x and fields may still be added. See CLAUDE.md in this directory for the boundaries the package is built to, and the risks it carries.

MIT © docspack