create-ginko 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# create-ginko
+
+## 0.4.0
+
+### Minor Changes
+
+- [`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add Ginko 0.4, the first release: one content system for Nuxt websites, from Markdown files in Git to a hosted platform.
+  
+  Owners, staff and AI agents edit the same content. All seven packages release together under one version. It starts at 0.4 because `@lupinum/ginko-content` and `@lupinum/ginko-docs` already published an older, unrelated line up to 0.3. Until 1.0, a minor version (0.4 → 0.5) may contain breaking changes; the changelog names each one and how to update.
+  
+  Requirements: Node 22.18+, 24 or 26, and Nuxt 4.6+ or Nuxt 5 (tested on its nightly until it is released). Start a site with `npm create ginko@latest my-site`; the documentation explains every step.
+  
+  **Public API**
+  
+  - `@lupinum/ginko`: `defineSite`, `single`, `collection`, `f`, `defineComponents`, `formatMoney`, `plainText`, `safeHref`, `startOfWeek` and the documented types. Imported, not auto-imported.
+  - `@lupinum/ginko/nuxt`: the module, the `useGinko*` composables (everything that needs a Nuxt app starts with `useGinko`), `<GinkoMarkdown>` and `<GinkoImage>`. `@lupinum/ginko/vue`: `<GinkoMarkdown>` for any Vue app. `@lupinum/ginko/search`: `loadIndex` and `search`.
+  - `@lupinum/ginko/internal` and `@lupinum/ginko/internal/search` are for Ginko's own packages and have no stability promise.
+  - The `ginko` CLI: `check [--offline]`, `release` and `export [folder]`, plus `--version`. Every command run prints one JSON line, `{ "ok": true, … }` or `{ "ok": false, "error": { code, message } }` (`--help` and `--version` print plain text), and ends with exit code 0 (ok), 1 (fix the code), 2 (usage), 3 (platform unreachable, retry) or 4 (key not allowed). CI deploys the site only when `release` prints `"deploy": true` (a superseded run exits 0 with `"deploy": false`). The CLI reads `GINKO_PLATFORM` (or `NUXT_PUBLIC_GINKO_PLATFORM`), `GINKO_KEY`, `GINKO_COMMIT` (or `GITHUB_SHA`), `GINKO_BRANCH` and `GINKO_REMOTE`; it does not read `.env` files. `ginko-i18n --json` uses the same output shape, error codes (`USAGE`, `INVALID`) and exit codes.
+  - Config names: `f.ref` (one entry) and `f.refs` (several); `visible: { mode: 'until', field, days?, deleteExpired? }`; prefill tokens `@today`, `@workWeek`, `@nextWorkWeek`; `firstDayOfWeek`, `linkCheck`, `untranslated`, `maxBytes`, `Migration.compute`, `retired` rule `{ drop: true }`. Options and defaults are typed per field, and an unknown top-level key fails the build.
+  - Markdown components: `embed`, `frame` (`none`, `card`, `border`, …), `background` (`none`, `muted`, `tint`), `appearance` (`quiet`, `tint`), `quiz-question{mode}`, `code-tree{file}`.
+  
+  **Content (`@lupinum/ginko`, `@lupinum/ginko-content`)**
+  
+  - One text format: Markdown (comark 0.7) everywhere, with field profiles that limit what a field may contain. Footnotes, emoji, alerts, Shiki code, task lists, route links (`$blog.my-post`), reusable snippets and heading anchors.
+  - Data files: YAML and JSON (one file, one entry) and CSV (one file, many entries), checked against the field schema; every error names the file and field, and the line for CSV rows and unreadable files. Entries with `draft: true` stay out of production builds.
+  - Query engine in the site, over the loaded bundle: `where`, `order`, `limit`, pagination with totals, field selection, `include` for references, previous/next and facet counts.
+  - References (`f.ref`, `f.refs`), navigation trees and breadcrumbs, and a URL for every entry in every language; two entries on one URL fail the build.
+  - Link check before any HTML exists: route links, anchors, snippets and redirected paths, in the build, the dev terminal, `ginko check` and the agent tools. On the platform a save, a new entry or a scheduled publish that adds a broken link is stopped, and History says why. External links are checked on request (`linkCheck.external`), at build and in `ginko check` (never in dev), with a 7-day cache.
+  - Images: WebP copies at 480, 960 and 1600 px, made at upload on the platform and at build for files. `<GinkoImage>` and Markdown images get `srcset` and `sizes`.
+  - Redirects from `redirectFrom` (301) and site rules in `redirects` (301 by default, `status` 302/307/308 per rule).
+  - SEO from the bundle, with no other module: title template, canonical, Open Graph with `og:url`, `<html lang>`, hreflang with `x-default`, sitemap with `lastmod`, images and alternates, robots.txt with `noindex` on preview hosts, JSON-LD. With `nuxt-og-image` (in every starter), every page gets a generated share card in the brand colour `seo.color`, with the site's logo and the page's image.
+  - Works with the Nuxt SEO modules (`@nuxtjs/seo` or single ones, in any order): Ginko leaves them sitemap, robots.txt and JSON-LD defaults and hands them its pages with hreflang, the site's address, name and languages, and `noindex` on preview hosts. `nuxt-ai-ready` stays off while Ginko serves `/llms.txt`. Requires `nuxt-og-image` 7.
+  - Search index built in plain JS at build time, one record per heading section, loaded lazily per language.
+  - Agent output: `/llms.txt`, `/llms-full.txt`, a `.md` twin for every entry page (collections with a `route`), and a Markdown 404 that suggests pages. The normal address always answers with HTML.
+  - Render modes: Git-only sites prerender everything; platform sites refresh changed pages after a publish; previews render with `noindex`.
+  - In dev, `nuxt dev` restarts when `ginko.config.ts` changes, and a brick that cannot reach the platform names itself and the fix.
+  - CLI `ginko`: `check` (schema, links and the share image, for every site; `--offline` without the platform) and `release` for CI, `export` for backups; `pnpm local:dev|import|pull` run only in the Ginko monorepo.
+  
+  **Languages (`@lupinum/ginko-i18n`)**
+  
+  - The only locale authority: routes, alternates, hreflang, messages with plurals, and formatters for dates, ranges, relative time, numbers, currency and lists, each in the site's time zone.
+  - Works on its own in any Nuxt 4.6+ or Nuxt 5 app, without the rest of Ginko.
+  
+  **Components and docs (`@lupinum/ginko-components`, `@lupinum/ginko-docs`)**
+  
+  - Content components with props defined as Ginko fields: callouts, tabs, code groups, steps, cards, accordion, figures, embeds (click to load), timeline, quiz and more. Each one can also be copied into an app with the shadcn-vue CLI, from a registry the docs build generates.
+  - Docs layer (`@lupinum/ginko-docs`; `npm create ginko@latest my-docs -- --preset docs` starts a site with it): navigation, section tabs, breadcrumbs, table of contents with scroll spy, previous/next, ⌘K search with heading results, blog with authors and RSS, changelog, copy page as Markdown, dark mode. A guide for switching from Nuxt Content and `@nuxtjs/i18n`. Math (KaTeX) and mermaid diagrams render and load only on pages that use them.
+  
+  **Platform and Studio (hosted by Lupinum)**
+  
+  The platform is a hosted service, not an npm package. A site connects to it with one setting; without it, the site reads its content from files.
+  
+  - Quick tasks for the jobs owners do most ("Heute geschlossen", "Preis ändern"), phone first, with the full form behind "Alles bearbeiten".
+  - Files library: All, Recent, Unused, Missing alt text, Duplicates and folders; icon and list views; "used in" with links; replace a file and keep its references; a used file cannot be removed by mistake. Alt text set in the library is the default for every use, per language.
+  - Approvals, off by default: a task or agent key can need a yes. Reviewers see the change, approve, approve for a time, or reject with a sentence; the author sees the reason. Releases publish several changes together.
+  - History with "show changes", "back to this version" and undo; drafts and scheduled publishing; trash with restore; translation status per language; "why is this not on the website?".
+  - Team and invitations with per-task rights, sign-in with an emailed code, AI agent keys with an MCP tool catalog derived from the operations, and weekly reminder mails.
+  - Long forms group their fields under headings or in tabs (`group` on a field, `layout: 'tabs'` on a brick); phones always show headings.
+  - A rich text editor (TipTap 3) that writes Markdown, where untouched text stays byte for byte. Headings, lists, task lists, quotes, code blocks, tables, images from the library, embeds, registry components with prop forms, slash and bubble menus, Markdown shortcuts and paste, source mode, find and replace (⌘F), a drag handle and Alt+↑/↓ to move blocks, character counter, a link card for pasted URLs, uploads with progress, and a formatting bar above the phone keyboard.
+  - Delete a site, with seven days to cancel, and delete your own account. The last owner of a site must hand it over or delete it first.
+  - Studio in German, English and Spanish (beta), light and dark.
+  
+  **Presets (`@lupinum/ginko-preset-gastro`, `create-ginko`)**
+  
+  - Gastro: opening hours with exceptions, seasons, holidays and new hours from a date; lunch week with planning ahead and an optional PDF; menu with prices from a date; notices that expire; events; JSON-LD for Restaurant, Menu, opening hours and Event; a printable lunch sheet.
+  - `create-ginko` starts a new site, plain or with `--preset gastro|docs`. Starters install with npm, pnpm 11 and bun, carry a `typecheck` script, a page description and share cards (`nuxt-og-image` with Takumi, Nuxt 4.6.1 or later; set `NUXT_APP_SECRET` where the site runs, `.env` has one), and create-ginko warns on an unsupported Node.
+  
+  **Not in 0.4**
+  
+  Real-time co-editing comes next. Also not included: an agency preset, the editor UI as a shadcn-vue registry, OAuth for agent connectors, and a Google Business sync.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Lupinum OG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# create-ginko
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start a Nuxt site with [Ginko](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko):
+
+```bash
+npm create ginko@latest my-site
+cd my-site
+npm install
+npm run dev
+```
+
+The new site reads its content from Markdown in `content/` and needs no platform. To let an owner
+edit a brick on the Ginko platform instead, remove `source: 'files'` from it in `ginko.config.ts`,
+and give the single's required fields a `default` or make them optional (`f.markdown`, `f.image` and `f.file` cannot have a default, so set `optional: true` on them). See
+[Platform and CLI](https://github.com/lupinum-dev/ginko/blob/main/sites/docs/content/docs/12.plattform-und-cli.en.md).
+
+The sample site is English. `--locale de` creates it in German.
+
+The site id (`site` in `ginko.config.ts`) comes from the folder name: lower case, every run of other characters
+becomes `-`, at most 40 characters, and it must start with a letter. When the id differs from the folder name, the
+command says so. Change `site` in `ginko.config.ts` if you want another id.
+
+## Options
+
+Write the options after `--`. npm keeps options before `--` for itself and passes on only their values; the
+command then stops and shows the right form. pnpm, yarn and bun accept the same command.
+
+```bash
+npm create ginko@latest my-site -- --locale de
+npm create ginko@latest my-restaurant -- --preset gastro
+npm create ginko@latest my-docs -- --preset docs
+```
+
+| Option | Values | Default |
+|---|---|---|
+| `--preset <name>` (or `--preset=<name>`) | `gastro`, `docs` | the plain starter |
+| `--locale <code>` (or `--locale=<code>`) | `en`, `de` | `en` |
+| `-h`, `--help` | | |
+
+The command always says which starter and language it used. An unknown option, preset or locale stops
+with exit code 2 (a usage error, as in the `ginko` CLI) and creates nothing. A folder that exists and is not
+empty stops with exit code 1.
+
+## Presets
+
+| Preset | Package | What the starter shows | Platform needed? |
+|---|---|---|---|
+| `gastro` | `@lupinum/ginko-preset-gastro` | Opening hours and a menu, both read from files | Only for the preset's other bricks (notices, lunch, events, gallery) and the owner's quick tasks. The starter itself runs without it. |
+| `docs` | `@lupinum/ginko-docs` | The docs layer (navigation, search) with two pages in `content/docs/` | No |
+
+Each preset is a small folder in `presets/` that is copied over `template/`; `presets/<name>-de` is its German
+version. `template-de/` holds the German sample text of the plain starter.
+
+## License
+
+MIT © Lupinum OG

package/index.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// npm create ginko <folder> [-- --preset gastro|docs] [--locale en|de]: copies template/ into a new folder and sets
+// the site id and the Ginko versions. The Ginko packages release together, so they get this package's own version.
+// A preset is a small folder in presets/ that is copied over the base template and adds the preset's packages.
+// German: template-de/ goes over the base template; a preset has its own folder `<preset>-de`.
+import { randomBytes } from 'node:crypto'
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { supportsNode } from './node-version.mjs'
+
+// preset name -> the packages it adds (its own package, then the Ginko peers of that package that the base template
+// lacks; test/create-ginko.test.ts checks this against the packages' metadata), and what the next steps say about it
+const presets = {
+  gastro: { packages: ['@lupinum/ginko-preset-gastro'], note: 'Hours and menu read from files. The preset\'s other bricks (notices, lunch, events, gallery) and the owner\'s quick tasks need the Ginko platform.' },
+  docs: { packages: ['@lupinum/ginko-docs'], note: 'Pages are Markdown files in content/docs. No platform needed.' },
+}
+const langs = { en: 'English', de: 'German' }
+const command = 'npm create ginko@latest'
+const usage = `Usage: ${command} <folder> -- [--preset gastro|docs] [--locale en|de]
+
+Creates a Nuxt site with Ginko that reads its content from Markdown files.
+
+  --preset <name>  start from a preset: gastro (restaurant) or docs (documentation)
+  --locale <code>  locale code of the sample site: en (default) or de
+  -h, --help       show this help
+
+With npm, write -- before the options. Without it, npm keeps them for itself.`
+
+/** Prints the problem and the usage, and stops without creating anything. Exit 2 is a usage error, as in `ginko`. */
+function fail(message) {
+  console.error(`${message}\n\n${usage}`)
+  process.exit(2)
+}
+
+const args = process.argv.slice(2)
+let target
+let preset
+let lang = 'en'
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]
+  // pnpm and yarn may pass the `--` of `pnpm create ginko my-site -- --preset gastro` through.
+  if (arg === '--') continue
+  if (arg === '-h' || arg === '--help') { console.log(usage); process.exit(0) }
+  if (arg === '--preset' || arg === '--locale') {
+    const value = args[++i]
+    if (!value || value.startsWith('-')) fail(`${arg} needs a value.`)
+    if (arg === '--preset') preset = value
+    else lang = value
+  }
+  else if (arg.startsWith('--preset=')) preset = arg.slice('--preset='.length)
+  else if (arg.startsWith('--locale=')) lang = arg.slice('--locale='.length)
+  else if (arg.startsWith('-')) fail(`Unknown option "${arg}".`)
+  else if (target === undefined) target = arg
+  // npm drops `--preset` written without `--` and passes only its value, so a second name is almost always that.
+  else if (Object.hasOwn(presets, arg)) fail(`Unexpected argument "${arg}". npm drops --preset when it comes before --. Write:\n  ${command} ${target} -- --preset ${arg}`)
+  else if (Object.hasOwn(langs, arg)) fail(`Unexpected argument "${arg}". npm drops --locale when it comes before --. Write:\n  ${command} ${target} -- --locale ${arg}`)
+  else fail(`Unexpected argument "${arg}". Give one folder name.`)
+}
+if (preset !== undefined && !Object.hasOwn(presets, preset)) {
+  fail(`Unknown preset "${preset}". Choose one of: ${Object.keys(presets).join(', ')}.`)
+}
+if (!Object.hasOwn(langs, lang)) fail(`Unknown language "${lang}". Choose one of: ${Object.keys(langs).join(', ')}.`)
+const presetDir = preset && (lang === 'en' ? preset : `${preset}-${lang}`)
+if (presetDir && !existsSync(new URL(`./presets/${presetDir}`, import.meta.url))) {
+  fail(`The ${preset} preset has no ${langs[lang]} version yet. Leave out --locale ${lang}.`)
+}
+if (!target) fail('Give the name of the folder to create.')
+const dir = resolve(target)
+if (existsSync(dir) && readdirSync(dir).length) {
+  console.error(`The folder ${target} exists and is not empty. Choose another name.`)
+  process.exit(1)
+}
+const site = basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'my-site'
+if (!/^[a-z]/.test(site)) {
+  console.error(`The site id "${site}" must start with a letter. Choose another folder name.`)
+  process.exit(1)
+}
+const own = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+// A warning, not an error: the site is still created, and the user may run it on another Node.
+if (!supportsNode(process.versions.node, own.engines.node)) {
+  console.warn(`Warning: Ginko needs Node ${own.engines.node}, but this is Node ${process.versions.node}. The site is created, but install and dev may fail or print warnings. Switch to a supported Node version before you run "install".\n`)
+}
+cpSync(new URL('./template', import.meta.url), dir, { recursive: true })
+// npm drops .gitignore from published packages, so the template carries it as `gitignore`.
+renameSync(join(dir, 'gitignore'), join(dir, '.gitignore'))
+if (presetDir) {
+  // The base page and sample text give way to the preset's own.
+  rmSync(join(dir, 'content/start.md'))
+  rmSync(join(dir, 'app/pages/index.vue'))
+  cpSync(new URL(`./presets/${presetDir}`, import.meta.url), dir, { recursive: true })
+}
+else if (lang !== 'en') cpSync(new URL(`./template-${lang}`, import.meta.url), dir, { recursive: true })
+for (const file of ['package.json', 'ginko.config.ts']) {
+  const path = join(dir, file)
+  writeFileSync(path, readFileSync(path, 'utf8').replaceAll('{{SITE}}', site).replaceAll('{{VERSION}}', own.version))
+}
+if (preset) {
+  const path = join(dir, 'package.json')
+  const pkg = JSON.parse(readFileSync(path, 'utf8'))
+  for (const name of presets[preset].packages) pkg.dependencies[name] = `^${own.version}`
+  pkg.dependencies = Object.fromEntries(Object.entries(pkg.dependencies).sort(([a], [b]) => a.localeCompare(b)))
+  writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`)
+}
+
+// The share cards (nuxt-og-image) sign their URLs with this secret; `nuxt dev` and `nuxt preview` read .env.
+writeFileSync(join(dir, '.env'), `# Signs the share card URLs. Set the same variable where the site runs.\nNUXT_APP_SECRET=${randomBytes(32).toString('hex')}\n`)
+
+// The next steps name the package manager that ran us (npm, pnpm, yarn or bun), and quote a folder a shell would split.
+const agent = (process.env.npm_config_user_agent ?? '').split('/')[0]
+const pm = ['pnpm', 'yarn', 'bun'].includes(agent) ? agent : 'npm'
+const cd = /^[\w./-]+$/.test(target) ? target : `'${target.replaceAll('\'', '\'\\\'\'')}'`
+console.log(`Created ${target} from the ${preset ? `${preset} preset` : 'plain starter'} in ${langs[lang]}.`)
+if (site !== basename(dir)) console.log(`The site id is "${site}": the folder name in lower case, with other characters replaced by "-", at most 40 characters. Change \`site\` in ginko.config.ts to use another one.`)
+if (preset) console.log(presets[preset].note)
+// npm keeps options for itself unless they come after --; pnpm, yarn and bun pass them on.
+const example = pm === 'npm' ? `${command} my-site -- --preset gastro` : `${pm} create ginko my-site --preset gastro`
+console.log(`Other starters: --preset gastro, --preset docs; German sample: --locale de.${pm === 'npm' ? ' With npm, put -- before them:' : ''}
+  ${example}
+
+Next:
+
+  cd ${cd}
+  ${pm} install
+  ${pm} run dev
+
+Before you deploy, set NUXT_APP_SECRET where the site runs (any 32 or more random characters, .env has one).
+Without it, the share cards of a server-rendered site answer with an error; a static build needs none.
+`)

