@anja.codes/create-vitakit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anja Ressmann, Benjamin Hackl
+
+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,48 @@
-# Temporary Holding Version
+# @anja.codes/create-vitakit
 
-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.
+Scaffold a [vitakit](https://github.com/anja-codes/vitakit) project: an academic
+website and a LaTeX CV built from one set of files.
+
+```bash
+pnpm create @anja.codes/vitakit my-site
+cd my-site
+pnpm install
+pnpm dev            # http://localhost:3000
+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 Workers or Pages, GitLab Pages, Codeberg Pages,
+existing web space via SSH/rsync, or decide later), copies the template and
+substitutes those few values.
+
+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

@@ -0,0 +1,99 @@
+#!/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, 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 { readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import process from 'node:process'
+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'
+}
+
+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
+  }
+  if (args.includes('--deployment-help')) {
+    console.log(deploymentHelp())
+    return
+  }
+
+  const [directoryArgument] = args.filter(argument => !argument.startsWith('-'))
+  const interactive = process.stdin.isTTY && !process.env.VITAKIT_CREATE_DEFAULTS
+
+  const answers = {
+    name: 'Your Name',
+    title: 'Postdoctoral Researcher',
+    affiliation: 'Department of Mathematics, University of Graz',
+    email: 'you@example.org',
+    deployment: 'github-pages',
+    packageManager,
+  }
+
+  let directory = directoryArgument
+
+  if (interactive) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const ask = async (question, fallback) => {
+      const answer = (await rl.question(`${question} (${fallback}) `)).trim()
+      return answer || fallback
+    }
+
+    console.log('\nvitakit — a website and a LaTeX CV from one set of files.\n')
+    answers.name = await ask('Your name:', answers.name)
+    answers.title = await ask('Your position:', answers.title)
+    answers.affiliation = await ask('Affiliation:', answers.affiliation)
+    answers.email = await ask('Email:', answers.email)
+    directory ??= await ask('Directory:', slugify(answers.name))
+
+    try {
+      answers.deployment = await chooseDeployment(ask)
+    } finally {
+      rl.close()
+    }
+  }
+
+  directory ??= slugify(answers.name)
+  answers.slug = slugify(basename(directory))
+  const target = resolve(process.cwd(), directory)
+
+  if (existsSync(target) && (await readdir(target)).length) {
+    throw new Error(`${directory} already exists and is not empty`)
+  }
+
+  await scaffold(target, answers)
+
+  console.log(`\nCreated ${directory}\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) => {
+  console.error(`\n@anja.codes/create-vitakit: ${error instanceof Error ? error.message : String(error)}\n`)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@anja.codes/create-vitakit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Scaffold a vitakit project: an academic website and a LaTeX CV from one set of files.",
+  "license": "MIT",
+  "keywords": [
+    "vitakit",
+    "create",
+    "scaffold",
+    "cv",
+    "academic",
+    "nuxt",
+    "latex"
+  ],
+  "homepage": "https://vitakit.anja.codes/guide/tutorial/",
+  "bugs": {
+    "url": "https://github.com/anja-codes/vitakit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anja-codes/vitakit.git",
+    "directory": "create"
+  },
+  "type": "module",
+  "bin": {
+    "create-vitakit": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "scaffold.mjs",
+    "deployments.mjs",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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/.gitignore.template

@@ -0,0 +1,19 @@
+# Nuxt
+.output
+.nuxt
+.data
+.nitro
+.cache
+dist
+node_modules
+
+# vitakit / latexmk output
+# Everything generated lives in cv-tex/generated/ (the .cls and all auxiliary
+# files included); only the finished PDF is written beside the sources.
+cv-tex/generated
+cv-tex/*.pdf
+
+# Misc
+*.log
+.DS_Store
+.env

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/_forgejo/workflows/deploy.yml

@@ -0,0 +1,31 @@
+# Builds the site and deploys it to web space via rsync.
+#
+# Secret: SSH_DEPLOY_KEY (private key with write access to the target).
+# Adjust NUXT_APP_BASE_URL and the rsync target below.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      NUXT_APP_BASE_URL: /
+    steps:
+      - uses: https://github.com/actions/checkout@v7
+      - run: apt update && apt install -y rsync
+      - uses: https://github.com/pnpm/action-setup@v6
+      # The runner image may ship an older Node than Nuxt requires.
+      - uses: https://github.com/actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - uses: https://github.com/webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.SSH_DEPLOY_KEY }}
+      - run: |
+          rsync -e "ssh -o StrictHostKeyChecking=no" -av --delete \
+            .output/public/ user@example.org:/var/www/your-site/

package/template/_github/workflows/cloudflare.yml

@@ -0,0 +1,33 @@
+# Builds the site and deploys it to Cloudflare Pages.
+#
+# 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.
+#
+# 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:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    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 }}
+          command: pages deploy .output/public --project-name=__SLUG__