@anja.codes/create-vitakit 0.1.0 → 0.2.0

package/README.md

@@ -8,16 +8,41 @@ pnpm create @anja.codes/vitakit my-site
 cd my-site
 pnpm install
 pnpm dev            # http://localhost:3000
-pnpm build:cv       # cv-tex/cv.pdf (needs a TeX distribution)
+pnpm pdf            # cv-tex/cv.pdf (needs a TeX distribution)
 pnpm check          # what CI runs
 ```
 
+`npm create @anja.codes/vitakit my-site` works too: the project is then written
+for npm, with `npm run …` in its scripts, workflows and instructions.
+
 It asks for your name, position, affiliation, email and a deployment target
-(GitHub Pages, Cloudflare Pages, rsync, or none), copies the template and
+(GitHub Pages, Cloudflare Workers or Pages, GitLab Pages, Codeberg Pages,
+existing web space via SSH/rsync, or decide later), copies the template and
 substitutes those few values.
 
-This is the only scaffolding step vitakit has. Everything afterwards — a new
-page, a new CV variant, a new section — is adding or copying a file in a
-repository you own.
+Choose `?` at the deployment prompt for a compact comparison of URLs,
+requirements and CI. Numbered setup steps follow your selection.
+To read the comparison without creating files:
+
+```bash
+pnpm create @anja.codes/vitakit --deployment-help
+```
+
+- **GitHub Pages:** public source on Free; a paid plan for private source.
+- **Cloudflare Workers:** recommended for new Cloudflare projects; uses GitHub Actions.
+- **Cloudflare Pages:** legacy option, still available; also uses GitHub Actions.
+- **GitLab Pages:** private source supported on Free; uses GitLab CI/CD.
+- **Codeberg Pages:** uses git-pages and Forgejo Actions. Hosted CI requires public,
+  freely licensed source; use your own runner for sensitive CV source.
+- **SSH/rsync:** needs existing web space; the preset uses Forgejo Actions.
+
+Choosing to decide later adds no workflows and leaves all hosting options open.
+
+See [publishing and setup](../docs/guide/publishing.md) for details.
+
+Everything afterwards is ordinary files in a repository you own. The
+`vitakit` command in the project helps with the common changes — `pnpm vitakit
+status` shows what is there, `pnpm vitakit add section <name>` sets up a new
+section — and shows every change before it makes it.
 
 MIT

package/deployments.mjs

@@ -0,0 +1,178 @@
+/** Hosting choices, comparison facts and actionable setup steps. */
+export const DEPLOYMENTS = {
+  'github-pages': {
+    label: 'GitHub Pages',
+    description: 'Static hosting built into GitHub.',
+    details: {
+      URL: 'https://<user>.github.io/<repo>/ or a custom domain.',
+      Source: 'Public on Free; private needs GitHub Pro (personal) or Team/Enterprise (org).',
+      CI: 'GitHub Actions.',
+    },
+    setup: [
+      'In GitHub Settings → Pages, select GitHub Actions as the source.',
+      'Check .github/workflows/deploy.yml:\n- Project site: keep NUXT_APP_BASE_URL=/<repo>/.\n- User site (<user>.github.io) or root custom domain: remove that setting.',
+      'Commit pnpm-lock.yaml and push to main.',
+    ],
+    notes: ['Private source needs GitHub Pro (personal) or Team/Enterprise (org).'],
+    files: ['.github/workflows/deploy.yml', '.github/workflows/cv.yml'],
+  },
+  'cloudflare-workers': {
+    label: 'Cloudflare Workers (recommended)',
+    description: 'Cloudflare’s current platform, serving static files without server code.',
+    details: {
+      URL: 'https://<worker>.<account>.workers.dev/ or a custom domain.',
+      Source: 'Private repos supported on Free; hosting/CI limits apply.',
+      CI: 'GitHub Actions.',
+    },
+    setup: [
+      'Enable a workers.dev subdomain in your Cloudflare account.',
+      'Set the Worker name in wrangler.json.',
+      'Add GitHub Actions repository secrets:\n- CLOUDFLARE_ACCOUNT_ID\n- CLOUDFLARE_API_TOKEN (Workers Scripts: Edit permission)',
+      'Commit pnpm-lock.yaml and push to main.',
+    ],
+    files: ['.github/workflows/workers.yml', '.github/workflows/cv.yml', 'wrangler.json'],
+  },
+  'cloudflare': {
+    label: 'Cloudflare Pages (legacy)',
+    description: 'Legacy Cloudflare option. Still available; use Workers for new projects.',
+    details: {
+      URL: 'https://<project>.pages.dev/ or a custom domain.',
+      Source: 'Private repos supported on Free; hosting/CI limits apply.',
+      CI: 'GitHub Actions, uploading a prebuilt site (Direct Upload).',
+    },
+    setup: [
+      'Create a Cloudflare Pages Direct Upload project; production branch: main.',
+      'Set --project-name in .github/workflows/cloudflare.yml to match.',
+      'Add GitHub Actions repository secrets:\n- CLOUDFLARE_ACCOUNT_ID\n- CLOUDFLARE_API_TOKEN (Cloudflare Pages: Edit permission)',
+      'Commit pnpm-lock.yaml and push to main.',
+    ],
+    files: ['.github/workflows/cloudflare.yml', '.github/workflows/cv.yml'],
+  },
+  'gitlab-pages': {
+    label: 'GitLab Pages',
+    description: 'Static hosting on GitLab.com or a university’s GitLab instance.',
+    details: {
+      URL: 'https://<project>-<id>.gitlab.io/; project paths/custom domains also work.',
+      Source: 'Private repos supported on Free; CI quotas apply.',
+      CI: 'GitLab CI/CD. Self-managed instances need GitLab 17.10+.',
+    },
+    setup: [
+      'Enable CI runners and Pages in your GitLab project.',
+      'For a public site, set Pages access to Everyone in project settings.',
+      'Check .gitlab-ci.yml: the base path comes from CI_PAGES_URL.\nFor a root custom domain, set CI/CD variable NUXT_APP_BASE_URL=/.',
+      'Commit pnpm-lock.yaml and push to the default branch.',
+    ],
+    files: ['.gitlab-ci.yml'],
+  },
+  'codeberg-pages': {
+    label: 'Codeberg Pages (git-pages)',
+    description: 'Static hosting on Codeberg, powered by git-pages.',
+    details: {
+      URL: 'https://<owner>.codeberg.page/<repo>/ or a custom domain.',
+      Source: 'Hosted CI needs public, freely licensed source; private needs your own runner.',
+      CI: 'Forgejo Actions, using the automatic token; no publishing branch needed.',
+    },
+    setup: [
+      'Enable Actions in your Codeberg repository.',
+      'Choose a Docker-capable runner in .forgejo/workflows/codeberg.yml.\nUse your own runner for private source.',
+      'Check site and NUXT_APP_BASE_URL in that workflow.\nFor root/custom domains, update both; custom domains also need DNS authorization.',
+      'Commit pnpm-lock.yaml and push to main.',
+    ],
+    notes: ['Codeberg-hosted runners require a public, freely licensed repository.'],
+    files: ['.forgejo/workflows/codeberg.yml'],
+  },
+  'rsync': {
+    label: 'Existing web space (SSH/rsync)',
+    description: 'Upload to university web space or a server you already control.',
+    details: {
+      URL: 'Your server’s URL, e.g. https://www.example.edu/~username/.',
+      Needs: 'SSH/rsync access and a writable web directory; not SFTP-only hosting.',
+      CI: 'Forgejo Actions, not GitHub Actions.',
+    },
+    setup: [
+      'Open .forgejo/workflows/deploy.yml.',
+      'Set the SSH user, host, destination path and NUXT_APP_BASE_URL.',
+      'Add SSH_DEPLOY_KEY as a Forgejo Actions repository secret.',
+      'Configure SSH host-key verification; the template currently disables it.',
+      'Commit pnpm-lock.yaml and push to main.',
+    ],
+    notes: ['Check the destination: rsync --delete removes files absent from the build.'],
+    files: ['.forgejo/workflows/deploy.yml'],
+  },
+  'none': {
+    label: 'Decide later / deploy manually',
+    description: 'Choose a host later; nothing is published.',
+    details: {
+      Local: 'Website and LaTeX CV work as usual.',
+      CI: 'No deployment or PDF-build workflows added.',
+    },
+    setup: [
+      'When ready to publish, run pnpm check.',
+      'Upload only .output/public to a static host, not the source or cv-tex/.',
+    ],
+    files: [],
+  },
+}
+
+/** Wrap CLI prose with hanging indents, preserving explicit sublists. */
+function wrap(text, prefix = '', width = 80) {
+  const continuation = ' '.repeat(prefix.length)
+  return text.split('\n').flatMap((paragraph, index) => {
+    const lines = []
+    let line = index === 0 ? prefix : continuation
+    for (const word of paragraph.split(/\s+/)) {
+      if (line.trim() && line.length + 1 + word.length > width) {
+        lines.push(line)
+        line = continuation
+      }
+      line += (line.trim() && line !== prefix ? ' ' : '') + word
+    }
+    lines.push(line)
+    return lines
+  }).join('\n')
+}
+
+export function deploymentHelp() {
+  const sections = Object.values(DEPLOYMENTS).map(({ label, description, details }, index) => [
+    `${index + 1}. ${label}`,
+    wrap(description, '   '),
+    ...Object.entries(details).map(([name, value]) => wrap(value, `   ${name}: `)),
+  ].join('\n'))
+  return [
+    'Choosing a deployment target',
+    'Keep sensitive CV source private. Publish only .output/public.',
+    ...sections,
+    'Setup steps are shown after selection.',
+  ].join('\n\n')
+}
+
+export function deploymentInstructions(key, packageManager = 'pnpm') {
+  const { label, setup, notes = [] } = DEPLOYMENTS[key]
+  const commandText = text => packageManager === 'npm'
+    ? text.replace(/pnpm-lock\.yaml/g, 'package-lock.json').replace(/pnpm check/g, 'npm run check')
+    : text
+  return [
+    `Deployment: ${label}`,
+    ...notes.map(note => wrap(note, '  ')),
+    ...setup.map((step, index) => wrap(commandText(step), `  ${index + 1}. `)),
+  ].join('\n')
+}
+
+/** Keep help and invalid input in the selection loop, without losing answers. */
+export async function chooseDeployment(ask, log = console.log) {
+  const keys = Object.keys(DEPLOYMENTS)
+  log('\nDeployment target (you can change this later):')
+  keys.forEach((key, index) => log(`  ${index + 1}. ${DEPLOYMENTS[key].label}`))
+  log('  ?. Help choosing — URLs, requirements and setup')
+
+  while (true) {
+    const choice = (await ask('Choose a number, or ? for help:', '1')).trim()
+    if (/^(\?|h|help)$/i.test(choice)) {
+      log(`\n${deploymentHelp()}\n`)
+      continue
+    }
+    const key = /^[1-9]\d*$/.test(choice) ? keys[Number(choice) - 1] : undefined
+    if (key) return key
+    log(`Please choose a number from 1 to ${keys.length}, or ? for help.`)
+  }
+}

package/index.mjs

@@ -1,83 +1,40 @@
 #!/usr/bin/env node
 /**
  * pnpm create @anja.codes/vitakit [directory]
+ * npm create @anja.codes/vitakit [directory]
  *
- * Copies the template, substitutes the few things that are personal, and picks
- * a deployment workflow. Deliberately the *only* scaffolding step vitakit has:
+ * Copies the template, substitutes the few things that are personal, picks a
+ * deployment workflow, and writes the project for the package manager that ran
+ * it. Deliberately the *only* scaffolding step vitakit has:
  * everything afterwards is editing files in a repository you own.
  */
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { readdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { basename, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 import process from 'node:process'
-
-const TEMPLATE = fileURLToPath(new URL('template', import.meta.url))
-
-const DEPLOYMENTS = {
-  'github-pages': { label: 'GitHub Pages (public repository)', keep: ['deploy.yml', 'cv.yml'], host: '_github' },
-  'cloudflare': { label: 'Cloudflare Pages (works with a private repository)', keep: ['cloudflare.yml', 'cv.yml'], host: '_github' },
-  'rsync': { label: 'Web space via rsync (Forgejo)', keep: ['deploy.yml'], host: '_forgejo' },
-  'none': { label: 'None for now', keep: [], host: undefined },
-}
+import { detectPackageManager, scaffold } from './scaffold.mjs'
+import { chooseDeployment, deploymentHelp, deploymentInstructions } from './deployments.mjs'
 
 function slugify(value) {
   return value.normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
     .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'my-site'
 }
 
-/** Replace the placeholders the template uses. */
-function fill(text, answers) {
-  return text
-    .replaceAll('__NAME__', answers.name)
-    .replaceAll('__TITLE__', answers.title)
-    .replaceAll('__AFFILIATION__', answers.affiliation)
-    .replaceAll('__EMAIL__', answers.email)
-    .replaceAll('__SLUG__', answers.slug)
-}
-
-const TEXT_FILE = /\.(md|ya?ml|json|ts|vue|css|bib|tex|svg|txt|yml|template)$/
-
-async function scaffold(target, answers) {
-  await mkdir(target, { recursive: true })
-  await cp(TEMPLATE, target, { recursive: true })
-
-  // Files that cannot be shipped under their final name: `.gitignore` is
-  // excluded by npm, and `package.json` would make the template a workspace.
-  for (const [from, to] of [['.gitignore.template', '.gitignore'], ['package.json.template', 'package.json']]) {
-    await rename(join(target, from), join(target, to))
-  }
-
-  const deployment = DEPLOYMENTS[answers.deployment]
-  for (const [dir, name] of [['_github', '.github'], ['_forgejo', '.forgejo']]) {
-    const path = join(target, dir)
-    if (deployment.host !== dir) {
-      await rm(path, { recursive: true, force: true })
-      continue
-    }
-    const workflows = join(path, 'workflows')
-    for (const file of await readdir(workflows)) {
-      if (!deployment.keep.includes(file)) await rm(join(workflows, file))
-    }
-    await rename(path, join(target, name))
+async function main() {
+  const args = process.argv.slice(2)
+  const packageManager = detectPackageManager(process.env.npm_config_user_agent)
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: ${packageManager} create @anja.codes/vitakit [directory]\n\n  --help, -h          Show this help without creating a project\n  --deployment-help  Explain deployment targets without creating a project\n`)
+    console.log(deploymentHelp())
+    return
   }