package/node-version.mjs

@@ -0,0 +1,10 @@
+// Is this Node version inside an `engines.node` range of caret alternatives ("^22.18.0 || ^24.0.0")?
+// Only that shape is supported: it is what all Ginko packages declare.
+export function supportsNode(version, range) {
+  const [major, minor, patch] = version.split('.').map(Number)
+  return range.split('||').some((alternative) => {
+    const [wantMajor, wantMinor = 0, wantPatch = 0] = alternative.trim().replace(/^\^/, '').split('.').map(Number)
+    if (major !== wantMajor) return false
+    return minor > wantMinor || (minor === wantMinor && patch >= wantPatch)
+  })
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "create-ginko",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Start a Ginko site: npm create ginko my-site",
+  "bin": {
+    "create-ginko": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "node-version.mjs",
+    "template",
+    "template-de",
+    "presets",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lupinum-dev/ginko.git",
+    "directory": "packages/create-ginko"
+  },
+  "homepage": "https://github.com/lupinum-dev/ginko",
+  "bugs": {
+    "url": "https://github.com/lupinum-dev/ginko/issues"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/presets/docs/app/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/presets/docs/content/docs/1.getting-started.md

@@ -0,0 +1,12 @@
+---
+title: Getting started
+description: What this site is and how to add a page.
+---
+
+## Add a page
+
+Every page is a Markdown file in `content/docs/`. The number before the name sets the order in the side navigation.
+
+## Next
+
+Read [Writing pages]($docs.writing-pages) to see the frontmatter fields.

package/presets/docs/content/docs/2.writing-pages.md

@@ -0,0 +1,14 @@
+---
+title: Writing pages
+description: The frontmatter fields of a docs page.
+---
+
+## Frontmatter
+
+- `title` and `description` appear at the top of the page and in search.
+- `section` groups pages in the side navigation.
+- `parent` nests a page under another one.
+
+::callout
+Change a file, save, and the page updates.
+::

package/presets/docs/ginko.config.ts

@@ -0,0 +1,21 @@
+// A documentation site: the layout, side navigation and search come from @lupinum/ginko-docs.
+// Every page is a Markdown file in content/docs/.
+import { defineSite } from '@lupinum/ginko'
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
+
+const locales = ['en'] as const
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // change for your country
+  locales,
+  currency: 'EUR', // change for your country
+  pages: { home: '/' },
+  // Shown in search results and link previews. Replace it with one sentence about your site.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Documentation for our product.', color: '#047857' },
+  components, // the Markdown components (::callout, ::tabs …) and their checked props
+  bricks: { docs: docsCollection({ locales }) },
+})

