@kamod-ch/preactpress 1.0.0

package/templates/hono/README.md

@@ -0,0 +1,41 @@
+# PreactPress Hono-style starter site
+
+This folder was scaffolded with `preactpress init --template hono`.
+
+It combines a hono.dev-inspired landing page with a full documentation starter, MDX examples, and an English/German i18n demo.
+
+## Commands
+
+| Script | What it does |
+| --- | --- |
+| `pnpm run dev` | Start the dev server at http://localhost:5173 |
+| `pnpm run check` | Validate config, routes, and links |
+| `pnpm run build` | Write static HTML to `dist/` |
+| `pnpm run preview` | Serve the production build locally |
+
+## Where to edit
+
+| Path | Purpose |
+| --- | --- |
+| `*.md`, `*.mdx` | Page content — file path becomes the URL |
+| `index.mdx`, `de/index.mdx` | Landing pages with the hero and feature cards |
+| `de/*.md`, `de/*.mdx` | German pages for the bundled i18n demo |
+| `.preactpress/config.ts` | Site title, nav, sidebar, locales, build options |
+| `.preactpress/theme/` | Custom Hono-style layout, components, and CSS |
+| `components/` | Preact components for MDX pages |
+| `index.html` | Vite entry (rarely edited) |
+
+Start with [Your first 5 minutes](/guide/first-five-minutes) in the local site, or read the full PreactPress README in the npm package / repository.
+
+This starter includes English pages at the root and German pages under `/de/`. Remove the `de/` folder and `locales` config if you want a single-language site.
+
+## Deploy
+
+```bash
+pnpm run check
+pnpm run build
+```
+
+Upload **only** `dist/` to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any static host. No Node server is required in production.
+
+Before the first production build, set `site.url` (and `site.base` for subpath hosting) in `.preactpress/config.ts`.

package/templates/hono/about.md

@@ -0,0 +1,10 @@
+---
+title: About
+description: About this site
+---
+
+# About us
+
+Your content here.
+
+This page was added as part of the [Your first 5 minutes](/guide/first-five-minutes) tutorial. Replace this text with your own copy — team bio, project mission, contact details, or anything else that belongs on an About page.

package/templates/hono/components/Counter.tsx

@@ -0,0 +1,25 @@
+import { useState } from 'preact/hooks'
+
+export default function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial)
+
+  return (
+    <div style={{ display: 'inline-flex', alignItems: 'center', gap: '0.5rem' }}>
+      <button
+        type="button"
+        onClick={() => setCount((value) => value - 1)}
+        aria-label="Decrease count"
+      >
+        −
+      </button>
+      <span>{count}</span>
+      <button
+        type="button"
+        onClick={() => setCount((value) => value + 1)}
+        aria-label="Increase count"
+      >
+        +
+      </button>
+    </div>
+  )
+}

package/templates/hono/de/about.md

@@ -0,0 +1,10 @@
+---
+title: Über uns
+description: Über diese Website
+---
+
+# Über uns
+
+Hier steht dein Inhalt.
+
+Diese Seite wurde im Tutorial [Die ersten 5 Minuten](/de/guide/first-five-minutes) hinzugefügt. Ersetze diesen Text durch deine eigenen Inhalte — Teamvorstellung, Projektziel, Kontaktinformationen oder alles, was auf eine Über-uns-Seite gehört.

package/templates/hono/de/guide/commands.md

