A content-first personal site built with Nuxt 4, Nuxt Content v3 and Tailwind CSS / Nuxt UI. It mixes a trilingual article stream and public learning series with a digital garden of interlinked concept notes, entities, and project pages. Content is authored in Obsidian — the sibling ../folio/content/ is the active Obsidian vault.
Live at: https://parz1.minerei.dev
- Framework — Nuxt 4 (Vue 3, TypeScript), pnpm-managed
- Content — @nuxt/content v3 with a Zod-validated multi-collection schema
- UI — Nuxt UI, Tailwind CSS 4, SCSS, GitHub-flavoured markdown typography
- i18n — @nuxtjs/i18n (English / 简体中文 / 日本語); content localized per-language as separate markdown variants
- CMS — Nuxt Studio (GitHub-backed editing), optional
- Analytics — @vercel/analytics + speed-insights
Paths below are relative to the external content workspace; the same paths in this repository are retained as rollback copies.
| Collection | Path | Purpose |
|---|---|---|
articles |
content/blog/articles/ |
Essays, logs, and loose thoughts selected by kind |
columns |
content/blog/columns/ |
Ordered public learning paths and planned chapters |
concepts |
content/concepts/ |
Digital-garden notes, linked via [[wikilinks]] |
entities |
content/entities/ |
Knowledge-graph nodes (tools, standards, instruments…) |
projects |
content/projects/ |
Projects bound to GitHub repos |
Schemas and validation live in content.config.ts.
Every Markdown document in content/ declares an ordered authors list. List order determines first/second author; optional roles record contributions such as idea, writing, and editing. See the coauthorship guide for Koto/parz1 examples, and run pnpm test:authors when changing attribution.
content/ is an Obsidian vault (config in content/.obsidian/). The content:file:beforeParse hook (utils/rubyHook.ts) converts on build:
{漢字|かな}→<ruby>furigana annotations[[wikilink]]→ internal links to/concepts/…or/blog/…
Use pnpm (the lockfile is pinned; hoisting is required by some native deps):
pnpm install --shamefully-hoistpnpm dev # dev server on http://localhost:3000
pnpm build # production build
pnpm generate # static export (nuxt generate)
pnpm preview # serve the production build locallyAfter adding Nuxt modules or changing content collections, refresh generated typings:
pnpm exec nuxt preparepnpm lint # oxlint
pnpm lint:fix
pnpm format # oxfmt (writes)
pnpm format:checkCopy .env.example to .env and fill in what you need:
NUXT_GITHUB_TOKEN— server-side GitHub status for project pages (no anonymous fallback)STUDIO_*— Nuxt Studio GitHub OAuth + access controlGALLERY_R2_*— optional Cloudflare R2 upload pipeline for the gallery
docs/cloudflare-preview.md— isolated Cloudflare test deployment and Web Analyticsdocs/gallery-media-workflow.md— gallery media pipelinedocs/concept-note-template.md— concept-note templateAGENTS.md— repository guidelines for agents & contributors
Production now reads published Folio releases at runtime: publishing ordinary Markdown does not rebuild the blog. SSR, search, lists and sitemap share a validated snapshot, with memory/shared-cache/bundled fallbacks. See runtime delivery and SEO. Build-time release URL/SHA settings below remain the cold-start fallback baseline.
The next design is local-first: editable Markdown plus local SQLite history, comments and a durable sync queue. A Vercel service provides multi-device synchronization and explicit publication backed by cloud storage; Git is not required. See the local-first design and implementation plan. This is documentation only; the existing pipeline below remains active until an explicit migration.
The default local content source is ../folio/content/, selected by publication.json; content/ in this repository is retained only as a rollback copy. Set CONTENT_WORKSPACE_DIR for another location. Unselected drafts and private discussions do not enter normal site collections.
pnpm build and pnpm generate prepare a fixed validated release first. CI may supply BLOG_CONTENT_RELEASE_FILE, or BLOG_CONTENT_RELEASE_URL plus BLOG_CONTENT_RELEASE_SHA256. Missing input fails rather than silently building old content. The previous Studio write path is disabled outside explicit BLOG_CONTENT_MODE=legacy rollback.
See workspace and deployment for local writing, reviewed digests, private Git, R2, CI integration and rollback; Koto pilot covers revision diff and inline discussions.