Why Ginko (and when not)
Ginko fits content-heavy Nuxt 4 sites that publish from files and do not need a browser CMS workflow.
Choose Ginko for content-heavy Nuxt 4 sites where content lives in files and ships through Git. Define a collection for Markdown, YAML, JSON, or CSV, and Ginko derives typed queries, routing, navigation, localization, search, and sitemap data from it.
import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/config'
export const docs = defineCollection({
type: 'page',
source: 'docs/**/*.md',
route: '/docs'
})
export default defineContentConfig({
collections: { docs }
})Who it fits
Ginko is built for documentation sites, blogs and changelogs, marketing sites with substantial Markdown, and multilingual guides. It works best when developers or technical authors edit files in an IDE, Git gives you history and review, and branches give you draft environments.
The filesystem provider stays reasonable up to roughly 2,000 Markdown documents, depending on document size, locale count, search mode, and deployment target. That is where the design is aimed, not a hard parser limit.
What it leaves out on purpose
- No content database to provision. The filesystem provider builds the content snapshot from your files, so there is no separate database to migrate or keep in sync when you deploy.
- No browser editor or CMS workflow. Ginko ships no admin panel, roles, uploads, or approval states, so the core stays small and your content stays in Git.
- No unscoped global query. Every read goes through a collection handle, so the schema, route, and localization rules for those documents apply to every query automatically.
Ginko or Nuxt Content
Both declare collections in content.config.ts, use typed schemas, render Markdown and MDC, and support page and data collections. The choice is about architecture and scope.
| Decision | Ginko | Nuxt Content |
|---|---|---|
| Best fit | Small-to-medium filesystem-first sites | A broader Git-based content platform |
| Runtime storage | No content database in the default provider | SQLite-backed storage with runtime adapters |
| Query model | Collection handles for page, list, navigation, and server reads | Collection query builder backed by SQL |
| Localization | Locale variants, fallback, and translated slugs are core concepts | Official integration uses one collection per locale, resolved in app code |
| Browser editing | Outside Ginko core | Nuxt Studio provides a self-hosted editing workflow |
| Search | MiniSearch, Pagefind, or provider-owned search | Collection search sections and the wider ecosystem |
Nuxt Content has real advantages. Nuxt Content v3 generates a database dump and restores it into SQLite; client queries can use a browser WASM SQLite database, and Node installs can use better-sqlite3, sqlite3, or native SQLite. Do not choose Ginko because of the outdated claim that Nuxt Content requires one specific native package. Nuxt Studio is a free, open-source, self-hosted module, so browser editing is a genuine Nuxt Content advantage. The official Nuxt Content i18n guide defines a collection per locale and resolves fallback in application code; Ginko makes fallback part of the content model.
Sources: Nuxt Content overview, SQLite options, database architecture, i18n integration, Nuxt Studio OSS.
When to pick something else
- Non-technical authors need to edit and publish in a browser today.
- Editors must publish without a deployment; the filesystem provider only reads deployed files.
- The dataset is very large and ad hoc queries define the project.
- Editorial workflow itself is the product: permissions, approvals, scheduled publishing, audit policy.
- Nuxt 4 is not your framework; Ginko is not a framework-neutral generator.
Do not add a CMS for hypothetical future needs. When a real CMS becomes necessary, the provider contract lets it replace the filesystem without changing collection-based page queries.