Nuxt Content: a file-based CMS where Markdown is the database

The problem Nuxt Content solves for Nuxt 3 projects

Most content-driven sites end up with two systems that disagree: a git repository holding layouts and components, and a separate CMS holding text. Nuxt Content collapses that split. The README states that it reads the `content/` directory in your project, parses `.md`, `.yml`, `.csv` or `.json` files and creates a data layer for your application. The files stay in the repository, so a content change is a commit and a deploy rather than a database write through an API.

The audience is narrow and identifiable. If your application is built on Nuxt 3 and your writers can open a pull request, the module removes an entire integration surface. If your writers cannot, the module does not help, because the README lists no admin interface. It links to Nuxt Studio as a separate product, which is a signal about where editing is expected to happen.

The feature list is worth reading as a statement of intent rather than a checklist. Fully typed collections and queries, navigation generation, and a query builder on top of a SQLite database are all about treating files as records. Working in serverless and edge environments is the constraint that shapes the rest: a filesystem-based CMS has to behave when there is no persistent filesystem at runtime.

How the content/ directory becomes a queryable layer

The README describes the shape of the pipeline without detailing every stage. Files in `content/` are parsed, and the parsed result is exposed as collections that you query. The query builder sits on top of a SQLite database, which means queries are not a plain array filter over imported objects. That distinction matters at scale: a site with a few thousand Markdown files can be queried with sorting, filtering and field selection without loading everything into memory on each request.

The MDC syntax is the second half of the mechanism. Markdown files can contain Vue components, so a page is not limited to headings, paragraphs and code blocks. A component in a Markdown file runs as a Vue component in the rendered page, which is why the module describes itself as powered by Markdown and Vue components. The repository topics include `mdc` alongside `cms`, `git-cms` and `markdown`, so this is a first-class part of the design rather than an add-on.

Two supporting pieces appear in the feature list. Navigation generation means the module can derive navigation structures from the content tree instead of requiring a hand-maintained menu file. Code highlighting is delegated to Shiki. Both are the kind of thing a team would otherwise assemble from separate packages, and both are documented as part of the module rather than as optional plugins.

The serverless and edge support is the part worth thinking about hardest. A file-based CMS in a serverless environment has to resolve content at build time or from a bundled data source, because there is no writable disk to fall back on. The README asserts the capability without describing the mechanism, so the deployment target is something to confirm against your own hosting rather than assume.

Installing Nuxt Content and rendering a first page

The README does not include install commands; it links to the documentation at content.nuxt.com and lists development commands for the repository itself, such as `pnpm install`, `pnpm dev:prepare` and `pnpm dev`. Those are commands for working on the module, not for adding it to an application. For an application, the documented path is the module installation described on the documentation site, which is where you should read the current steps rather than copying the repository's own scripts.

The repository does ship runnable examples under `examples/`, with directories for `basic`, `blog`, `i18n` and `ui`. The package.json exposes an `example` script that runs `nuxt dev examples/$*`, so the examples are meant to be started directly. If you want to see the module working before wiring it into your own app, that is the shortest route the repository offers.

Once installed, the mental model is a directory and a query. You place Markdown files under `content/`, and pages query them. The README gives the directory name and the file extensions it parses, and states that collections and queries are typed. What the README does not give is a worked snippet showing a collection definition and a query call, so any code you write should follow the documentation site rather than a reconstructed example.

The development experience is one of the advertised features. The README lists fast hot module replacement in development, which for a file-based CMS means editing a Markdown file and seeing the result without a full rebuild. That is the loop you will spend most of your time in, and it is the reason the module is pleasant to use for writing even when the query layer is not the interesting part of your project.

Where the git-as-CMS model breaks down

The obvious limitation is editorial. A CMS that lives in a repository assumes every author has repository access and is willing to work with files. The README does not describe a web editing interface, and the link to Nuxt Studio is a separate product rather than a feature of this module. If your organisation has a marketing team that expects a login, a draft button and a preview URL, this module is the wrong tool and no amount of configuration changes that.