package/presets/docs/nuxt.config.ts

@@ -0,0 +1,9 @@
+import ginko from './ginko.config.ts'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-01',
+  extends: ['@lupinum/ginko-docs'],
+  // nuxt-og-image draws a share card for every page (Ginko passes title, image, logo and `seo.color`).
+  modules: ['@lupinum/ginko/nuxt', 'nuxt-og-image'],
+  ginko,
+})

package/presets/docs-de/app/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/presets/docs-de/content/docs/1.einstieg.md

@@ -0,0 +1,12 @@
+---
+title: Einstieg
+description: Was diese Seite ist und wie du eine Seite ergänzt.
+---
+
+## Eine Seite ergänzen
+
+Jede Seite ist eine Markdown-Datei in `content/docs/`. Die Zahl vor dem Namen legt die Reihenfolge in der Seitennavigation fest.
+
+## Weiter
+
+Lies [Seiten schreiben]($docs.seiten-schreiben), um die Felder im Frontmatter zu sehen.

package/presets/docs-de/content/docs/2.seiten-schreiben.md

@@ -0,0 +1,14 @@
+---
+title: Seiten schreiben
+description: Die Felder im Frontmatter einer Doku-Seite.
+---
+
+## Frontmatter
+
+- `title` und `description` stehen oben auf der Seite und in der Suche.
+- `section` fasst Seiten in der Seitennavigation zu Gruppen zusammen.
+- `parent` hängt eine Seite unter eine andere.
+
+::callout
+Ändere eine Datei, speichere sie, und die Seite aktualisiert sich.
+::

