create-ginko 0.4.0 → 0.5.0

package/templates/blog/MEDIA.md

@@ -0,0 +1,29 @@
+# Media
+
+Photos and other media in this template, with their source and license. The code is MIT (see LICENSE); media keep
+their own license. People are shown with their initials, never with stock photos of faces.
+
+## Photos
+
+The [Unsplash License](https://unsplash.com/license) allows free use, also commercial, without asking; it does not
+allow selling the photos as they are or building a similar photo service.
+
+| File | Used in | What | Source | License |
+|---|---|---|---|---|
+| `public/media/notebook.jpg` | post "What a ten-minute notebook teaches you" (cover) | an open notebook with blank pages and a pencil on a wooden table | [honza_kahanek on Unsplash](https://unsplash.com/photos/brown-pencil-on-white-book-page-fVUl6kzIvLg) | Unsplash License |
+| `public/media/forest-path.jpg` | post "The forest at the end of the tram line" (cover) | a path through a misty forest, with a bench and a table | [goranvuc on Unsplash](https://unsplash.com/photos/pathway-between-trees-in-forest-EuuIa8XTLK4) | Unsplash License |
+| `content/posts/rock-pools.jpg` | post "Rock pools at low tide" (in the text, with a caption) | rock pools between flat rocks with seaweed, a forested shore behind | [folkandwild on Unsplash](https://unsplash.com/photos/rocky-tide-pools-along-a-forested-coastline-gLTUc-cboEU) | Unsplash License |
+
+## Made for this template
+
+| File | What | License |
+|---|---|---|
+| `.github/screenshots/home-light.png`, `home-dark.png` | screenshots of this template | MIT, like the code |
+
+The share cards (1200 × 630) are generated by the site (nuxt-og-image) with Inter
+([SIL Open Font License](https://openfontlicense.org)).
+
+When you add a photo, put a cover in `public/media/` and a photo for the text next to its post in `content/posts/`,
+give it alt text in every language file that shows it, and add a row here. The sample photos are stock photos of other
+places. Replace them with your own: readers of a nature blog want to see what you saw. A post needs no photo: the
+lists and the post page work without one.

package/templates/blog/NOTES.md

@@ -0,0 +1,16 @@
+# Notes before release
+
+- **Sample content.** The writers Ida Wren and Tom Marsh, their city, the river, the tram line and the coast are
+  invented; the nature facts in the posts (swifts, beech leaves in winter, rock pool life, tawny owl calls, street
+  trees in winter) were written to be true but not checked by a naturalist. `content/site.md` has a sample email
+  (`example.com`), and the legal texts are marked placeholders.
+- **Photos.** The three photos are stock photos (MEDIA.md); four of the seven posts have none on purpose, to show the
+  no-image state.
+- **Scheduled post and draft.** `owls-in-the-old-cemetery` is dated 2027-01-17 and `lichen-on-the-old-bridge` has
+  `draft: true`; both must stay off the site (gate 3, `templates/_features/blog/e2e/blog.spec.ts`). create-ginko does
+  not move post dates (posts have no `visible` rule), so in a copy made after 17 January 2027 the owls post is an
+  ordinary published post. Move its date with the monthly re-anchor if the sample should keep a scheduled post.
+- **German** says "du" on every page (a personal blog), also in the placeholders of `content/legal/`.
+- **Studio (gate 7).** No `templates/_studio/blog` yet. In the Studio a post is scheduled with the publish step
+  (`publishAt`); `local:files-export` imports a future-dated file post as a published entry, so the export should turn
+  it into a scheduled draft before the platform variant is tested.

package/templates/blog/README.md

@@ -0,0 +1,274 @@
+# Blog
+
+A personal blog to start from: "Field Notes", two friends writing about the nature in and around their city. Posts
+with a cover photo or none, topics with their own pages, an author page per writer, older and newer post links, a
+feed per language, drafts and scheduled posts, in English and German, with light and dark mode. Built with
+[Nuxt](https://nuxt.com) and [Ginko](https://github.com/lupinum-dev/ginko). All content is Markdown in `content/`;
+the blog needs no account and no database.
+
+| Light | Dark |
+|---|---|
+| ![The blog's home page in light mode](.github/screenshots/home-light.png) | ![The blog's home page in dark mode](.github/screenshots/home-dark.png) |
+
+## Quick start
+
+```bash
+npm create ginko@latest my-blog -- --template blog
+```
+
+This copies the template into `my-blog`, keeps the languages you choose (`--locales en` for English only,
+`--locales de,en` for German first), sets the site id and writes a `.env` with a new `NUXT_APP_SECRET`. Then:
+
+```bash
+cd my-blog
+npm install
+npm run dev
+```
+
+Or copy the folder as it is, with both languages, through Nuxt's own command:
+
+```bash
+npm create nuxt@latest my-blog -- -t github:lupinum-dev/ginko/templates/blog#release
+```
+
+Copy `.env.example` to `.env` and fill in `NUXT_APP_SECRET` (see below). The `#release` branch follows the latest
+Ginko release, so both commands give you the same files.
+
+## Deploy
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Flupinum-dev%2Fginko%2Ftree%2Frelease%2Ftemplates%2Fblog&env=NUXT_APP_SECRET&envDescription=Signs%20the%20share%20card%20URLs.%20Any%2032%20or%20more%20random%20characters.)
+
+Any host that runs Node works: `npm run build` writes a server to `.output/`, started with
+`node .output/server/index.mjs`. Set these variables where the site runs:
+
+| Variable | What |
+|---|---|
+| `NUXT_APP_SECRET` | Signs the URLs of the share cards. 32 or more random characters (`openssl rand -hex 32`). |
+| `NUXT_PUBLIC_SITE_URL` | The address of the live site, for example `https://www.my-blog.com`. On Vercel the production address is used when this is not set. |
+
+A build on Vercel stops with a message while the address is still `example.com`, so search engines never see wrong
+links. Other builds (CI, your computer) only print a warning.
+
+### Static files
+
+The blog can also be built as static files: `npm run generate` writes every page, the feeds, the sitemap and
+`llms.txt` to `.output/public/`, for any static host. Two things then wait for the next build: a scheduled post (see
+"Write a post") and the end of a notice. Add the daily rebuild below.
+
+### A daily rebuild
+
+A post dated in the future goes online with the first build on or after its date, with a server and with static
+files alike, because the content is part of the build. To publish it on its day without doing anything, rebuild the
+site every morning. On Vercel: create a Deploy Hook (Project → Settings → Git → Deploy Hooks), save its URL as the
+repository secret `DEPLOY_HOOK` on GitHub, and add `.github/workflows/daily-build.yml`:
+
+```yaml
+name: daily-build
+on:
+  schedule:
+    - cron: '5 4 * * *' # every day at 04:05 UTC
+  workflow_dispatch:
+permissions: {}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: curl --fail --silent --show-error --request POST "$DEPLOY_HOOK"
+        env:
+          DEPLOY_HOOK: ${{ secrets.DEPLOY_HOOK }}
+```
+
+Other hosts have the same kind of build hook. GitHub pauses scheduled workflows in a repository without activity for
+60 days; a new post is activity.
+
+## Develop, build, preview
+
+| Command | What |
+|---|---|
+| `npm run dev` | the site with live reload on http://localhost:3000; it also shows drafts and scheduled posts |
+| `npm run check` | Checks the content files in a few seconds: missing or wrong fields, dates, links between pages and files in `public/`. Each problem names the file and the field. |
+| `npm run build` | the production build in `.output/` |
+| `npm run preview` | runs that build locally |
+| `npm run generate` | static files instead of a server |
+| `npm run lint` | ESLint |
+| `npm run typecheck` | TypeScript and Vue types |
+
+`.github/workflows/ci.yml` runs lint, typecheck and build on every push. It needs no settings.
+
+## Write a post
+
+A post is one Markdown file in `content/posts/`; its name is its address (`swifts-over-the-car-park.md` is
+`/posts/swifts-over-the-car-park`).
+
+```markdown
+---
+title: "Swifts over the car park"
+description: "One or two sentences: the summary in lists, feeds and search results."
+date: 2026-06-21
+authors: [people/ida-wren]
+tags: ["Birds"]
+image:
+  src: /media/swifts.jpg
+  alt: "What the photo shows, for people who cannot see it"
+---
+
+The text, in Markdown. Headings start at `##`.
+```
+
+- **Draft:** add `draft: true`. The post is on no page, in no list, feed, sitemap or search, until you remove the
+  line. `npm run dev` shows it, so you can read it first.
+- **Schedule:** give it a `date` in the future. It stays off the site like a draft until the first build on or after
+  that day (see "A daily rebuild"). `npm run dev` shows it.
+- **Publish:** remove the `draft` line and set `date` to the day it goes online (the post shows this date, and lists
+  sort by it). Commit and push; the next build puts it online.
+- **Translation:** `swifts-over-the-car-park.de.md` with `title`, `slug` (its German address), `description`, `tags`
+  and `image.alt` in German, and the text. Date, authors and the photo come from the main file. A post without a
+  translation is not shown in that language. The translation lists the `tags` in the same order as the main file: when
+  you add, remove or move a tag in the main file, do the same at the same place in the translation. `npm run check`
+  reports a translation with a different number of tags.
+- **Cover photo:** optional. Without one, lists and the post show text only. Put the file in `public/media/`; cover
+  photos are shown at 3:2.
+- **Photo with a caption in the text:** put the photo next to the post (`content/posts/rock-pools.jpg`); the build
+  makes smaller copies of it for phones. Then the image, and on the next line an emphasised caption:
+
+  ```markdown
+  ![Rock pools between flat rocks covered in seaweed](./rock-pools.jpg)
+  *The pools below the old lookout, two hours after high water.*
+  ```
+
+- **Topics:** `tags` are free text, at most ten per post. Each tag gets a page under the posts
+  (`/posts/topics/birds`) with every post that carries it; the home page and the list of posts link all of them.
+  Write a tag the same way in every post. Tags are per language, so the German tag pages are the German tags'; the
+  language switch on a tag page leads to the other language's list of posts.
+- **Code and quotes:** fenced code blocks (with a language, such as ```` ```text ````) and `>` quotes are styled.
+
+The reading time is counted from the text (200 words a minute). The older and the newer post are linked below each
+post.
+
+## Edit content
+
+Every text is a Markdown file. The main language has no suffix (`home.md`); a translation adds the language code
+(`home.de.md`) and repeats only what it translates. After each change, run `npm run check`.
+
+Files point to other entries by id: the folder and the file name without number and language, so
+`content/people/1.ida-wren.md` is `people/ida-wren`. The `slug` is only the address on the site: renaming a file
+breaks the references to it, changing the `slug` does not. Write dates as `2026-10-24`.
+
+| On the site | File |
+|---|---|
+| Home page: title and lead | `content/home.md`, `content/home.de.md` |
+| Posts | `content/posts/<name>.md` (see "Write a post") |
+| Authors (the About page and one page each) | `content/people/<n>.<name>.md`: `name`, `role`, `bio`; no photo needed, the site shows initials. A post names them in `authors` (`people/ida-wren`) |
+| Notices above the header | `content/notices/<n>.<name>.md`: `text` (at most 140 characters; in quotes when it contains a colon) and `until` (the last day it shows, like `2026-12-31`; without it the notice stays until you delete the file); a translation has only `text` |
+| Email (footer, imprint) | `content/site.md`; add `legalName`, `street`, `postalCode` and `city` if your imprint needs them |
+| Privacy policy, terms of use, imprint | `content/legal/` (placeholders: replace them before you go live) |
+| Site name, description for search engines | `ginko.config.ts` (`name`, `seo.description`) |
+| Menu, the line under the name in the footer, profiles elsewhere, newsletter | `app/app.config.ts` |
+| Section titles, the About page's title and lead, the posts page's title and lead | `i18n/<language>.json`; the features' own texts are in `i18n/<feature>/<language>.json`, and a key set in `i18n/<language>.json` wins |
+
+Notices show in file-number order, smallest first: give a new notice a smaller number than the others (`0.` works,
+and numbers may have gaps, so older notices keep theirs). At most two show at once.
+
+## Follow: feed and newsletter
+
+Each language has a feed at `<posts page>/rss.xml` (`/posts/rss.xml`, `/de/beitraege/rss.xml`) with the title,
+summary, date and authors of every post that is online. It is linked in the footer of every page and below the list
+of posts.
+
+The blog has no form (it sends no data to other companies). For a newsletter, use a newsletter service and set its
+sign-up page as `blog.newsletter` in `app/app.config.ts`; the footer then links it. Name the service in your privacy
+policy.
+
+## Make it yours
+
+- **Name and menu.** `name` in `ginko.config.ts` (header, footer, share cards, search engines, and the label screen
+  readers announce for the feed links). The sample name also appears as text in the About page's lead (`people.lead`
+  in `i18n/<language>.json`), so rewrite it; search `content/` and `i18n/` for it and replace what is left. `nav` in
+  `app/app.config.ts`, at most six links.
+- **Logo.** Put the file in `public/` and set `logo: { src: '/logo.svg', width: 120, height: 32 }` in
+  `app/app.config.ts`. Without it, the header shows the name.
+- **Colour.** `--brand` and `--brand-foreground` in `app/assets/css/main.css`, once for light and once for dark
+  (`.dark`), and the light value as `seo.color` in `ginko.config.ts` (the background of the share cards). Text on the
+  colour needs a contrast of at least 4.5:1 in both modes; check each pair with a contrast checker (for example
+  webaim.org/resources/contrastchecker). `DESIGN.md` has the rules and the colours of the other templates.
+- **Fonts.** `--font-body` (and optionally `--font-heading`) in `main.css`. `@nuxt/fonts` downloads the font at build
+  time and serves it from your site.
+- **Addresses.** The words of the addresses per language are `segments` in `app/routes.ts`: `posts` (`/posts`,
+  `/de/beitraege`), `tags` (the word of a topic page: `topics`, `themen`) and `about` (`/about`, `/de/ueber-uns`,
+  also the authors' pages). Change a word there; pages and links follow.
+
+`DESIGN.md` explains the tokens and components. The parts in `app/components/ui/` are
+[shadcn-vue](https://www.shadcn-vue.com) components.
+
+## Add a page
+
+Add a Vue file in `app/pages/`, for example `app/pages/now.vue` for a "What we are doing now" page. Start it with
+`<BlockPageHeader>` and call `usePageSeo()`, like `app/pages/about/[slug].vue`. Register it in `ginko.config.ts`
+under `pages` (`now: localized('/now')`), so `useGinkoPath()('now')` links to it and the sitemap lists it, and add
+its German word to `segments` in `app/routes.ts` (`now: { en: 'now', de: 'jetzt' }`). Put it in the menu with
+`{ page: 'now', label: { en: 'Now', de: 'Jetzt' } }` in `nav`.
+
+For pages written in Markdown, take the `pages` brick from Ginko's starter template (`app/bricks/pages.ts` and
+`app/pages/[...slug].vue`, with `pages: pages({ route: localized('/[slug]'), source: 'files' })` in `bricks`); then
+`content/pages/<n>.<name>.md` becomes a page.
+
+## Add or remove a language
+
+The languages are the `locales` list in `app/routes.ts`; the first is the main language, whose addresses have no
+prefix.
+
+- **Remove one:** delete it from `locales` and its words from `segments`, then delete its files (`*.de.md`,
+  `i18n/de.json`, `i18n/*/de.json`), its line in `languages` in `ginko.config.ts`, and its `tagline` and `nav`
+  labels in `app/app.config.ts`. Or start fresh with `npm create ginko@latest my-blog -- --template blog --locales en`.
+- **Add one** (for example French): add `'fr'` to `locales` and to `languages`, give each word in `segments` its
+  French form, add the `.fr.md` translations (a post without one is not shown in French), `i18n/fr.json`, and the
+  features' texts in French (`i18n/site/fr.json`, `i18n/blog/fr.json`, `i18n/people/fr.json`: Ginko's other
+  templates have them).
+
+## Remove a feature
+
+| Feature | Delete |
+|---|---|
+| Topic pages | `app/pages/news/tags/`, and the tag links in `app/pages/news/[slug].vue` (the tag chips and `useTagPath()`), `app/pages/news/index.vue` (the tag nav and `useBlogTags()`) and `app/pages/index.vue` (the "Topics" section and `useBlogTags()`); keep `tags` in the posts as keywords for search engines |
+| Authors (a blog without names) | the `authors` line in every post and the files in `content/people/`; posts, lists, the feed and the home page then show no names. To remove the pages too, also follow the Author pages and About page rows |
+| Author pages | `route` of the `people` brick in `ginko.config.ts` and `app/pages/about/[slug].vue`; names are then plain text |
+| The About page | `pages.team`, its `nav` item, `app/pages/team.vue`, `app/components/people/`, `i18n/people/`, `"people"` in `package.json` → `ginko.features`; keep the `people` brick while posts name authors |
+| Feed | `server/middleware/news-feed.ts`, the feed link in `app/pages/news/index.vue` (the visible link, the `rel="alternate"` link in `useHead()`, `useFeedPath()` and the `Rss` import) and in `app/components/site/FooterStatus.vue` (the feed item, `useFeedPath()` and `Rss` in its import), the sentence about the feed in `content/posts/why-we-keep-field-notes*.md` ("Follow along") and the feed bullet in `content/legal/1.privacy*.md` |
+| Notices | `content/notices/`, the `notices` brick (with its comment) and its import in `ginko.config.ts`, `<SiteNotice />` in `app/layouts/default.vue`, `app/components/site/Notice.vue` |
+| A legal text | its files in `content/legal/` |
+| German | see "Add or remove a language" |
+| Dark mode | `<SiteThemeToggle />` in `app/components/site/Header.vue`, `app/components/site/ThemeToggle.vue`, and `@nuxtjs/color-mode` with its `colorMode` options in `nuxt.config.ts` and `package.json` |
+| Share cards | `nuxt-og-image` and `@takumi-rs/core` in `nuxt.config.ts` and `package.json`; then `NUXT_APP_SECRET` is not needed |
+
+## Before you deploy
+
+- [ ] `NUXT_PUBLIC_SITE_URL` (or `url` in `ginko.config.ts`) is your real address.
+- [ ] `NUXT_APP_SECRET` is set where the site runs.
+- [ ] The sample posts and authors are replaced by your own, and the draft `lichen-on-the-old-bridge` is deleted.
+- [ ] The placeholders in `content/legal/` are replaced by your own texts, and the ones you do not need are deleted.
+- [ ] `content/site.md` has your real email (and your name and address, if your country requires an imprint).
+- [ ] The sample phone numbers and emails are replaced: they reach nobody (the numbers start their local part with 0, the emails end in .example), so a forgotten one fails quietly.
+- [ ] Every photo you added has alt text in each language and a source in `MEDIA.md`.
+- [ ] If you schedule posts: the daily rebuild runs.
+
+## Move to the Studio
+
+Ginko Studio is Lupinum's hosted editor: authors write, save drafts and set a time for a post to go live on their
+phone, without Git; Today lists the drafts and the scheduled posts. It is open by invitation, and Lupinum moves your
+content with you. The site stays the same code: each brick in `ginko.config.ts` loses its `source: 'files'`, and its
+content then comes from the Studio. Until then, everything here works without it. Ask at
+[lupinum.com](https://lupinum.com).
+
+## Updating
+
+Move all Ginko packages to the same version in one step:
+
+```bash
+npm install @lupinum/ginko@latest @lupinum/ginko-content@latest @lupinum/ginko-i18n@latest
+```
+
+The release notes list "Template files changed": compare those files with yours if you want the changes.
+
+## License
+
+Code: MIT (see `LICENSE`). Media: see `MEDIA.md`.

package/templates/blog/app/app.config.ts

@@ -0,0 +1,29 @@
+import type { SiteAppConfig } from './composables/useSiteAppConfig'
+
+// The brand and navigation of the site. The name is `name` in ginko.config.ts; colours and fonts are in
+// app/assets/css/main.css; the contact email is in content/site.md.
+export default defineAppConfig({
+  site: {
+    // logo: { src: '/logo.svg', width: 120, height: 32 },
+    // One line under the name in the footer, per language.
+    tagline: {
+      en: 'Notes on the nature in and around the city.',
+      de: 'Notizen über die Natur in und um die Stadt.',
+    },
+    organization: 'Organization',
+    // At most 6. A page of ginko.config.ts (`page`, with its label per language; keep it the same as the page's title).
+    nav: [
+      { page: 'news', label: { en: 'Posts', de: 'Beiträge' } },
+      { page: 'team', label: { en: 'About', de: 'Über uns' } },
+    ],
+    footer: [],
+    // For example { label: 'Mastodon', url: 'https://mastodon.social/@fieldnotes' }.
+    socials: [],
+  } satisfies SiteAppConfig,
+  // Following the blog, shown in the footer of every page (app/components/site/FooterStatus.vue) next to the feed.
+  blog: {
+    // The sign-up page of your newsletter at a newsletter service, for example 'https://fieldnotes.example.com/subscribe'.
+    // Empty: no newsletter link. The site itself has no form and sends no data to the service.
+    newsletter: '',
+  },
+})

package/templates/blog/app/app.vue

@@ -0,0 +1,7 @@
+<!-- Synced from templates/_features/site/app/app.vue by `pnpm templates sync`. Edit the source, not this copy. -->
+<template>
+  <NuxtRouteAnnouncer />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/templates/blog/app/assets/css/main.css

@@ -0,0 +1,18 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "./tokens.css";
+
+/* This template's accent and fonts (DESIGN.md "Your accent"). Everything else comes from tokens.css.
+   blog: indigo. White on the accent 6.3:1 light; the accent on the page 6.3:1 light; #1e1b4b on the dark accent
+   8.0:1; the dark accent on the page 9.9:1. The focus ring and links in text use the accent. */
+:root {
+  --brand: #4f46e5;
+  --brand-foreground: #ffffff;
+  /* @nuxt/fonts serves Inter from the site and adds size-matched fallbacks. */
+  --font-body: "Inter", ui-sans-serif, system-ui, sans-serif;
+}
+
+.dark {
+  --brand: #a5b4fc;
+  --brand-foreground: #1e1b4b;
+}