Contributing
This is the source for the MagicUtils documentation site — a
Nuxt app whose pages live as Markdown under content/,
rendered with @nuxt/content.
Run the docs locally
The project uses Bun.
bun run dev starts the dev server with hot reload. To produce and preview a
production build:
bun run typecheck runs the Nuxt/Vue type check.
Edit content
Documentation pages are Markdown files under content/; the folder maps
directly to URLs (content/getting-started/installation.md →
/getting-started/installation). Each page may set title and description
in its frontmatter — keep the description a single quoted line, since it feeds
the page's <meta description>, Open Graph tags, and the generated
llms.txt/llms-full.txt.
The sidebar order is defined in app/utils/nav.ts, not inferred from the
folder, so add new pages there too.
Versioned docs (maintainers)
The latest docs live in content/ and serve at the site root (URLs never
change, which is best for SEO). Each archived minor line lives under
content/v<minor>/ and serves at /v<minor>/...; archived pages are noindex
and canonicalise to their latest equivalent.
To freeze the current docs as an archived version when a new minor supersedes them:
This snapshots content/ into content/v<minor>/ and registers the archived
line in app/utils/versions.ts. It does not rewrite version strings inside the
Markdown — the update-version GitHub Actions workflow does that, opening a PR
that bumps the latest version in app/utils/versions.ts and every version
reference in content/ whenever a newer MagicUtils release appears on
maven.theroer.dev.
Deploy
Deployment is automated. Pushing to main triggers the build-and-push
workflow, which builds the site into a Docker image and pushes it to GHCR
(ghcr.io/<owner>/magicutils-website); the host then pulls the new image. There
is no manual deploy step.