package/presets/docs-de/ginko.config.ts

@@ -0,0 +1,21 @@
+// Eine Doku-Seite: Layout, Seitennavigation und Suche kommen aus @lupinum/ginko-docs.
+// Jede Seite ist eine Markdown-Datei in content/docs/.
+import { defineSite } from '@lupinum/ginko'
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
+
+const locales = ['de'] as const
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // für dein Land ändern
+  locales,
+  currency: 'EUR', // für dein Land ändern
+  pages: { home: '/' },
+  // Steht in Suchergebnissen und Link-Vorschauen. Ersetze es durch einen Satz über deine Website.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Dokumentation zu unserem Produkt.', color: '#047857' },
+  components, // die Markdown-Komponenten (::callout, ::tabs …) und ihre geprüften Props
+  bricks: { docs: docsCollection({ locales }) },
+})

package/presets/docs-de/nuxt.config.ts

@@ -0,0 +1,9 @@
+import ginko from './ginko.config.ts'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-01',
+  extends: ['@lupinum/ginko-docs'],
+  // nuxt-og-image draws a share card for every page (Ginko passes title, image, logo and `seo.color`).
+  modules: ['@lupinum/ginko/nuxt', 'nuxt-og-image'],
+  ginko,
+})

package/presets/gastro/app/pages/index.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { formatMoney } from '@lupinum/ginko'
+import { priceOn, timesOf, weekdayNames, type Weekday } from '@lupinum/ginko-preset-gastro'
+
+const hours = useGinko('hours')
+const menu = useGinko('menu')
+const today = useGinkoToday()
+const { language } = useI18n()
+const categories = [['starters', 'Starters'], ['soups', 'Soups'], ['mains', 'Mains'], ['desserts', 'Desserts'], ['drinks', 'Drinks']] as const
+useGinkoSeo({ title: 'Menu and opening hours' })
+</script>
+
+<template>
+  <main>
+    <h1>Opening hours</h1>
+    <table>
+      <tbody>
+        <tr v-for="d in hours.data.week" :key="d.day">
+          <th scope="row">{{ weekdayNames.en[d.day as Weekday] }}</th>
+          <td>{{ d.closed ? 'Closed' : timesOf(d, 'and') }}</td>
+        </tr>
+      </tbody>
+    </table>
+    <h1>Menu</h1>
+    <section v-for="[key, title] in categories.filter(([k]) => menu.items.some((i) => i.data.category === k))" :key="key">
+      <h2>{{ title }}</h2>
+      <ul>
+        <li v-for="dish in menu.items.filter((i) => i.data.category === key)" :key="dish.id">
+          <strong>{{ dish.data.name }}</strong>, {{ formatMoney(priceOn(dish.data, today), language) }}
+          <br>{{ dish.data.description }}
+        </li>
+      </ul>
+    </section>
+  </main>
+</template>