-
-  // Substitute placeholders in every text file.
-  const walk = async (dir) => {
-    for (const item of await readdir(dir, { withFileTypes: true })) {
-      const path = join(dir, item.name)
-      if (item.isDirectory()) await walk(path)
-      else if (TEXT_FILE.test(item.name) || item.name === 'package.json' || item.name === '.gitignore') {
-        await writeFile(path, fill(await readFile(path, 'utf8'), answers))
-      }
-    }
+  if (args.includes('--deployment-help')) {
+    console.log(deploymentHelp())
+    return
   }
-  await walk(target)
-}
 
-async function main() {
-  const [directoryArgument] = process.argv.slice(2).filter(argument => !argument.startsWith('-'))
+  const [directoryArgument] = args.filter(argument => !argument.startsWith('-'))
   const interactive = process.stdin.isTTY && !process.env.VITAKIT_CREATE_DEFAULTS
 
   const answers = {
@@ -86,6 +43,7 @@ async function main() {
     affiliation: 'Department of Mathematics, University of Graz',
     email: 'you@example.org',
     deployment: 'github-pages',
+    packageManager,
   }
 
   let directory = directoryArgument
@@ -104,13 +62,11 @@ async function main() {
     answers.email = await ask('Email:', answers.email)
     directory ??= await ask('Directory:', slugify(answers.name))
 
-    console.log('\nDeployment:')
-    const keys = Object.keys(DEPLOYMENTS)
-    keys.forEach((key, index) => console.log(`  ${index + 1}. ${DEPLOYMENTS[key].label}`))
-    const choice = await ask('Choose:', '1')
-    answers.deployment = keys[Number(choice) - 1] ?? 'github-pages'
-
-    rl.close()
+    try {
+      answers.deployment = await chooseDeployment(ask)
+    } finally {
+      rl.close()
+    }
   }
 
   directory ??= slugify(answers.name)
@@ -124,13 +80,17 @@ async function main() {
   await scaffold(target, answers)
 
   console.log(`\nCreated ${directory}\n`)
-  console.log('  cd ' + directory)
-  console.log('  pnpm install')
-  console.log('  pnpm dev            # http://localhost:3000')
-  console.log('  pnpm build:cv       # cv-tex/cv.pdf (needs LaTeX)')
-  console.log('  pnpm check          # what CI runs\n')
-  console.log('Then edit content/: profile.yml, the section files and publications.bib.')
-  console.log('The PDF is not part of the website build; assume this repository is private.\n')
+  const pm = answers.packageManager
+  const run = pm === 'npm' ? 'npm run' : 'pnpm'
+  const step = (command, comment) => console.log(`  ${command.padEnd(20)}${comment ? `# ${comment}` : ''}`.trimEnd())
+  step('cd ' + directory)
+  step(`${pm} install`)
+  step(`${run} dev`, 'http://localhost:3000')
+  step(`${run} pdf`, 'cv-tex/cv.pdf (needs LaTeX)')
+  step(`${run} check`, 'what CI runs')
+  console.log()
+  console.log('Edit content/ to make it yours. Keep sensitive CV source private.\n')
+  console.log(`${deploymentInstructions(answers.deployment, pm)}\n`)
 }
 
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anja.codes/create-vitakit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a vitakit project: an academic website and a LaTeX CV from one set of files.",
   "license": "MIT",
   "keywords": [
@@ -12,7 +12,7 @@
     "nuxt",
     "latex"
   ],
-  "homepage": "https://github.com/anja-codes/vitakit/tree/main/create#readme",
+  "homepage": "https://vitakit.anja.codes/guide/tutorial/",
   "bugs": {
     "url": "https://github.com/anja-codes/vitakit/issues"
   },
@@ -27,6 +27,8 @@
   },
   "files": [
     "index.mjs",
+    "scaffold.mjs",
+    "deployments.mjs",
     "template",
     "README.md",
     "LICENSE"

package/scaffold.mjs

@@ -0,0 +1,124 @@
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DEPLOYMENTS } from './deployments.mjs'
+
+export { DEPLOYMENTS } from './deployments.mjs'
+
+const TEMPLATE = fileURLToPath(new URL('template', import.meta.url))
+
+/** Package managers a project can be written for; the first is the default. */
+export const PACKAGE_MANAGERS = ['pnpm', 'npm']
+
+/**
+ * The package manager that started `create`, from the user agent every package
+ * manager sets for the processes it runs (`npm/11.6.0 node/v22.18.0 …`).
+ * Anything but npm (pnpm, another one, or running this file directly) gets
+ * the default.
+ */
+export function detectPackageManager(userAgent = '') {
+  return userAgent.startsWith('npm/') ? 'npm' : 'pnpm'
+}
+
+/**
+ * The template is written for pnpm. For npm, its commands are translated in
+ * every text file (scripts, workflows, comments, the pages' own instructions),
+ * so a project never mentions a package manager its owner does not use.
+ */
+function forNpm(text, scripts) {
+  return text
+    // The pnpm setup step, together with the comment lines directly above it.
+    .replace(/^(?:[ \t]*#.*\n)*[ \t]*- uses: \S*pnpm\/action-setup@\S+\n/gm, '')
+    .replace(/cache: pnpm\b/g, 'cache: npm')
+    .replace(/^[ \t]*- corepack (?:enable|install)\n/gm, '')
+    .replace(/pnpm install --frozen-lockfile/g, 'npm ci')
+    .replace(/pnpm vitakit\b/g, 'npx vitakit')
+    // `pnpm pdf --tex-only` -> `npm run pdf -- --tex-only`
+    .replace(/pnpm ([\w:-]+)((?: --?[\w-]+)*)/g, (command, script, args) =>
+      scripts.includes(script) ? `npm run ${script}${args ? ` --${args}` : ''}` : command)
+}
+
+/** YAML placeholders represent whole scalars; prose/TeX placeholders stay raw. */
+function fill(text, answers) {
+  const values = {
+    NAME: answers.name,
+    TITLE: answers.title,
+    AFFILIATION: answers.affiliation,
+    EMAIL: answers.email,
+    SLUG: answers.slug,
+    SUMMARY: `${answers.title} at ${answers.affiliation}, working on your research area.`,
+  }
+  // One callback pass preserves literal $ replacements and placeholder-like
+  // text in answers. JSON strings are valid quoted YAML scalars, including
+  // embedded quotes, backslashes and newlines.
+  return text.replace(/__(YAML_)?(NAME|TITLE|AFFILIATION|EMAIL|SLUG|SUMMARY)__/g,
+    (_, yaml, key) => yaml ? JSON.stringify(values[key]) : values[key])
+}
+
+const TEXT_FILE = /\.(md|ya?ml|json|ts|vue|css|bib|tex|svg|txt|yml|template)$/
+const TEXT_NAMES = new Set(['package.json', '.gitignore', 'latexmkrc'])
+
+/** Internal creator implementation, separate from the interactive CLI. */
+export async function scaffold(target, answers) {
+  const deployment = DEPLOYMENTS[answers.deployment]
+  if (!deployment || !Object.hasOwn(DEPLOYMENTS, answers.deployment)) {
+    throw new Error(`Unknown deployment target: ${answers.deployment}`)
+  }
+
+  await mkdir(target, { recursive: true })
+  await cp(TEMPLATE, target, {
+    recursive: true,
+    // Finder metadata can exist in a checkout but must not reach a project.
+    filter: source => basename(source) !== '.DS_Store',
+  })
+
+  // Files that cannot be shipped under their final name: `.gitignore` is
+  // excluded by npm, and `package.json` would make the template a workspace.
+  for (const [from, to] of [['.gitignore.template', '.gitignore'], ['package.json.template', 'package.json']]) {
+    await rename(join(target, from), join(target, to))
+  }
+
+  for (const [dir, name] of [['_github', '.github'], ['_forgejo', '.forgejo']]) {
+    const path = join(target, dir)
+    const keep = deployment.files.filter(file => file.startsWith(`${name}/workflows/`))
+    if (!keep.length) {
+      await rm(path, { recursive: true, force: true })
+      continue
+    }
+    const workflows = join(path, 'workflows')
+    for (const file of await readdir(workflows)) {
+      if (!keep.includes(`${name}/workflows/${file}`)) await rm(join(workflows, file))
+    }
+    await rename(path, join(target, name))
+  }
+
+  // Standalone provider configuration is just as target-specific as workflows.
+  for (const [from, to] of [['gitlab-ci.yml.template', '.gitlab-ci.yml'], ['wrangler.json.template', 'wrangler.json']]) {
+    if (deployment.files.includes(to)) await rename(join(target, from), join(target, to))
+    else await rm(join(target, from))
+  }
+
+  const manifest = join(target, 'package.json')
+  const npm = answers.packageManager === 'npm'
+  const scripts = Object.keys(JSON.parse(await readFile(manifest, 'utf8')).scripts)
+
+  // Substitute placeholders in every text file, and translate commands for npm.
+  const walk = async (dir) => {
+    for (const item of await readdir(dir, { withFileTypes: true })) {
+      const path = join(dir, item.name)
+      if (item.isDirectory()) await walk(path)
+      else if (TEXT_FILE.test(item.name) || TEXT_NAMES.has(item.name)) {
+        const text = fill(await readFile(path, 'utf8'), answers)
+        await writeFile(path, npm ? forNpm(text, scripts) : text)
+      }
+    }
+  }
+  await walk(target)
+
+  // `packageManager` pins pnpm for Corepack and for pnpm/action-setup.
+  if (npm) {
+    const pkg = JSON.parse(await readFile(manifest, 'utf8'))
+    delete pkg.packageManager
+    await writeFile(manifest, `${JSON.stringify(pkg, null, 2)}\n`)
+  }
+}

package/template/_forgejo/workflows/codeberg.yml

@@ -0,0 +1,37 @@
+# Builds the site and uploads only the checked output to Codeberg Pages.
+# Codeberg Pages now uses git-pages; no pages branch or webhook is needed here.
+# Enable Actions in repository settings. Codeberg's hosted runners require a
+# PUBLIC, freely licensed repository. For private CV source, use your own
+# compatible runner and change runs-on below; do not make sensitive source public.
+# The automatic token authorizes the matching <owner>.codeberg.page/<repo>/ site.
+# For a root site or custom domain, change BOTH NUXT_APP_BASE_URL and site below.
+# Custom domains also need DNS authorization: https://docs.codeberg.org/codeberg-pages/using-custom-domain/
+name: Deploy (Codeberg Pages)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    if: ${{ forgejo.ref == 'refs/heads/main' }}
+    # Use a Docker-capable runner; Nuxt builds need more than the tiny tier.
+    runs-on: codeberg-medium
+    env:
+      NUXT_APP_BASE_URL: /${{ forgejo.event.repository.name }}/
+    steps:
+      - uses: https://github.com/actions/checkout@v7
+      - uses: https://github.com/pnpm/action-setup@v6
+      - uses: https://github.com/actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - uses: https://codeberg.org/git-pages/action@v2
+        with:
+          site: https://${{ forgejo.repository_owner }}.codeberg.page/${{ forgejo.event.repository.name }}/
+          server: codeberg.page
+          token: ${{ forgejo.token }}
+          source: .output/public/

package/template/_github/workflows/cloudflare.yml

@@ -1,10 +1,12 @@
 # Builds the site and deploys it to Cloudflare Pages.
 #
-# Recommended when the repository is private: Cloudflare Pages builds from
-# private repositories on the free tier, which GitHub Pages does not.
+# GitHub Actions builds the site and uploads only .output/public; the source
+# repository can stay private. The site is public at <project>.pages.dev (or
+# your custom domain). Free-tier hosting and GitHub Actions usage limits apply.
 #
-# Secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.
-# Set `projectName` to your Pages project.
+# Setup: create a Pages Direct Upload project with production branch `main`.
+# Set --project-name below to its name.
+# Secrets: CLOUDFLARE_API_TOKEN (Pages edit permission), CLOUDFLARE_ACCOUNT_ID.
 name: Deploy (Cloudflare Pages)
 
 on:

package/template/_github/workflows/cv.yml

@@ -24,7 +24,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
       # Generate the .tex files here: the LaTeX action runs in its own container,
       # without Node. cv-tex/latexmkrc lets it find the generated document class.
-      - run: pnpm build:cv --no-pdf
+      - run: pnpm pdf --tex-only
       - uses: xu-cheng/latex-action@v4
         with:
           working_directory: cv-tex

package/template/_github/workflows/workers.yml

@@ -0,0 +1,39 @@
+# Builds the site and deploys static assets to Cloudflare Workers (not Pages).
+# wrangler.json points exclusively to .output/public. No Worker script or SSR.
+# Setup: enable your account's workers.dev subdomain and choose an available
+# Worker name in wrangler.json, or configure a custom domain there.
+# Secrets: CLOUDFLARE_API_TOKEN (Workers Scripts edit permission),
+#          CLOUDFLARE_ACCOUNT_ID. The source repository can stay private.
+name: Deploy (Cloudflare Workers)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cloudflare-workers
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          wranglerVersion: '4'
+          command: deploy

package/template/app/assets/css/main.css

@@ -34,6 +34,18 @@ a {
 .vita-section {
   @apply divide-y divide-neutral-100;
 }
+.vita-section-group {
+  @apply mt-10;
+}
+.vita-section-group__title {
+  @apply text-xl font-semibold;
+}
+.vita-section-group > .vita-section {
+  @apply mt-3;
+}
+.vita-section-group__subtitle {
+  @apply mt-6 text-sm font-semibold text-neutral-600;
+}
 .vita-links {
   @apply flex flex-wrap gap-x-4 gap-y-1;
 }

package/template/app/pages/cv.vue

@@ -3,18 +3,16 @@
  * The CV page: several sections composed in the order you want them.
  *
  * Section order, headings and which sections appear are decided here, not in
- * the data — exactly as `cv.tex` decides them for the PDF.
+ * the data — exactly as `cv-tex/cv.tex` decides them for the PDF. One line per
+ * section: move a line to move a section, delete it to leave the section out.
+ * A section without entries is not shown, heading included.
  */
 const profile = useProfile()
-const page = usePage('/cv/')!
+const page = usePage('/cv/')
 
-const sections = [
-  { id: 'employment', label: 'Employment' },
-  { id: 'education', label: 'Education' },
-  { id: 'teaching', label: 'Teaching' },
-  { id: 'supervision', label: 'Supervised theses' },
-  { id: 'talks', label: 'Talks' },
-]
+if (!page) {
+  throw createError({ statusCode: 404, statusMessage: 'No page for /cv/ (expected content/pages/cv.md)', fatal: true })
+}
 
 useHead({
   title: `${page.title} – ${profile.name}`,
@@ -24,16 +22,13 @@ useHead({
 
 <template>
   <article>
-    <h1 class="text-3xl font-semibold">
-      {{ page.title }}
-    </h1>
+    <h1 class="text-3xl font-semibold" v-html="page.titleHtml" />
     <VitaMarkdown class="mt-6" :html="page.bodyHtml" />
 
-    <section v-for="section in sections" :key="section.id" class="mt-10">
-      <h2 class="text-xl font-semibold">
-        {{ section.label }}
-      </h2>
-      <VitaSection :id="section.id" class="mt-3" />
-    </section>
+    <VitaSection id="employment" title="Employment" />
+    <VitaSection id="education" title="Education" />
+    <VitaSection id="teaching" title="Teaching" />
+    <VitaSection id="supervision" title="Supervised theses" />
+    <VitaSection id="talks" title="Talks" />
   </article>
 </template>

package/template/app/pages/index.vue

@@ -30,12 +30,12 @@ useHead({
         <h1 class="text-3xl font-semibold">
           {{ profile.name }}
         </h1>
-        <p v-if="profile.title" class="text-neutral-600">
+        <p v-if="profile.title || profile.affiliation" class="text-neutral-600">
           {{ profile.title }}
+          <template v-if="profile.title && profile.affiliation"> · </template>
           <template v-if="profile.affiliation">
-            ·
-            <a v-if="profile.affiliation.url" :href="profile.affiliation.url">{{ profile.affiliation.name }}</a>
-            <template v-else>{{ profile.affiliation.name }}</template>
+            <a v-if="profile.affiliation.url" :href="profile.affiliation.url">{{ profile.affiliation.label }}</a>
+            <template v-else>{{ profile.affiliation.label }}</template>
           </template>
         </p>
         <p v-if="profile.email" class="mt-1 text-sm">

package/template/app/pages/publications.vue

@@ -6,7 +6,11 @@
  * escape hatch when a page needs prose *and* components.
  */
 const profile = useProfile()
-const page = usePage('/publications/')!
+const page = usePage('/publications/')
+
+if (!page) {
+  throw createError({ statusCode: 404, statusMessage: 'No page for /publications/ (expected content/pages/publications.md)', fatal: true })
+}
 
 useHead({
   title: `${page.title} – ${profile.name}`,
@@ -16,9 +20,7 @@ useHead({
 
 <template>
   <article>
-    <h1 class="text-3xl font-semibold">
-      {{ page.title }}
-    </h1>
+    <h1 class="text-3xl font-semibold" v-html="page.titleHtml" />
     <VitaMarkdown class="mt-6" :html="page.bodyHtml" />
     <VitaPublications class="mt-8" />
   </article>

package/template/content/pages/cv.md

@@ -4,6 +4,6 @@ description: The same data that produces the PDF.
 order: 30
 ---
 
-Build the PDF version with `pnpm build:cv`. The sections below come from the
+Build the PDF version with `pnpm pdf`. The sections below come from the
 YAML files in `content/`; their order is decided in `app/pages/cv.vue`, and the
 order in the PDF in `cv-tex/cv.tex`.

package/template/content/pages/index.md

@@ -1,5 +1,5 @@
 ---
-title: __NAME__
+title: __YAML_NAME__
 order: 0
 ---
 
@@ -8,4 +8,4 @@ Replace this page with a few sentences about yourself: it lives in
 
 Everything on this site comes from the files in `content/`, and the same data
 produces `cv-tex/cv.pdf`. Add a page by adding a Markdown file; add a CV
-section by adding a YAML file — `pnpm vitakit add outreach` sets one up.
+section by adding a YAML file — `pnpm vitakit add section outreach` sets one up.

package/template/content/profile.yml

@@ -1,9 +1,9 @@
 # You, and the shape of your site. The only file that is not a CV section.
-name: __NAME__
-title: __TITLE__
+name: __YAML_NAME__
+title: __YAML_TITLE__
 affiliation:
-  name: __AFFILIATION__
-email: __EMAIL__
+  name: __YAML_AFFILIATION__
+email: __YAML_EMAIL__
 
 # Where the site is published. Only the PDF needs it, to link files on the
 # site such as /slides/talk.pdf; delete the # once you know the address.
@@ -19,8 +19,7 @@ links:
 
 # One or two sentences for search engines and link previews. What visitors
 # read is content/pages/index.md, not this.
-summary: >-
-  __TITLE__ at __AFFILIATION__, working on your research area.
+summary: __YAML_SUMMARY__
 
 # Navigation, in the order it should appear. Adding a page does not change
 # this list: the wording and the order are yours.

package/template/content/publications.bib

@@ -4,7 +4,7 @@
 % The non-standard `status` field decides the grouping on /publications/ and in
 % the PDF: published, accepted, preprint, software or other; without it, an
 % entry is published. To change the groups:
-%     pnpm vitakit eject publications        # -> schemas/publications.ts
+%     pnpm vitakit customize publications    # -> schemas/publications.ts
 %
 % `doi`, `arxiv`, `mrnumber` and `zbl` become links; `eprint` with
 % `eprinttype = {arxiv}` (or `archivePrefix`) works as `arxiv` does, so exports

package/template/cv-tex/cv.tex

@@ -1,4 +1,5 @@
-% Your CV. This file decides the ORDER of things; cv.yml decides what goes in.
+% Your CV. This file decides the ORDER of things and their headings; cv.yml
+% decides what goes in. app/pages/cv.vue does the same for the website.
 %
 % Styling: redefine the macros in preamble.tex. For deeper changes run
 %   pnpm vitakit eject vitakit-cv.cls
@@ -15,7 +16,7 @@
 \addbibresource{../content/publications.bib}
 
 \input{preamble.tex}
-\input{generated/cv/profile.tex}
+\vitainput{profile}
 
 \begin{document}
 \vitaheader
@@ -25,14 +26,14 @@
 % sections vitakit generates from content/.
 % \input{prose/research-statement.tex}
 
-\vitasection{employment}
-\vitasection{education}
-\vitasection{teaching}
+\vitasection[Employment]{employment}
+\vitasection[Education]{education}
+\vitasection[Teaching]{teaching}
 
 \section{Publications}
 \vitainput{publications}
 
-\vitasection{supervision}
-\vitasection{talks}
+\vitasection[Supervised theses]{supervision}
+\vitasection[Selected talks]{talks}
 
 \end{document}

package/template/cv-tex/latexmkrc

@@ -1,5 +1,5 @@
 # Lets a plain `latexmk cv.tex` (in CI, or from an editor) find the document
-# class, which `pnpm build:cv` writes to generated/<document>/. A copy in this
+# class, which `pnpm pdf` writes to generated/<document>/. A copy in this
 # directory (`pnpm vitakit eject vitakit-cv.cls`) still wins: `.` comes first.
 # The trailing separator keeps TeX's default search path.
 $ENV{'TEXINPUTS'} = join($search_path_separator, '.', './generated//', $ENV{'TEXINPUTS'} // '');

package/template/cv-tex/preamble.tex

@@ -2,9 +2,6 @@
 % vitakit-cv.cls, so redefining them changes the design without touching
 % anything vitakit produces.
 
-% Section headings as they should appear in this document:
-\vitasectiontitle{employment}{Employment}
-\vitasectiontitle{education}{Education}
-\vitasectiontitle{teaching}{Teaching}
-\vitasectiontitle{talks}{Selected talks}
-\vitasectiontitle{supervision}{Supervised theses}
+% Headings are written where a section is included, \vitasection[Talks]{talks}.
+% For one wording shared by every document that includes this preamble:
+%   \vitasectiontitle{talks}{Selected talks}

package/template/gitlab-ci.yml.template

@@ -0,0 +1,28 @@
+# Builds and checks the site, then publishes only the static output.
+# Requires GitLab 17.10+ with Pages and a Docker-compatible CI runner enabled.
+# Private source projects are supported; set Pages access to Everyone for a
+# public website (Settings -> General -> Visibility, project features, permissions).
+# For a root-level custom domain, set NUXT_APP_BASE_URL=/ in CI/CD variables.
+image: node:22-bookworm
+
+stages: [deploy]
+
+deploy-pages:
+  stage: deploy
+  before_script:
+    - corepack enable
+    - corepack install
+    - pnpm install --frozen-lockfile
+  script:
+    # CI_PAGES_URL handles unique domains, project paths and subgroup paths.
+    # An explicit CI/CD variable can override it for a custom domain.
+    - |
+      if [ -z "${NUXT_APP_BASE_URL:-}" ]; then
+        NUXT_APP_BASE_URL="$(node -e 'const path = new URL(process.env.CI_PAGES_URL).pathname; process.stdout.write(path.endsWith("/") ? path : path + "/")')"
+        export NUXT_APP_BASE_URL
+      fi
+    - pnpm check
+  pages:
+    publish: .output/public
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

package/template/package.json.template

@@ -12,12 +12,11 @@
     "preview": "nuxt preview",
     "postinstall": "nuxt prepare",
     "typecheck": "nuxt typecheck",
-    "check:static": "vitakit-check",
-    "check": "pnpm typecheck && pnpm generate && pnpm check:static",
-    "build:cv": "vitakit-build-cv"
+    "check": "pnpm typecheck && pnpm generate && vitakit verify",
+    "pdf": "vitakit pdf"
   },
   "dependencies": {
-    "@anja.codes/vitakit": "^0.1.0",
+    "@anja.codes/vitakit": "^0.2.0",
     "@nuxt/fonts": "^0.14.0",
     "@tailwindcss/vite": "^4.3.3",
     "nuxt": "^4.5.2",

package/template/wrangler.json.template

@@ -0,0 +1,10 @@
+{
+  "name": "__SLUG__",
+  "compatibility_date": "2026-10-18",
+  "workers_dev": true,
+  "assets": {
+    "directory": "./.output/public",
+    "html_handling": "auto-trailing-slash",
+    "not_found_handling": "404-page"
+  }
+}