The second limitation is the one the README is quiet about. It states that the module works in serverless and edge environments, but it does not explain how content is made available there. For a file-based system, that question has real consequences: whether content is bundled at build time, whether a rebuild is required for every text change, and what happens when a preview deployment needs content that has not been published. The README does not document rollback either, so reverting a bad content change is a git operation you should plan for rather than something the module handles.

There is also a schema cost. Typed collections are a benefit, but they mean a content model that has to be maintained alongside the content. Renaming a field or changing a type is a code change with a migration attached, and the README does not describe a migration path. Teams used to schema-less Markdown will feel that friction.

Finally, the module is specific to Nuxt 3. The feature list begins with Nuxt 3 support, and the package is a Nuxt module. If your site is built on another framework, none of this transfers.

Nuxt Content compared with a headless CMS

The nearest alternative is a headless CMS: a hosted content store with an API, and a frontend that fetches from it at request time or build time. The difference in approach is where the content lives and who owns the write path. A headless CMS puts content in a database behind an HTTP API, with an editing interface and roles on top. Nuxt Content puts content in the repository and exposes it through a query layer that runs inside the Nuxt application.

That changes failure modes rather than removing them. With a headless CMS, a content update is live without a deploy, and the API is a runtime dependency that can be slow or unavailable. With Nuxt Content, content and code ship together, so a text fix is a deploy, but there is no external service between the reader and the page. For documentation sites, marketing pages and blogs where code and copy change together anyway, that trade is usually favourable. For a newsroom publishing dozens of updates a day, it is not.

The second alternative is a plain Markdown pipeline, such as a static site generator that turns files into HTML without a query layer. That is simpler and has fewer moving parts, but it gives up typed collections, the SQLite-backed query builder and component rendering inside Markdown. If you only need pages and never need to filter or sort content programmatically, the extra machinery of Nuxt Content is weight you are not using.

A third option worth naming is using Nuxt without any content module and importing Markdown through a bundler plugin. That works until you need navigation generation, typed collections or a query interface, at which point you are rebuilding parts of this module.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent: v3.16.1 on 2026-09-21, v3.16.0 on 2026-08-27 and v3.15.2 on 2026-07-23. That cadence is the practical signal here. A module that ships patch and minor releases roughly monthly is one where you should expect to move versions, and where pinning to an old minor will eventually put you behind fixes.

The upgrade cost is concentrated in the content layer. Typed collections mean a version bump can require changes to collection definitions and query calls, not just to a lockfile. The repository keeps a CHANGELOG.md at the top level, and there is a `docs/` directory alongside `examples/` and a `playground/`, so the material for reviewing a change before adopting it exists in the repository. Nothing in the README describes a deprecation policy or a support window for older majors, so how long a given major stays viable is not something you can read off the README.

Licensing is straightforward. The package.json declares `"license": "MIT"`, the repository carries a LICENSE file, and the README repeats the MIT designation. MIT permits commercial use and modification with the licence and copyright notice retained. That is a statement about the licence text, not legal advice; if your organisation has specific obligations around attribution or redistribution, have it reviewed rather than relying on this summary.

The dependency footprint is a real cost of adoption. The module builds on Nuxt, uses SQLite for queries and Shiki for highlighting, and the repository is a pnpm workspace with a lockfile and a Renovate configuration. You are taking on a module that itself takes on dependencies, and those are the things that will generate upgrade work between your own releases.

Editorial conclusion

Adopt Nuxt Content if your site is already a Nuxt 3 application and your authors are comfortable with git, because the content/ directory becomes the source of truth and the query layer is generated from it. Do not adopt it if you need non-technical editors publishing through a browser, since the repository describes no editorial UI of its own and points at Nuxt Studio instead. Before committing, verify two things in your own setup: that your deployment target is one of the serverless or edge environments the README names, and that your collection schemas survive a content/ directory of the size you actually have, because the README does not document rollback or migration behaviour for schema changes.

Frequently asked questions

Official sources

1. License: MIT
2. nuxt/content on GitHub
3. Project website
4. README
5. Releases