package/presets/gastro/content/hours.md

@@ -0,0 +1,12 @@
+---
+week:
+  - { day: mo, closed: true }
+  - { day: tu, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: we, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: th, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: fr, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "23:00" }
+  - { day: sa, closed: false, from1: "11:30", to1: "23:00" }
+  - { day: su, closed: false, from1: "11:30", to1: "20:00" }
+exceptions: []
+holidayNoticeDays: 14
+---

package/presets/gastro/content/menu/1.tomato-soup.md

@@ -0,0 +1,7 @@
+---
+category: soups
+name: Tomato soup
+description: Roasted tomatoes, basil and a spoon of cream.
+price: 6.5
+veg: vegetarian
+---

package/presets/gastro/content/menu/2.house-burger.md

@@ -0,0 +1,7 @@
+---
+category: mains
+name: House burger
+description: Beef patty, cheddar, pickles and fries.
+price: 14.9
+veg: none
+---

package/presets/gastro/content/menu/3.garden-salad.md

@@ -0,0 +1,7 @@
+---
+category: starters
+name: Garden salad
+description: Seasonal leaves, seeds and lemon dressing.
+price: 8.5
+veg: vegan
+---

package/presets/gastro/content/menu/4.apple-tart.md

@@ -0,0 +1,7 @@
+---
+category: desserts
+name: Apple tart
+description: Warm apple tart with vanilla ice cream.
+price: 5.9
+veg: vegetarian
+---

