@kamod-ch/preactpress 1.0.0

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

@@ -0,0 +1,220 @@
+---
+title: Routing
+description: Verstehe, wie PreactPress Dateien auf URLs abbildet
+---
+
+# Routing
+
+PreactPress nutzt dateibasiertes Routing. Jede `.md`- und `.mdx`-Datei unter `srcDir` wird zu einer Route, und Produktionsbuilds schreiben jede Route als statisches HTML.
+
+## Dateibasiertes Routing
+
+Bei dieser Struktur:
+
+```text
+.
+├── index.md
+├── about.md
+├── guide/
+│   ├── index.md
+│   └── getting-started.md
+└── interactive.mdx
+```
+
+erzeugt PreactPress diese Routen:
+
+```text
+index.md                  -> /
+about.md                  -> /about
+guide/index.md            -> /guide
+guide/getting-started.md  -> /guide/getting-started
+interactive.mdx           -> /interactive
+```
+
+Beim Produktionsbuild werden Routen als Verzeichnis-Indizes geschrieben:
+
+```text
+/                      -> dist/index.html
+/about                 -> dist/about/index.html
+/guide/getting-started -> dist/guide/getting-started/index.html
+```
+
+Standardmäßig (`cleanUrls: true`) schreibt der Build Verzeichnis-Indizes, damit Hosts URLs ohne Dateiendung ausliefern können.
+
+## Projektroot und Quellverzeichnis
+
+Der Projektroot ist der Ort, an dem PreactPress `.preactpress/config.ts` sucht.
+
+Standardmäßig liegen die Quelldateien ebenfalls im Projektroot:
+
+```text
+.
+├── .preactpress/
+│   └── config.ts
+├── index.md
+└── guide/
+    └── getting-started.md
+```
+
+Mit `srcDir` kannst du Inhalte in ein verschachteltes Quellverzeichnis legen:
+
+```ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+Dann sieht die Struktur so aus:
+
+```text
+.
+├── .preactpress/
+│   └── config.ts
+└── docs/
+    ├── index.md
+    └── guide/
+        └── getting-started.md
+```
+
+Die resultierenden Routen bleiben gleich:
+
+```text
+docs/index.md                  -> /
+docs/guide/getting-started.md  -> /guide/getting-started
+```
+
+## Zwischen Seiten verlinken
+
+Du kannst absolute oder relative Links verwenden. Empfohlen ist, Dateiendungen wegzulassen:
+
+```md
+[Getting Started](/de/guide/getting-started)
+[Routing](./routing)
+[Start](../)
+```
+
+Vermeide direkte Links auf generiertes HTML oder Markdown-Quelldateien:
+
+```md
+<!-- Vermeiden -->
+[Getting Started](/de/guide/getting-started.md)
+[Getting Started](/de/guide/getting-started.html)
+```
+
+`preactpress check` validiert lokale Markdown-Links mit `.md`-, `.mdx`- oder `.html`-Endung und meldet fehlende Seiten.
+
+## Locale-Routen
+
+PreactPress unterstützt Locale-Ordner im VitePress-Stil. Die Standardsprache liegt im Root, Übersetzungen liegen in Locale-Ordnern:
+
+```text
+index.md                       -> /
+guide/getting-started.md       -> /guide/getting-started
+de/index.md                    -> /de
+de/guide/getting-started.md    -> /de/guide/getting-started
+```
+
+Labels, Sprachcodes und lokale Navigation konfigurierst du in `.preactpress/config.ts`:
+
+```ts
+export default {
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en'
+    },
+    de: {
+      label: 'Deutsch',
+      lang: 'de',
+      link: '/de/'
+    }
+  }
+}
+```
+
+Das Standard-Theme zeigt einen Sprachumschalter, wenn mehrere Locales konfiguriert sind.
+
+## Tag-Routen
+
+Seiten können Tags im Frontmatter definieren:
+
+```md
+---
+title: Release Notes
+tags: [release, changelog]
+---
+```
+
+Jeder Tag erhält eine Index-Seite:
+
+```text
+release   -> /tags/release
+changelog -> /tags/changelog
+```
+
+Bei lokalisierten Inhalten werden Tag-Seiten pro Locale erzeugt:
+
+```text
+de/guide/intro.md mit Tag "Markdown" -> /de/tags/markdown
+```
+
+Wenn eine echte Markdown- oder MDX-Seite dieselbe Route wie ein generierter Tag-Index belegt, gewinnt die echte Seite.
+
+## Base Path
+
+Nutze `site.base`, wenn die Site unter einem Unterpfad ausgeliefert wird, zum Beispiel bei GitHub-Pages-Projektseiten:
+
+```ts
+export default {
+  site: {
+    base: '/my-repo/'
+  }
+}
+```
+
+Du kannst den Base Path auch für einen einzelnen Build überschreiben:
+
+```bash
+pnpm exec preactpress build --base /my-repo/
+```
+
+## Route Rewrites
+
+Öffentliche URLs auf bestehende Inhalte mappen, ohne Dateien zu duplizieren:
+
+```ts
+export default {
+  rewrites: {
+    '/docs': '/guide',
+    '/getting-started': '/guide/intro'
+  }
+}
+```
+
+Keys sind die Routen für Besucher; Values müssen auf Routen zeigen, die bereits aus Markdown-Dateien existieren. `preactpress check` validiert Quellen und Kollisionen.
+
+## Clean URLs und Hosting
+
+| `cleanUrls` | Ausgabe für `/about` | Typischer Host |
+| --- | --- | --- |
+| `true` (Standard) | `dist/about/index.html` | Netlify, Vercel, Cloudflare Pages, GitHub Pages |
+| `false` | `dist/about.html` | Statische Buckets ohne Directory-Index |
+
+```ts
+export default {
+  cleanUrls: false
+}
+```
+
+Die meisten modernen Static Hosts funktionieren mit dem Standard. Setze `cleanUrls: false` nur, wenn dein Host `/about` nicht zu `about/index.html` auflösen kann.
+
+## Aktuelle Grenzen
+
+PreactPress hält Routing bewusst klein. Im Vergleich zu VitePress enthält es aktuell nicht:
+
+| Feature | Status |
+| --- | --- |
+| Dynamische Routen wie `[pkg].paths.ts` | Nicht unterstützt |
+| Pattern-basierte Rewrites mit Parametern | Nicht unterstützt |
+
+Wenn deine Site viele Seiten aus externen Daten erzeugen muss, generiere Markdown- oder MDX-Dateien vor `preactpress build`.

package/templates/hono/de/guide/seiten-erstellen.md

@@ -0,0 +1,171 @@
+---
+title: Seiten erstellen
+description: Neue Markdown- und MDX-Seiten anlegen, URLs verstehen und in die Navigation einbinden
+---
+
+# Seiten erstellen
+
+In PreactPress entstehen Seiten aus Dateien — es gibt keinen separaten Seiten-Editor oder CMS. Jede `.md`- oder `.mdx`-Datei unter dem Quellverzeichnis (`srcDir`, standardmäßig das Projektroot) wird automatisch zu einer öffentlichen URL.
+
+## Kurzüberblick
+
+1. Eine neue Datei anlegen (z. B. `kontakt.md` oder `guide/neue-seite.md`).
+2. Optional Frontmatter mit `title`, `description` und `layout` ergänzen.
+3. Inhalt in Markdown oder MDX schreiben.
+4. Dev-Server lädt die Seite automatisch nach — kein Neustart nötig.
+5. Optional Eintrag in `nav` und `sidebar` in `.preactpress/config.ts` setzen.
+
+## Schritt für Schritt: eine einfache Seite
+
+Lege im Projektroot (oder unter `srcDir`) eine Markdown-Datei an, z. B. `kontakt.md`:
+
+```md
+---
+title: Kontakt
+description: So erreichst du uns
+layout: page
+---
+
+# Kontakt
+
+Schreib uns an **hello@example.com**.
+```
+
+Speichern — unter `pnpm run dev` ist die Seite sofort unter **/kontakt** erreichbar.
+
+> **Hinweis**
+> Der Dateiname (ohne Endung) bestimmt den URL-Pfad. `kontakt.md` → `/kontakt`, nicht `/kontakt.md`.
+
+## Wo die Datei liegt → welche URL
+
+PreactPress nutzt **dateibasiertes Routing**. Der Pfad relativ zu `srcDir` wird zur Route:
+
+| Datei | URL |
+| --- | --- |
+| `index.md` | `/` |
+| `about.md` | `/about` |
+| `guide/einfuehrung.md` | `/guide/einfuehrung` |
+| `guide/index.md` | `/guide` |
+| `news/2025/intro.md` | `/news/2025/intro` |
+| `interactive.mdx` | `/interactive` |
+
+Produktionsbuilds schreiben Verzeichnis-Indexe (`dist/about/index.html`), damit URLs ohne `.html` funktionieren.
+
+Ausführliche Details: [Routing](/de/guide/routing).
+
+## Quellverzeichnis (`srcDir`)
+
+Standardmäßig liegen Markdown-Dateien im Projektroot neben `.preactpress/`. Du kannst Inhalte in einen Unterordner legen:
+
+```ts
+// .preactpress/config.ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+Dann gehören alle Seiten nach `docs/` — z. B. `docs/index.md` → `/`, `docs/guide/foo.md` → `/guide/foo`. Die URLs bleiben gleich; nur der Speicherort der Dateien ändert sich.
+
+## Frontmatter (optional, aber empfohlen)
+
+YAML am Dateianfang steuert Metadaten und Darstellung:
+
+```md
+---
+title: Meine Seite
+description: Kurztext für Suche, SEO und Social Previews
+layout: doc
+---
+```
+
+| Feld | Zweck |
+| --- | --- |
+| `title` | Seitentitel (Navigation, `<title>`, Suche) |
+| `description` | Zusammenfassung für SEO und Suche |
+| `layout: doc` | Doku-Layout mit Sidebar, Gliederung und Vor/Zurück-Links |
+| `layout: page` | Inhaltsseite ohne Sidebar und ohne Doku-Gliederung |
+| `layout: home` | Startseiten-Layout mit optional `hero` und `features` |
+| `draft: true` | Seite wird aus Build, Sitemap und Suche ausgeschlossen |
+
+Weitere Felder (`tags`, `sidebar: false`, `navbar: false`, …) stehen im README des npm-Pakets bzw. in der Referenz des Starters.
+
+## MDX-Seiten mit Komponenten
+
+Brauchst du interaktive UI, nutze `.mdx` statt `.md`:
+
+```mdx
+---
+title: Demo
+description: Interaktive Komponente
+---
+
+import Counter from './components/Counter.tsx'
+
+## Zähler
+
+<Counter initial={3} />
+```
+
+Komponenten importierst du relativ zur MDX-Datei. Überschriften `##` und `###` erscheinen in der Seitengliederung (bei `layout: doc`).
+
+Beispiel im Starter: [Interaktives MDX](/de/interactive).
+
+## In die Navigation einbinden
+
+Neue Seiten erscheinen **nicht automatisch** in der Kopfzeile oder Sidebar. Trage sie in `.preactpress/config.ts` ein:
+
+```ts
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Start', link: '/' },
+      { text: 'Kontakt', link: '/kontakt' }
+    ],
+    sidebar: [
+      {
+        text: 'Anleitung',
+        items: [
+          { text: 'Seiten erstellen', link: '/de/guide/seiten-erstellen' },
+          { text: 'Kontakt', link: '/kontakt' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Bei mehrsprachigen Sites (`locales`) gehören `nav` und `sidebar` in die jeweilige Locale-Konfiguration — siehe [Getting Started](/de/guide/getting-started).
+
+## Übersetzte Seite (Locale)
+
+Mit konfigurierten Locales legst du Übersetzungen in Sprachordnern ab:
+
+```text
+kontakt.md          → /kontakt
+de/kontakt.md       → /de/kontakt
+```
+
+Die deutsche Version ist eine **eigene Datei**, kein Alias der englischen Seite.
+
+## Entwürfe und Prüfung
+
+- **`draft: true`** im Frontmatter: Seite nur lokal sichtbar im Dev-Modus, nicht im Produktionsbuild.
+- **`pnpm run check`**: prüft fehlende Links, unbekannte Layouts, Route-Kollisionen und warnt bei Entwürfen ohne Beschreibung.
+
+## Typische Fehler
+
+| Problem | Lösung |
+| --- | --- |
+| Seite 404 | Dateiendung `.md` / `.mdx`? Liegt die Datei unter `srcDir`? Dev-Server läuft? |
+| Link in Markdown funktioniert nicht | Extension weglassen: `/guide/foo`, nicht `/guide/foo.md` |
+| Doppelte URL | Zwei Dateien dürfen nicht dieselbe Route erzeugen (z. B. `foo.md` und `foo/index.md`) |
+| Seite fehlt in der Navigation | `nav` / `sidebar` in der Config ergänzen |
+
+## Nächste Schritte
+
+| Thema | Link |
+| --- | --- |
+| Erste Änderungen in 5 Minuten | [Die ersten 5 Minuten](/de/guide/first-five-minutes) |
+| Routing, `srcDir`, Tags | [Routing](/de/guide/routing) |
+| Markdown-Syntax | [Markdown-Beispiele](/de/markdown-examples) |
+| Produktion bauen | [Deploy](/de/guide/deploy) |

package/templates/hono/de/guide/what-is-preactpress.md

@@ -0,0 +1,87 @@
+---
+title: Was ist PreactPress?
+description: Erfahre, was PreactPress ist und wann du es einsetzen kannst
+---
+
+# Was ist PreactPress?
+
+PreactPress ist ein Static-Site-Generator für schnelle, inhaltsorientierte Websites. Du schreibst Seiten in Markdown oder MDX, konfigurierst Navigation und Theme-Optionen in `.preactpress/config.ts`, und PreactPress erzeugt statisches HTML für beliebige Static Hosts.
+
+Es basiert auf [Vite](https://vite.dev/) und [Preact](https://preactjs.com/). Der Workflow ist von VitePress inspiriert, aber das Komponentenmodell ist Preact statt Vue.
+
+## Einsatzbereiche
+
+### Dokumentation
+
+PreactPress bringt ein kleines Standard-Theme für technische Dokumentation mit. Es enthält Navigation, Sidebar-Gruppen, Outline-Links, Suche, Last-Updated-Metadaten und Markdown-Rendering.
+
+Es passt besonders gut, wenn deine Dokumentation natürlich als Dateien wächst:
+
+```text
+index.md
+guide/getting-started.md
+guide/routing.md
+reference/api.md
+```
+
+Jede Markdown- oder MDX-Datei wird zu einer Seite. Neue Dokumentation entsteht also durch neue Dateien und Einträge in der Sidebar.
+
+### Blogs, Portfolios und Marketing-Seiten
+
+PreactPress kann auch Blogs, Portfolios und kleine Marketing-Seiten erzeugen. Markdown trägt den Inhalt, MDX bringt interaktive Preact-Komponenten hinein, und eigene Themes ersetzen bei Bedarf das Standard-Doku-Layout.
+
+Im separaten Projekt `preactpress-examples` gibt es ein Custom-Theme-Beispiel mit Magazin-Layout, Artikel-Teasern und Tag-Seiten.
+
+## Developer Experience
+
+PreactPress soll Content-Arbeit einfach halten:
+
+| Feature | Nutzen |
+| --- | --- |
+| Vite Dev-Server | Schneller Start und Hot Updates beim Bearbeiten |
+| Markdown-Frontmatter | Titel, Beschreibungen, Tags, Draft-Status und Social-Metadaten |
+| MDX | Preact-Komponenten direkt in Inhaltsseiten |
+| Standard-Theme | Nav, Sidebar, Outline, Suche, Footer, Sprachumschalter |
+| `preactpress check` | Validierung von Config, Routen und Links vor dem Release |
+
+Für normale Inhalte nimmst du `.md`. Wenn eine Seite Interaktivität braucht, nimmst du `.mdx` und importierst eine Preact-Komponente:
+
+```mdx
+import Counter from './components/Counter.tsx'
+
+## Demo
+
+<Counter initial={3} />
+```
+
+## Performance
+
+PreactPress erzeugt beim Produktionsbuild statisches HTML für jede Route. Der erste Besuch erhält also HTML, das den Seiteninhalt bereits enthält. Das ist gut für Ladezeit und SEO.
+
+Nach der Hydration übernimmt die Client-Navigation. Markdown-Seiten werden als kleine JSON-Payloads aus `preactpress-content/*.json` geladen, sodass große Sites nicht jeden Markdown-Body im ersten JavaScript-Bundle ausliefern müssen.
+
+Der Produktionsbuild besteht nur aus statischen Dateien:
+
+| Ausgabe | Zweck |
+| --- | --- |
+| `index.html`, `*/index.html` | Eine HTML-Datei pro Route |
+| `assets/*` | Gehashtes JavaScript und CSS von Vite |
+| `preactpress-search.json` | Suchdaten für das Standard-Theme |
+| `preactpress-content/*.json` | Lazy geladene Markdown-Payloads |
+| `404.html` | Fehlerseite |
+
+## Was ist mit VitePress?
+
+Wenn du VitePress kennst, wird sich PreactPress vertraut anfühlen: Beide nutzen Vite, dateibasierte Markdown-Routen, ein Standard-Doku-Theme und statischen Output.
+
+Der wichtigste Unterschied ist der UI-Stack. VitePress nutzt Vue. PreactPress nutzt Preact und MDX, daher werden interaktive Inhalte und eigene Themes als Preact-Komponenten geschrieben.
+
+PreactPress ist in Produktion außerdem static-only. Du baust die Site einmal, lädst das Ausgabeverzeichnis hoch und hostest es auf Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3, Nginx oder einem anderen Static Host.
+
+## Nächste Schritte
+
+| Seite | Warum |
+| --- | --- |
+| [Getting Started](/de/guide/getting-started) | PreactPress installieren und die Starter-Struktur verstehen |
+| [Routing](/de/guide/routing) | Lernen, wie Dateien zu URLs werden |
+| [Deploy](/de/guide/deploy) | Eine statische Site bauen und veröffentlichen |

package/templates/hono/de/index.mdx

@@ -0,0 +1,51 @@
+---
+title: Schnell, schlank, auf Web-Standards gebaut
+description: Ein von hono.dev inspiriertes Starter-Template für Dokumentation und Produktseiten mit PreactPress.
+---
+
+import FeatureGrid from '../.preactpress/theme/FeatureGrid.tsx'
+import Hero from '../.preactpress/theme/Hero.tsx'
+
+<Hero
+  eyebrow="Hono-inspirierter Starter"
+  title="Schnell, schlank, auf Web-Standards gebaut."
+  subtitle="Nutze dieses Template für hochwertige Dokumentation, Beispiele und Produktseiten mit einem kompakten Preact-Theme."
+  actions={[
+    { text: 'Loslegen', link: '/de/guide/getting-started', theme: 'brand' },
+    { text: 'Auf GitHub ansehen', link: 'https://github.com/your-org/your-project', theme: 'alt' }
+  ]}
+  code={`import { App } from 'your-framework'
+
+const app = new App()
+
+app.get('/', (c) => {
+  return c.text('Hallo Web-Standards!')
+})
+
+export default app`}
+/>
+
+<FeatureGrid
+  features={[
+    {
+      icon: 'F',
+      title: 'Ultraschnell & leichtgewichtig',
+      details: 'Statisches HTML, wenig Client-Code und ein Theme, das deine Docs responsiv hält.'
+    },
+    {
+      icon: 'R',
+      title: 'Für viele Runtimes gedacht',
+      details: 'Schreibe portable Beispiele für Node, Bun, Deno, Edge Workers und statisches Hosting.'
+    },
+    {
+      icon: 'B',
+      title: 'Batterien inklusive',
+      details: 'Navigation, Sidebar-Suche, MDX, Tags, i18n und statische Builds sind direkt startklar.'
+    },
+    {
+      icon: 'D',
+      title: 'Angenehme DX',
+      details: 'Markdown-first Content, Vite-Geschwindigkeit und editierbare Preact-Komponenten für Custom Pages.'
+    }
+  ]}
+/>

package/templates/hono/de/interactive.mdx

@@ -0,0 +1,32 @@
+---
+title: Interaktives MDX
+description: Markdown mit importierten Preact-Komponenten
+---
+
+import Counter from '../components/Counter.tsx'
+
+## Preact-Komponente
+
+MDX-Seiten können lokale Preact-Komponenten importieren und direkt rendern.
+
+<Counter initial={3} />
+
+## Bild
+
+Markdown-Bilder funktionieren wie in `.md`-Seiten:
+
+![Beispielfoto von Lorem Picsum](https://picsum.photos/id/10/800/450)
+
+## YouTube
+
+Einbetten mit einem normalen JSX-`iframe` (ersetze die Video-ID durch deine eigene):
+
+<iframe
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/aqz-KE-bpKQ"
+  title="YouTube-Video-Beispiel"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowFullScreen
+/>

package/templates/hono/de/markdown-examples.md

@@ -0,0 +1,142 @@
+---
+title: Markdown-Beispiele
+description: Häufige Authoring-Snippets
+tags:
+  - markdown
+---
+
+## Code
+
+```ts{2}
+export function greet(name: string) {
+  return `Hallo, ${name}!`
+}
+```
+
+Einzelne Zeilen kannst du per Fence-Meta (`{2}`) oder Inline-Notation markieren:
+
+```ts
+export function greet(name: string) {
+  return `Hallo, ${name}!` // [!code highlight]
+}
+```
+
+Inline-Code wie `themeConfig.outline` verwendet dieselben Theme-Tokens wie Codeblöcke.
+
+## Snippet-Import
+
+Wiederverwende Quelldateien statt Code zu duplizieren:
+
+<<< @/snippets/greet.ts{2}
+
+Das `@/`-Präfix wird relativ zum Content-Root (`srcDir`) aufgelöst.
+
+## Links
+
+[Start](/de) · [Externer Link](https://preactjs.com)
+
+## Tabellen
+
+| Syntax | Ergebnis |
+| --- | --- |
+| `# Titel` | Überschrift |
+| `---` Frontmatter | Seitenmetadaten |
+
+## Zitate
+
+> Nutze Blockquotes für Callouts, Hinweise oder kurze Kontextinformationen.
+
+## Container
+
+::: tip
+`::: tip`, `::: warning`, `::: danger`, `::: info` und `::: details` funktionieren wie bei VitePress.
+:::
+
+::: warning Eigener Titel
+Optional kannst du nach dem Typ einen eigenen Titel angeben.
+:::
+
+## GFM-Alerts
+
+GitHub-Alert-Syntax wird wie die Custom Container gerendert:
+
+> [!NOTE]
+> Nützliche Informationen für Leserinnen und Leser.
+
+> [!TIP]
+> Optionale Tipps für bessere Ergebnisse.
+
+> [!WARNING]
+> Kritische Inhalte, die sofortige Aufmerksamkeit brauchen.
+
+## Heading-IDs
+
+## Eigene Anker {#eigener-anker}
+
+Mit `{#deine-id}` steuerst du die Fragment-URL.
+
+## Inline-Inhaltsverzeichnis
+
+[[toc]]
+
+### Erster Abschnitt
+
+Inhalt des ersten Abschnitts.
+
+### Zweiter Abschnitt
+
+Inhalt des zweiten Abschnitts.
+
+## Code-Gruppen
+
+::: code-group
+
+```bash [npm]
+npm install
+```
+
+```bash [pnpm]
+pnpm install
+```
+
+:::
+
+## Eigene Heading-IDs
+
+## Stabile Links {#stabile-id}
+
+Hänge `{#id}` an eine Überschrift, um den Anker zu steuern.
+
+## Emoji
+
+`:tada:` und `:rocket:` funktionieren standardmäßig.
+
+## Inline-Inhaltsverzeichnis
+
+[[toc]]
+
+## Zweiter Abschnitt
+
+Inhalt unter dem inline TOC.
+
+### Unterabschnitt
+
+Verschachtelte Überschrift für die Gliederung.
+
+## Code-Gruppen
+
+::: code-group
+
+```js [config.js]
+export default { lang: 'js' }
+```
+
+```ts [config.ts]
+export default { lang: 'ts' }
+```
+
+:::
+
+## Markdown-Inclusion
+
+<!--@include: @/parts/include-body.md{5,6}-->