@@ -0,0 +1,44 @@
+---
+title: Befehle
+description: PreactPress-CLI für Entwicklung und Produktions-Builds
+---
+
+Die PreactPress-CLI wird im Site-Root ausgeführt (Ordner mit `.preactpress/config.ts`).
+
+## Entwicklung
+
+```bash
+pnpm exec preactpress dev
+```
+
+Startet Vite mit SSR, Hot Reload und dem gleichen HTML-Head wie in Production.
+
+## Production
+
+```bash
+pnpm exec preactpress build
+pnpm exec preactpress preview
+```
+
+`build` schreibt statisches HTML nach `outDir` (Standard: `dist/`). `preview` dient nur zur lokalen Vorschau.
+
+## Projekt anlegen
+
+```bash
+pnpm exec preactpress init
+pnpm exec preactpress init --template docs
+```
+
+Das `docs`-Template enthält diese Anleitung, i18n-Beispiele und Referenzseiten.
+
+## Validierung
+
+```bash
+pnpm exec preactpress check
+```
+
+Prüft Config, Routen-Kollisionen, Nav-/Sidebar-Links, interne Markdown-Links und Draft-Seiten.
+
+::: tip
+`check` in CI einbinden, damit kaputte Sidebar-Links vor dem Merge auffallen.
+:::

package/templates/hono/de/guide/configuration.md

@@ -0,0 +1,64 @@
+---
+title: Konfiguration
+description: Site-Config, Theme-Optionen und häufige Frontmatter-Felder
+---
+
+Die Konfiguration liegt in `.preactpress/config.ts` im Site-Root.
+
+## Site-Metadaten
+
+```ts
+export default {
+  site: {
+    title: 'Meine Docs',
+    description: 'Kurzbeschreibung für SEO',
+    base: '/',
+    url: 'https://example.com',
+    titleTemplate: ':title | :siteTitle'
+  }
+}
+```
+
+`site.url` vor dem Go-Live setzen — für Canonical-URLs, `sitemap.xml`, Open Graph und `hreflang`.
+
+## Inhaltsverzeichnis
+
+| Option | Zweck |
+| --- | --- |
+| `srcDir` | Ordner mit `.md` / `.mdx` (Standard `.`) |
+| `srcExclude` | Glob-Muster für Nicht-Seiten, z. B. `['**/README.md']` |
+| `lastUpdatedGit` | Git-Commit-Zeit für „Zuletzt aktualisiert“ (Fallback: mtime) |
+
+## Theme ohne eigenen Code
+
+`themeConfig` steuert das Standard-Layout:
+
+- `nav` — Kopfzeilen-Links; verschachtelte Dropdowns über `items`
+- `sidebar` — flaches Array **oder** Pfad-Map; Gruppen und Einträge unterstützen `collapsed` und verschachtelte `items`
+- `outline`, `search`, `socialLinks`, `footer`, `lastUpdated`, `editLink`, `logo`, `labels`
+- `logo` — String-URL oder `{ light, dark }` für theme-aware Bilder
+- `search` — `true` oder `{ provider: 'local' }` für Sidebar-Suche; `{ provider: 'algolia', options }` für Algolia DocSearch in der Nav-Leiste
+- `socialLinks` — `{ icon, link, ariaLabel? }[]` mit eingebauten Icons (`github`, `discord`, `x`, …) oder eigenem `{ svg }`
+
+Locale-Overrides unter `locales.<key>.themeConfig`.
+
+## Globale Head-Tags
+
+```ts
+head: [
+  ['meta', { name: 'theme-color', content: '#0f766e' }]
+]
+```
+
+## Frontmatter pro Seite
+
+| Feld | Zweck |
+| --- | --- |
+| `title` / `description` | Seitentitel und SEO-Text |
+| `titleTemplate` | Site-Template überschreiben; `false` = nur Seitentitel |
+| `head` | Zusätzliche `<meta>` / `<link>` / `<script>` nur für diese Seite |
+| `draft: true` | Aus Routen, Suche und Sitemap ausgeschlossen |
+
+::: warning
+`markdown.html` nur für vertrauenswürdige Inhalte aktivieren — erlaubt rohes HTML in Markdown.
+:::

package/templates/hono/de/guide/deploy.md