package/presets/gastro/ginko.config.ts

@@ -0,0 +1,23 @@
+// Opening hours and a menu from the gastro preset, both read from Markdown files in content/.
+// The preset's other bricks (notices, lunch, events, gallery) and the owner's quick tasks need the Ginko platform.
+import { defineSite } from '@lupinum/ginko'
+import { hours, menu } from '@lupinum/ginko-preset-gastro'
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // change for your country
+  locales: ['en'],
+  currency: 'EUR', // change for your country
+  pages: { home: '/' },
+  // Shown in search results and link previews. Replace it with one sentence about your site.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Opening hours and menu of our restaurant.', color: '#1e4032' },
+  bricks: {
+    // content/hours.md: weekly hours. The hours rules (hoursOn, todayState) count Austrian public holidays; pass them calendar: 'DE', 'SG' or 'none' to change that.
+    hours: hours({ source: 'files' }),
+    // content/menu/: one file per dish. allergens: 'none' leaves out the allergen field.
+    menu: menu({ allergens: 'none', source: 'files' }),
+  },
+})

package/presets/gastro-de/app/pages/index.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { formatMoney } from '@lupinum/ginko'
+import { priceOn, timesOf, weekdayNames, type Weekday } from '@lupinum/ginko-preset-gastro'
+
+const hours = useGinko('hours')
+const menu = useGinko('menu')
+const today = useGinkoToday()
+const { language } = useI18n()
+const categories = [['starters', 'Vorspeisen'], ['soups', 'Suppen'], ['mains', 'Hauptspeisen'], ['desserts', 'Nachspeisen'], ['drinks', 'Getränke']] as const
+useGinkoSeo({ title: 'Speisekarte und Öffnungszeiten' })
+</script>
+
+<template>
+  <main>
+    <h1>Öffnungszeiten</h1>
+    <table>
+      <tbody>
+        <tr v-for="d in hours.data.week" :key="d.day">
+          <th scope="row">{{ weekdayNames.de[d.day as Weekday] }}</th>
+          <td>{{ d.closed ? 'Ruhetag' : timesOf(d, 'und') }}</td>
+        </tr>
+      </tbody>
+    </table>
+    <h1>Speisekarte</h1>
+    <section v-for="[key, title] in categories.filter(([k]) => menu.items.some((i) => i.data.category === k))" :key="key">
+      <h2>{{ title }}</h2>
+      <ul>
+        <li v-for="dish in menu.items.filter((i) => i.data.category === key)" :key="dish.id">
+          <strong>{{ dish.data.name }}</strong>, {{ formatMoney(priceOn(dish.data, today), language) }}
+          <br>{{ dish.data.description }}
+        </li>
+      </ul>
+    </section>
+  </main>
+</template>

