# renoun turns a repository into queryable content for docs and blogs

> renoun is a TypeScript SDK that queries and renders a codebase, treating MDX, Markdown, TypeScript and JavaScript files as structured data so indexes, navigations, API references and pages are generated from what is in the repository rather than maintained separately. It suits a team publishing technical content next to the code it documents, and it ships three starter templates.

**souporserious/renoun** — Query and Render Your Codebase

- Repository: https://github.com/souporserious/renoun
- Website: https://renoun.dev
- Stars: 614 · Forks: 14
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/souporserious-renoun

## The problem is drift between content and code

The why section is the clearest statement of the project and it is about a specific maintenance problem. Maintaining technical blogs, docs and presentations is hard because the source of truth is split between content files, code and examples, causing drift. The renoun SDK turns your codebase into structured, queryable data, files, exports, types and MDX, so you can render indexes, navigations, API references and pages directly from what is in the repository, keeping everything in sync as it changes. That is a narrower and more technical proposition than a documentation generator. A typical documentation site has a content directory and a source directory, and the two are connected by hand through imports and filenames, so a rename in the source breaks a reference in the content that nobody notices until a reader hits it. Here the reference is the import itself, resolved at build time. The tagline of Query and Render Your Codebase is literal rather than marketing, and the feature list backs it up: query files, MDX, MD and TS, like data, generate navigations and indexes from the file system, load and render module exports, and validate frontmatter and exports with schemas.

## The Directory object is the whole interface

The code example at the top of the README is short enough to read in full and it shows the shape of the API:

```tsx
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  loader: (path) => import(`./posts/${path}.mdx`),
})

async function Page({ slug }: { slug: string }) {
  const post = await posts.getFile(slug, 'mdx')
  const Content = await post.getContent()

  return <Content />
}
```

A Directory is constructed with a path and a loader, and the loader is a dynamic import function, which means the files are bundled rather than read from disk at runtime. From there the API is a small set of verbs. getFile takes a slug and a format extension and returns a file object, getContent resolves that file's content, and the returned value is a React component you can render directly. The file objects are what carry the rest of the capability, since a file knows its exports, its frontmatter and its type information, and the schemas validate those against a shape you declare. The result is that a route handler is three lines and the indexing, the navigation and the validation are handled by the library rather than by conventions you have to keep.

## Three templates that show the intended uses

The templates section describes three application templates, each with a live demo and its source in the examples/ directory. The Blog template is a blog starter with a post index, tags and MDX article pages. The Docs template is a documentation starter that turns MDX content into a polished, full-featured site. The Workbench template is a design system workbench for building, previewing and documenting libraries, which is the one aimed at a team documenting an API surface. The distinction between them is instructive because it shows the range. A blog is content with some structure, tags and an index. Documentation is navigation, a table of contents and cross-references. A workbench is the harder case, because it renders the actual exports of a library rather than prose about it, which is where the schema validation of frontmatter and exports starts to matter. All three are generated with the same command that the README puts at the top of the page, npx create-renoun@latest, which means the templates are the intended entry point rather than something you assemble by hand.

## A pnpm and Turbo monorepo with a published package

The repository layout shows a workspace rather than a single package. There are packages/ for the published code, apps/ for the site, examples/ holding the blog, docs and workbench starters, plus a .changeset/ directory for the release workflow, turbo.json for the task runner, pnpm-workspace.yaml and pnpm-lock.yaml, a vitest.config.ts at the root and a .prettierrc. The root package manifest is private and named renoun, with the build and dev scripts delegating to turbo run, and the filtered variants using pnpm filters such as build:site for the site and build:examples for the examples. The release script is worth reading closely, since it publishes recursively with pnpm publish -r --provenance --access public --publish-branch main and then runs pnpm changeset tag, which is the standard Changesets workflow with provenance attestations on the published artifacts. The validate script is unusual and interesting, because it runs the built CLI from packages/renoun/dist/cli/index.js with the validate argument, which means the schema validation the library offers is also available as a command line check, which is what you would run in CI. The engines field requires Node 20.19.0 or newer, and the package manager is pinned to pnpm 10.28.2.

## What the repository itself does not say

There are gaps in the documentation that a reader should be aware of rather than discover later. The README is short, covering the overview, the features, the templates, the why and the contributing and licence sections, and it points at the Contributing Guide for details on how to contribute. It does not describe the API surface beyond the single example, it does not list which frontmatter fields or export shapes the schemas accept, and it does not say how the loader is expected to behave in a non-bundler context. The topics listed on the repository give a sense of the ambitions, documentation, markdown, mdx, react, references, server-components, syntax-highlighting and typescript, with zero-config as a topic, which suggests the intent is that it should work with little setup. The release history shows renoun@11.7.1 on 2026-04-19, renoun@11.7.0 on 2026-03-30 and renoun@11.6.0 on 2026-03-24, so the versioning is at eleven with a rapid cadence, and the last push was on 2026-05-11, which means the code is being worked on more recently than the last release. The licence is MIT.

## Conclusion

Adopt renoun when your documentation or blog content lives in the same repository as the code it describes and the drift between them is the problem you are trying to solve. Do not adopt it as a general static site generator with content held elsewhere, because the value comes from reading the repository itself. Verify first that your content format is one it handles, since MDX, Markdown, TypeScript and JavaScript are the ones named, that your Node version meets the engine requirement and that you use the pinned pnpm version, and that the frontmatter and export shapes you have validate against the schemas you write.

## FAQ

### What does renoun actually do?

It turns your codebase into structured, queryable data, files, exports, types and MDX, so you can render indexes, navigations, API references and pages directly from what is in the repository. The four listed features are querying MDX, MD and TS files like data, generating navigations and indexes from the file system, loading and rendering module exports, and validating frontmatter and exports with schemas.

### How do I start a renoun project?

Run npx create-renoun@latest and pick one of the three templates: a Blog starter with a post index, tags and MDX article pages, a Docs starter that turns MDX into a full site, or a Workbench design system workbench for building, previewing and documenting libraries. Each has a live demo and its source in the examples directory.

### How do I query files with renoun?

Create a Directory with a path and a loader function, then use methods like getFile and getContent on it. The example passes a path of 'posts' with a loader of (path) => import(`./posts/${path}.mdx`), calls posts.getFile(slug, 'mdx') and awaits post.getContent(), which returns a React component you can render.

### What are the toolchain requirements for renoun?

Node 20.19.0 or newer, with pnpm pinned to 10.28.2 through the packageManager field. The repository is a Turbo workspace built with pnpm filters, tests run under Vitest with a Playwright browser provider, and releases go through Changesets with pnpm publish --provenance.

## Sources

- [License: MIT](https://github.com/souporserious/renoun/blob/main/LICENSE)
- [Project website](https://renoun.dev)
- [README](https://github.com/souporserious/renoun/blob/main/README.md)
- [Releases](https://github.com/souporserious/renoun/releases)
- [souporserious/renoun on GitHub](https://github.com/souporserious/renoun)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/souporserious-renoun