@@ -0,0 +1,197 @@
+---
+title: Deploy
+description: Eine PreactPress-Site bauen und veröffentlichen
+---
+
+# Deploy
+
+PreactPress erzeugt statische Dateien. Produktion bedeutet: Build ausführen und das Ausgabeverzeichnis, normalerweise `dist/`, auf einen Static Host hochladen.
+
+In Produktion ist kein Node-Server nötig.
+
+## Lokal bauen und testen
+
+Führe Release-Checks und Produktionsbuild im Site-Verzeichnis aus:
+
+```bash
+pnpm run check
+pnpm run build
+```
+
+Sieh dir den Build lokal an:
+
+```bash
+pnpm run preview
+```
+
+Der Preview-Server stellt den gebauten Output standardmäßig unter **http://localhost:4173** bereit.
+
+## Produktionsmetadaten konfigurieren
+
+Setze `site.url` vor der Veröffentlichung. PreactPress nutzt diese URL für Canonical URLs, Open-Graph-Metadaten, `sitemap.xml` und `robots.txt`.
+
+```ts
+export default {
+  site: {
+    title: 'Meine Site',
+    description: 'Kurze Beschreibung für Suche und Social Previews',
+    url: 'https://example.com',
+    base: '/'
+  },
+  build: {
+    sitemap: true,
+    robots: true
+  }
+}
+```
+
+## Public Base Path
+
+Standardmäßig nimmt PreactPress an, dass deine Site am Domain-Root ausgeliefert wird:
+
+```text
+https://example.com/
+```
+
+Wenn die Site unter einem Unterpfad liegt, setze `site.base`:
+
+```ts
+export default {
+  site: {
+    url: 'https://user.github.io',
+    base: '/my-repo/'
+  }
+}
+```
+
+Du kannst den Base Path auch nur für einen einzelnen Build überschreiben:
+
+```bash
+pnpm exec preactpress build --base /my-repo/
+```
+
+## Build-Output
+
+Das Standard-Ausgabeverzeichnis ist `dist/`:
+
+| Ausgabe | Beschreibung |
+| --- | --- |
+| `index.html`, `*/index.html` | Statisches HTML für jede Route |
+| `assets/*` | Gehashtes JavaScript und CSS von Vite |
+| `404.html` | Fehlerseite |
+| `preactpress-search.json` | Suchindex für das Standard-Theme |
+| `preactpress-content/*.json` | Lazy geladene Markdown-Payloads für Client-Navigation |
+| `sitemap.xml`, `robots.txt` | Erzeugt, wenn `site.url` und Build-Flags gesetzt sind |
+| `feed.xml` | Erzeugt, wenn `build.feed` konfiguriert ist |
+
+Deploye nur das Ausgabeverzeichnis. Deploye nicht `node_modules`, `.preactpress` oder den Build-Cache.
+
+## Plattform-Einstellungen
+
+Für die meisten Static Hosts reichen diese Einstellungen:
+
+| Host | Build-Befehl | Output-Verzeichnis |
+| --- | --- | --- |
+| Netlify | `pnpm run build` | `dist` |
+| Vercel | `pnpm run build` | `dist` |
+| Cloudflare Pages | `pnpm run build` | `dist` |
+| Render Static Site | `pnpm run build` | `dist` |
+
+Install-Befehl:
+
+```bash
+pnpm install
+```
+
+Node-Version: **20 oder höher**.
+
+## GitHub Pages
+
+Für eine Projektseite unter `https://user.github.io/my-repo/` konfigurierst du:
+
+```ts
+export default {
+  site: {
+    url: 'https://user.github.io',
+    base: '/my-repo/'
+  }
+}
+```
+
+Danach deployest du das Verzeichnis `dist/`.
+
+Ein minimales GitHub-Actions-Workflow kann so aussehen:
+
+```yaml
+name: Deploy PreactPress site to Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - uses: actions/configure-pages@v5
+      - run: pnpm install
+      - run: pnpm run check
+      - run: pnpm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+Setze in den Repository-Einstellungen die Pages-Quelle auf **GitHub Actions**.
+
+## Monorepos
+
+In einem Monorepo führst du die Befehle aus dem Site-Paket aus:
+
+```bash
+cd packages/docs
+pnpm run check
+pnpm run build
+```
+
+Oder du übergibst der CLI den Site-Pfad:
+
+```bash
+pnpm exec preactpress build ./packages/docs
+```
+
+## Cache-Headers
+
+Dateien unter `assets/` enthalten Content-Hashes in ihren Dateinamen. Wenn dein Host HTTP-Header setzen kann, cache diese Dateien aggressiv:
+
+```text
+Cache-Control: public, max-age=31536000, immutable
+```
+
+Wende immutable Caching nicht auf HTML-Dateien oder JSON-Payloads wie `preactpress-search.json` und `preactpress-content/*.json` an, weil diese URLs bei Inhaltsänderungen gleich bleiben können.

package/templates/hono/de/guide/first-five-minutes.md

@@ -0,0 +1,82 @@
+---
+title: Die ersten 5 Minuten
+description: Seitentitel ändern, eine Seite hinzufügen und die Navigation aktualisieren
+---
+
+# Die ersten 5 Minuten
+
+Dieses praktische Tutorial folgt der Setup-Übersicht in [Getting Started](/de/guide/getting-started). Folge den Schritten in **deinem** Projekt — diese Website zeigt das Ergebnis.
+
+## 1. Seitentitel ändern
+
+Bearbeite `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: {
+    title: 'Meine Doku',
+    description: 'Kurze Beschreibung für Suche und Social Previews'
+  }
+}
+```
+
+Speichere die Datei. Der Dev-Server übernimmt Config-Änderungen beim nächsten Request.
+
+## 2. Eine Seite hinzufügen
+
+Erstelle `about.md`:
+
+```md
+---
+title: Über uns
+description: Über diese Website
+---
+
+# Über uns
+
+Hier steht dein Inhalt.
+```
+
+PreactPress stellt die Seite unter `/about` bereit. Jede `.md`- oder `.mdx`-Datei unter `srcDir` (standardmäßig: Projektroot) wird automatisch zu einer URL.
+
+Beispiel: `news/2025/intro.md` → `/news/2025/intro`.
+
+Dieser Starter enthält bereits [Über uns](/de/about), damit du die fertige Seite sehen kannst.
+
+## 3. Zur Navigation hinzufügen
+
+In `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: { title: 'Meine Doku' },
+  themeConfig: {
+    nav: [
+      { text: 'Start', link: '/' },
+      { text: 'Über uns', link: '/about' }
+    ],
+    sidebar: [
+      {
+        text: 'Anleitung',
+        items: [
+          { text: 'Start', link: '/' },
+          { text: 'Über uns', link: '/about' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Speichern — der Dev-Server lädt die Änderung automatisch.
+
+## Nächste Schritte
+
+| Befehl | Zweck |
+| --- | --- |
+| `pnpm run dev` | Dev-Server mit SSR und Hot Reload |
+| `pnpm run check` | Config, Links und Routen prüfen |
+| `pnpm run build` | Statischer Produktionsbuild → `dist/` |
+| `pnpm run preview` | Lokale Vorschau des Builds |
+
+Setze vor dem Deployment `site.url` in der Config, damit Canonical URLs, Open Graph Tags und `sitemap.xml` erzeugt werden. Lies danach [Routing](/de/guide/routing), um dateibasierte Routen zu verstehen, und [Deploy](/de/guide/deploy) für die Produktionsschritte.

package/templates/hono/de/guide/getting-started.md

@@ -0,0 +1,146 @@
+---
+title: Getting Started
+description: PreactPress installieren und eine neue Dokumentationsseite starten
+---
+
+# Getting Started
+
+Diese Anleitung zeigt, wie du eine PreactPress-Site erstellst, die generierten Dateien verstehst und den Dev-Server startest.
+
+## Voraussetzungen
+
+Du brauchst:
+
+| Voraussetzung | Version |
+| --- | --- |
+| Node.js | 20 oder höher |
+| Package Manager | pnpm empfohlen; npm, yarn und bun funktionieren ebenfalls |
+| Editor | Jeder Editor mit Markdown- und TypeScript-Unterstützung |
+
+## Site erstellen
+
+Starte in einem leeren Ordner:
+
+```bash
+mkdir my-site
+cd my-site
+pnpm dlx @kamod-ch/preactpress init
+pnpm install
+pnpm run dev
+```
+
+Mit npm:
+
+```bash
+mkdir my-site
+cd my-site
+npx @kamod-ch/preactpress init
+npm install
+npm run dev
+```
+
+Öffne **http://localhost:5173**, um die Starter-Site zu sehen.
+
+> **Hinweis**
+> `preactpress init` kopiert das eingebaute Starter-Template und schreibt `@kamod-ch/preactpress` in `devDependencies`. Du musst PreactPress vor dem Initialisieren nicht separat installieren.
+
+## Dateistruktur
+
+Nach der Initialisierung sieht das Projekt so aus:
+
+```text
+my-site/
+├── README.md
+├── index.html
+├── index.md
+├── about.md
+├── guide/
+│   └── first-five-minutes.md
+├── markdown-examples.md
+├── interactive.mdx
+├── components/
+│   └── Counter.tsx
+└── .preactpress/
+    └── config.ts
+```
+
+Der Ordner `.preactpress` enthält die Site-Konfiguration. Markdown- und MDX-Dateien außerhalb von `.preactpress` sind Quelldateien und werden zu Routen.
+
+## Die Config-Datei
+
+Die Starter-Config liegt unter `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: {
+    title: 'Meine Doku',
+    description: 'Kurze Beschreibung für Suche und Social Previews'
+  },
+  themeConfig: {
+    nav: [
+      { text: 'Start', link: '/de' },
+      { text: 'Anleitung', link: '/de/guide/what-is-preactpress' }
+    ],
+    sidebar: [
+      {
+        text: 'Einführung',
+        items: [
+          { text: 'Was ist PreactPress?', link: '/de/guide/what-is-preactpress' },
+          { text: 'Getting Started', link: '/de/guide/getting-started' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Nutze `site` für globale Metadaten und `themeConfig` für Optionen des Standard-Themes wie Logo (`logo: '/logo.svg'`), Navigation, Sidebar, Suche, Outline, Footer und Edit-Links.
+
+## Quelldateien
+
+PreactPress nutzt dateibasiertes Routing. Standardmäßig ist der Projektroot auch das Quellverzeichnis:
+
+```text
+index.md                  -> /
+about.md                  -> /about
+guide/getting-started.md  -> /guide/getting-started
+interactive.mdx           -> /interactive
+```
+
+Mit `srcDir` kannst du das Quellverzeichnis ändern:
+
+```ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+Mit dieser Config liest PreactPress Seiten aus `docs/`, während `.preactpress/config.ts` weiterhin zum Projektroot gehört.
+
+## Befehle
+
+Der Starter enthält npm-Scripts:
+
+| Befehl | Zweck |
+| --- | --- |
+| `pnpm run dev` | Dev-Server mit SSR und Hot Reload starten |
+| `pnpm run check` | Config, Routen und Links validieren |
+| `pnpm run build` | Statischen Produktionsbuild nach `dist/` schreiben |
+| `pnpm run preview` | Produktionsbuild lokal ansehen |
+
+Du kannst die CLI auch direkt aufrufen:
+
+```bash
+pnpm exec preactpress dev
+pnpm exec preactpress check
+pnpm exec preactpress build
+pnpm exec preactpress preview
+```
+
+## Was kommt als Nächstes?
+
+| Seite | Warum |
+| --- | --- |
+| [Die ersten 5 Minuten](/de/guide/first-five-minutes) | Titel ändern, Seite anlegen und Navigation verdrahten |
+| [Routing](/de/guide/routing) | Lernen, wie Markdown-Dateien zu URLs werden |
+| [Deploy](/de/guide/deploy) | Das erzeugte `dist/`-Verzeichnis bauen und veröffentlichen |