package/presets/gastro-de/content/hours.md

@@ -0,0 +1,12 @@
+---
+week:
+  - { day: mo, closed: true }
+  - { day: tu, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: we, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: th, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "22:00" }
+  - { day: fr, closed: false, from1: "11:30", to1: "14:00", from2: "17:30", to2: "23:00" }
+  - { day: sa, closed: false, from1: "11:30", to1: "23:00" }
+  - { day: su, closed: false, from1: "11:30", to1: "20:00" }
+exceptions: []
+holidayNoticeDays: 14
+---

package/presets/gastro-de/content/menu/1.tomatensuppe.md

@@ -0,0 +1,7 @@
+---
+category: soups
+name: Tomatensuppe
+description: Geröstete Tomaten, Basilikum und ein Löffel Rahm.
+price: 6.5
+veg: vegetarian
+---

package/presets/gastro-de/content/menu/2.hausburger.md

@@ -0,0 +1,7 @@
+---
+category: mains
+name: Hausburger
+description: Rindfleisch-Patty, Cheddar, Essiggurken und Pommes.
+price: 14.9
+veg: none
+---

package/presets/gastro-de/content/menu/3.gartensalat.md

@@ -0,0 +1,7 @@
+---
+category: starters
+name: Gartensalat
+description: Blattsalate der Saison, Kerne und Zitronendressing.
+price: 8.5
+veg: vegan
+---

package/presets/gastro-de/content/menu/4.apfelkuchen.md

@@ -0,0 +1,7 @@
+---
+category: desserts
+name: Apfelkuchen
+description: Warmer Apfelkuchen mit Vanilleeis.
+price: 5.9
+veg: vegetarian
+---

package/presets/gastro-de/ginko.config.ts

@@ -0,0 +1,25 @@
+// Öffnungszeiten und Speisekarte aus dem Gastro-Preset, beide aus Markdown-Dateien in content/.
+// Die anderen Bausteine des Presets (Hinweise, Mittagsmenü, Veranstaltungen, Galerie) und die Schnellaufgaben
+// für Inhaber brauchen die Ginko-Plattform.
+import { defineSite } from '@lupinum/ginko'
+import { hours, menu } from '@lupinum/ginko-preset-gastro'
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // für dein Land ändern
+  locales: ['de'],
+  currency: 'EUR', // für dein Land ändern
+  pages: { home: '/' },
+  // Steht in Suchergebnissen und Link-Vorschauen. Ersetze es durch einen Satz über deine Website.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Öffnungszeiten und Speisekarte unseres Restaurants.', color: '#1e4032' },
+  bricks: {
+    // content/hours.md: die Öffnungszeiten der Woche. Die Regeln dazu (hoursOn, todayState) zählen die österreichischen
+    // Feiertage; mit calendar: 'DE', 'SG' oder 'none' änderst du das.
+    hours: hours({ source: 'files' }),
+    // content/menu/: eine Datei pro Gericht. allergens: 'none' lässt das Feld für Allergene weg.
+    menu: menu({ allergens: 'none', source: 'files' }),
+  },
+})

package/template/app/app.vue

@@ -0,0 +1,3 @@
+<template>
+  <NuxtPage />
+</template>

package/template/app/pages/index.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+const start = useGinko('start')
+// The page title and description come from `name` and `seo` in ginko.config.ts. Pass `{ title }` to name a page.
+useGinkoSeo({})
+</script>
+
+<template>
+  <main>
+    <h1>{{ start.data.title }}</h1>
+    <GinkoMarkdown :value="start.data.body" />
+  </main>
+</template>

package/template/content/start.md

@@ -0,0 +1,5 @@
+---
+title: Hello Ginko
+---
+
+This text lives in `content/start.md`. Change it, and the page shows the new text.

package/template/ginko.config.ts

@@ -0,0 +1,24 @@
+// What content this site has. Bricks with `source: 'files'` read Markdown from content/.
+// To let an owner edit a brick on the Ginko platform instead, remove `source`; f.markdown then stores the text on the platform.
+// Then give the single's required fields a `default` or make them optional (`f.markdown`, `f.image` and `f.file` cannot have a default, so set `optional: true` on them).
+import { defineSite, f, single } from '@lupinum/ginko'
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // change for your country
+  locales: ['en'],
+  currency: 'EUR', // change for your country
+  pages: { home: '/' },
+  // Shown in search results and link previews. Replace it with one sentence about your site.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'A new website built with Ginko.', color: '#1f2937' },
+  bricks: {
+    start: single({
+      label: 'Start page',
+      source: 'files',
+      fields: { title: f.text('Title'), body: f.markdown('Text', { profile: 'basic' }) },
+    }),
+  },
+})

package/template/gitignore

@@ -0,0 +1,6 @@
+node_modules
+.env
+.nuxt
+.output
+.data
+dist

package/template/nuxt.config.ts

@@ -0,0 +1,8 @@
+import ginko from './ginko.config.ts'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-01',
+  // nuxt-og-image draws a share card for every page (Ginko passes title, image, logo and `seo.color`).
+  modules: ['@lupinum/ginko/nuxt', 'nuxt-og-image'],
+  ginko,
+})

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{SITE}}",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+  },
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "preview": "nuxt preview",
+    "typecheck": "nuxt typecheck",
+    "postinstall": "nuxt prepare"
+  },
+  "dependencies": {
+    "@lupinum/ginko": "^{{VERSION}}",
+    "@lupinum/ginko-content": "^{{VERSION}}",
+    "@lupinum/ginko-i18n": "^{{VERSION}}",
+    "@takumi-rs/core": "^2.15.0",
+    "nuxt": "^4.6.1",
+    "nuxt-og-image": "^7.0.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vue-tsc": "^3.1.5"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+# pnpm 11 stops `pnpm install` with an error until you say which packages may run install scripts.
+# esbuild (used by Nuxt and Vite) downloads its binary this way. npm and bun ignore this file.
+allowBuilds:
+  esbuild: true

package/template/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./.nuxt/tsconfig.app.json" },
+    { "path": "./.nuxt/tsconfig.server.json" },
+    { "path": "./.nuxt/tsconfig.shared.json" },
+    { "path": "./.nuxt/tsconfig.node.json" }
+  ]
+}

package/template-de/content/start.md

@@ -0,0 +1,5 @@
+---
+title: Hallo Ginko
+---
+
+Dieser Text liegt in `content/start.md`. Ändere ihn, und die Seite zeigt den neuen Text.

package/template-de/ginko.config.ts

@@ -0,0 +1,23 @@
+// What content this site has. Bricks with `source: 'files'` read Markdown from content/.
+// To let an owner edit a brick on the Ginko platform instead, remove `source`; f.markdown then stores the text on the platform.
+// Then give the single's required fields a `default` or make them optional (`f.markdown`, `f.image` and `f.file` cannot have a default, so set `optional: true` on them).
+import { defineSite, f, single } from '@lupinum/ginko'
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // für dein Land ändern
+  locales: ['de'],
+  currency: 'EUR', // für dein Land ändern
+  pages: { home: '/' },
+  // Steht in Suchergebnissen und Link-Vorschauen. Ersetze es durch einen Satz über deine Website.
+  seo: { description: 'Eine neue Website mit Ginko.' },
+  bricks: {
+    start: single({
+      label: 'Startseite',
+      source: 'files',
+      fields: { title: f.text('Titel'), body: f.markdown('Text', { profile: 'basic' }) },
+    }),
+  },
+})