@kamod-ch/preactpress 1.0.0

package/templates/hono/dist/preactpress-search.json

@@ -0,0 +1,242 @@
+[
+  {
+    "route": "/",
+    "locale": "root",
+    "title": "Fast, lightweight, built on Web Standards",
+    "description": "A Hono-inspired starter for documentation and product sites built with PreactPress.",
+    "excerpt": "A Hono-inspired starter for documentation and product sites built with PreactPress.",
+    "tags": []
+  },
+  {
+    "route": "/README",
+    "locale": "root",
+    "excerpt": "PreactPress Hono-style starter site # This folder was scaffolded with preactpress init --template hono . It combines a hono.dev-inspired landing page with…",
+    "tags": []
+  },
+  {
+    "route": "/about",
+    "locale": "root",
+    "title": "About",
+    "description": "About this site",
+    "excerpt": "About us # Your content here. This page was added as part of the Your first 5 minutes tutorial. Replace this text with your own copy — team bio, project…",
+    "tags": []
+  },
+  {
+    "route": "/de",
+    "locale": "de",
+    "title": "Schnell, schlank, auf Web-Standards gebaut",
+    "description": "Ein von hono.dev inspiriertes Starter-Template für Dokumentation und Produktseiten mit PreactPress.",
+    "excerpt": "Ein von hono.dev inspiriertes Starter-Template für Dokumentation und Produktseiten mit PreactPress.",
+    "tags": []
+  },
+  {
+    "route": "/de/about",
+    "locale": "de",
+    "title": "Über uns",
+    "description": "Über diese Website",
+    "excerpt": "Über uns # Hier steht dein Inhalt. Diese Seite wurde im Tutorial Die ersten 5 Minuten hinzugefügt. Ersetze diesen Text durch deine eigenen Inhalte —…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/commands",
+    "locale": "de",
+    "title": "Befehle",
+    "description": "PreactPress-CLI für Entwicklung und Produktions-Builds",
+    "excerpt": "Die PreactPress-CLI wird im Site-Root ausgeführt (Ordner mit .preactpress/config.ts ). Entwicklung # pnpm exec preactpress dev Startet Vite mit SSR, Hot…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/configuration",
+    "locale": "de",
+    "title": "Konfiguration",
+    "description": "Site-Config, Theme-Optionen und häufige Frontmatter-Felder",
+    "excerpt": "Die Konfiguration liegt in .preactpress/config.ts im Site-Root. Site-Metadaten # export default { site: { title: 'Meine Docs' , description:…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/deploy",
+    "locale": "de",
+    "title": "Deploy",
+    "description": "Eine PreactPress-Site bauen und veröffentlichen",
+    "excerpt": "Deploy # PreactPress erzeugt statische Dateien. Produktion bedeutet: Build ausführen und das Ausgabeverzeichnis, normalerweise dist/ , auf einen Static…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/first-five-minutes",
+    "locale": "de",
+    "title": "Die ersten 5 Minuten",
+    "description": "Seitentitel ändern, eine Seite hinzufügen und die Navigation aktualisieren",
+    "excerpt": "Die ersten 5 Minuten # Dieses praktische Tutorial folgt der Setup-Übersicht in Getting Started . Folge den Schritten in deinem Projekt — diese Website…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/getting-started",
+    "locale": "de",
+    "title": "Getting Started",
+    "description": "PreactPress installieren und eine neue Dokumentationsseite starten",
+    "excerpt": "Getting Started # Diese Anleitung zeigt, wie du eine PreactPress-Site erstellst, die generierten Dateien verstehst und den Dev-Server startest.…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/routing",
+    "locale": "de",
+    "title": "Routing",
+    "description": "Verstehe, wie PreactPress Dateien auf URLs abbildet",
+    "excerpt": "Routing # PreactPress nutzt dateibasiertes Routing. Jede .md - und .mdx -Datei unter srcDir wird zu einer Route, und Produktionsbuilds schreiben jede…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/seiten-erstellen",
+    "locale": "de",
+    "title": "Seiten erstellen",
+    "description": "Neue Markdown- und MDX-Seiten anlegen, URLs verstehen und in die Navigation einbinden",
+    "excerpt": "Seiten erstellen # In PreactPress entstehen Seiten aus Dateien — es gibt keinen separaten Seiten-Editor oder CMS. Jede .md - oder .mdx -Datei unter dem…",
+    "tags": []
+  },
+  {
+    "route": "/de/guide/what-is-preactpress",
+    "locale": "de",
+    "title": "Was ist PreactPress?",
+    "description": "Erfahre, was PreactPress ist und wann du es einsetzen kannst",
+    "excerpt": "Was ist PreactPress? # PreactPress ist ein Static-Site-Generator für schnelle, inhaltsorientierte Websites. Du schreibst Seiten in Markdown oder MDX,…",
+    "tags": []
+  },
+  {
+    "route": "/de/interactive",
+    "locale": "de",
+    "title": "Interaktives MDX",
+    "description": "Markdown mit importierten Preact-Komponenten",
+    "excerpt": "Markdown mit importierten Preact-Komponenten",
+    "tags": []
+  },
+  {
+    "route": "/de/markdown-examples",
+    "locale": "de",
+    "title": "Markdown-Beispiele",
+    "description": "Häufige Authoring-Snippets",
+    "excerpt": "Code # export function greet ( name : string ) { return `Hallo, ${ name }!` } Einzelne Zeilen kannst du per Fence-Meta ( {2} ) oder Inline-Notation…",
+    "tags": [
+      "markdown"
+    ]
+  },
+  {
+    "route": "/de/parts/include-body",
+    "locale": "de",
+    "excerpt": "Zeile eins — übersprungen. Zeile zwei — übersprungen. Zeile drei — übersprungen. Zeile vier — übersprungen. Eingebetteter Inhalt # Dieser Absatz wird per…",
+    "tags": []
+  },
+  {
+    "route": "/de/tags/markdown",
+    "locale": "de",
+    "title": "Tag: markdown",
+    "description": "Pages tagged “markdown”",
+    "excerpt": "Pages tagged: markdown 1 page(s). Markdown-Beispiele",
+    "tags": [
+      "markdown"
+    ]
+  },
+  {
+    "route": "/guide/commands",
+    "locale": "root",
+    "title": "Commands",
+    "description": "PreactPress CLI reference for local development and production builds",
+    "excerpt": "PreactPress ships a small CLI. Run commands from your site root (where .preactpress/config.ts lives). Development # pnpm exec preactpress dev Starts Vite…",
+    "tags": []
+  },
+  {
+    "route": "/guide/configuration",
+    "locale": "root",
+    "title": "Configuration",
+    "description": "Site config, theme options, and common frontmatter fields",
+    "excerpt": "Configuration lives in .preactpress/config.ts at your site root. Site metadata # export default { site: { title: 'My docs' , description: 'Short site…",
+    "tags": []
+  },
+  {
+    "route": "/guide/creating-pages",
+    "locale": "root",
+    "title": "Creating pages",
+    "description": "Add new Markdown and MDX pages, understand URLs, and wire them into navigation",
+    "excerpt": "Creating pages # PreactPress builds pages from files — there is no separate page editor or CMS. Every .md or .mdx file under the source directory ( srcDir…",
+    "tags": []
+  },
+  {
+    "route": "/guide/deploy",
+    "locale": "root",
+    "title": "Deploy",
+    "description": "Build and publish a PreactPress site",
+    "excerpt": "Deploy # PreactPress builds static files. Production deployment means running a build and uploading the output directory, usually dist/ , to a static…",
+    "tags": []
+  },
+  {
+    "route": "/guide/first-five-minutes",
+    "locale": "root",
+    "title": "Your first 5 minutes",
+    "description": "Change the site title, add a page, and update navigation",
+    "excerpt": "Your first 5 minutes # This hands-on tutorial follows the setup overview in Getting Started . Follow the steps below in your project — this site is the…",
+    "tags": []
+  },
+  {
+    "route": "/guide/getting-started",
+    "locale": "root",
+    "title": "Getting Started",
+    "description": "Install PreactPress and start a new documentation site",
+    "excerpt": "Getting Started # This guide shows how to create a PreactPress site, understand the generated files, and start the development server. Prerequisites # You…",
+    "tags": []
+  },
+  {
+    "route": "/guide/routing",
+    "locale": "root",
+    "title": "Routing",
+    "description": "Understand how PreactPress maps files to URLs",
+    "excerpt": "Routing # PreactPress uses file-based routing. Every .md and .mdx file under srcDir becomes a route, and production builds write each route as static…",
+    "tags": []
+  },
+  {
+    "route": "/guide/what-is-preactpress",
+    "locale": "root",
+    "title": "What is PreactPress?",
+    "description": "Learn what PreactPress is and when to use it",
+    "excerpt": "What is PreactPress? # PreactPress is a static site generator for fast, content-focused websites. You write pages in Markdown or MDX, configure navigation…",
+    "tags": []
+  },
+  {
+    "route": "/interactive",
+    "locale": "root",
+    "title": "Interactive MDX",
+    "description": "Markdown with imported Preact components",
+    "excerpt": "Markdown with imported Preact components",
+    "tags": []
+  },
+  {
+    "route": "/markdown-examples",
+    "locale": "root",
+    "title": "Markdown examples",
+    "description": "Common authoring snippets",
+    "excerpt": "Code # export function greet ( name : string ) { return `Hello, ${ name }!` } Highlight a single line with fence meta ( {2} ) or inline notation: export…",
+    "tags": [
+      "markdown"
+    ]
+  },
+  {
+    "route": "/partials/shared-note",
+    "locale": "root",
+    "excerpt": "Shared fragment This note is pulled in via ::: tip Shared fragment This note is pulled in via !-- include cycle detected:…",
+    "tags": []
+  },
+  {
+    "route": "/parts/include-body",
+    "locale": "root",
+    "excerpt": "Line one — skipped. Line two — skipped. Line three — skipped. Line four — skipped. Included body # This paragraph is pulled in via !-- include not found:…",
+    "tags": []
+  },
+  {
+    "route": "/tags/markdown",
+    "locale": "root",
+    "title": "Tag: markdown",
+    "description": "Pages tagged “markdown”",
+    "excerpt": "Pages tagged: markdown 1 page(s). Markdown examples",
+    "tags": [
+      "markdown"
+    ]
+  }
+]

package/templates/hono/dist/preactpress-theme.js

@@ -0,0 +1 @@
+(function(){try{var k="preactpress-theme";var m=localStorage.getItem(k);if(m==='light'||m==='dark')document.documentElement.setAttribute('data-theme',m);}catch(e){}})();

package/templates/hono/dist/tags/markdown/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Tag: markdown | Hono Starter</title>
+    <script src="/preactpress-theme.js"></script>
+    <meta name="description" content="Pages tagged “markdown”">
+    <meta property="article:tag" content="markdown">
+    <meta property="og:title" content="Tag: markdown | Hono Starter">
+    <meta property="og:description" content="Pages tagged “markdown”">
+    <meta property="og:type" content="website">
+    <meta property="og:url" content="/tags/markdown/">
+    <meta name="twitter:card" content="summary">
+    <meta name="twitter:title" content="Tag: markdown | Hono Starter">
+    <meta name="twitter:description" content="Pages tagged “markdown”">
+    <link rel="canonical" href="/tags/markdown/">
+    <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","headline":"Tag: markdown | Hono Starter","name":"Tag: markdown | Hono Starter","description":"Pages tagged “markdown”","url":"/tags/markdown/"}</script>
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="icon" href="/favicon-32.png" type="image/png" sizes="32x32">
+    <link rel="icon" href="/favicon.png" type="image/png" sizes="any">
+    <link rel="apple-touch-icon" href="/favicon.png">
+    <link rel="stylesheet" crossorigin href="/assets/main-DIIN7FO0.css">
+  </head>
+  <body>
+    <template id="__PREACTPRESS_PAGE_DATA__">{&quot;kind&quot;:&quot;markdown&quot;,&quot;meta&quot;:{&quot;tagIndex&quot;:true,&quot;tag&quot;:&quot;markdown&quot;,&quot;tagSlug&quot;:&quot;markdown&quot;},&quot;html&quot;:&quot;\u003carticle class=\&quot;pp-tag-index\&quot;&gt;\u003ch1 class=\&quot;pp-heading\&quot; id=\&quot;tag-markdown\&quot;&gt;Pages tagged: markdown\u003c/h1&gt;\u003cp class=\&quot;pp-tag-index-count\&quot;&gt;1 page(s).\u003c/p&gt;\u003cul class=\&quot;pp-tag-index-list\&quot;&gt;\n  \u003cli&gt;\u003ca href=\&quot;/markdown-examples\&quot;&gt;Markdown examples\u003c/a&gt;\u003c/li&gt;\n\u003c/ul&gt;\u003c/article&gt;&quot;,&quot;title&quot;:&quot;Tag: markdown&quot;,&quot;description&quot;:&quot;Pages tagged “markdown”&quot;,&quot;tags&quot;:[&quot;markdown&quot;],&quot;pageType&quot;:&quot;website&quot;,&quot;headings&quot;:[]}</template>
+    <div id="app"><div class="hn-site"><a class="hn-skip" href="#content">Skip to content</a><header class="hn-header"><div class="hn-header-inner"><a class="hn-brand" href="/" aria-label="Hono Starter"><span class="hn-logo" aria-label="Hono Starter"><svg aria-hidden="true" viewBox="0 0 36 36" width="36" height="36"><rect width="36" height="36" rx="11" fill="currentColor" opacity="0.12"></rect><path d="M19.8 5.5c.8 4-2.8 5.9-4.7 8.2-1.8 2.1-2.5 4.9-.3 7 0-2.8 1.7-4.6 4.2-6.7 3.2 3 5.3 5.8 5.3 9.2 0 4.4-3.3 7.3-7.6 7.3-4.8 0-8.3-3.6-8.3-8.4 0-6.1 6.3-9.2 11.4-16.6Z" fill="currentColor"></path><path d="M21.7 25.7c0 2.2-1.7 3.8-3.9 3.8s-4-1.6-4-3.8c0-1.7 1-3.1 3.4-5.2.1 1.7 1.4 2.6 2.4 3.4.8.6 2.1 1 2.1 1.8Z" fill="currentColor" opacity="0.38"></path></svg><span>Hono Starter</span></span></a><div class="hn-header-actions"><nav class="hn-nav" aria-label="Main navigation"><a class href="/guide/what-is-preactpress">Docs</a><a class href="/markdown-examples">Examples</a><a class href="/about">About</a></nav><div class="hn-social" aria-label="Social links"><a href="https://github.com/your-org/your-project" aria-label="GitHub"><span><svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>GitHub</title><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.404 1.02.005 2.04.137 3 .404 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></span></a></div><details class="hn-locale-switcher"><summary>English</summary><div class="hn-locale-menu"><a href="/tags/markdown" aria-current="page" class="active">English</a><a href="/de/tags/markdown" class>Deutsch</a></div></details><button type="button" class="hn-theme-toggle" aria-label="Toggle theme"><span class="hn-theme-toggle-moon" aria-hidden="true"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"><path d="M21 14.8A8.5 8.5 0 0 1 9.2 3a7 7 0 1 0 11.8 11.8Z" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.7"></path></svg></span><span class="hn-theme-toggle-sun" aria-hidden="true"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="3.5" stroke-width="1.7"></circle><path d="M12 2.5v2M12 19.5v2M4.6 4.6 6 6M18 18l1.4 1.4M2.5 12h2M19.5 12h2M4.6 19.4 6 18M18 6l1.4-1.4" stroke-linecap="round" stroke-width="1.7"></path></svg></span></button></div></div></header><div class="hn-doc-shell"><aside class="hn-sidebar" aria-label="Documentation navigation"><div class="hn-sidebar-panel"><label class="hn-search"><span>Search pages</span><input type="search" value placeholder="Filter documentation..."/></label><div class="hn-sidebar-group"><h2>Introduction</h2><ul><li><a class href="/">Welcome</a></li><li><a class href="/guide/what-is-preactpress">What is PreactPress?</a></li><li><a class href="/guide/getting-started">Getting Started</a></li><li><a class href="/guide/routing">Routing</a></li><li><a class href="/guide/deploy">Deploy</a></li><li><a class href="/guide/first-five-minutes">Your first 5 minutes</a></li><li><a class href="/guide/creating-pages">Creating pages</a></li><li><a class href="/guide/commands">Commands</a></li><li><a class href="/guide/configuration">Configuration</a></li></ul></div><div class="hn-sidebar-group"><h2>Reference</h2><ul><li><a class href="/markdown-examples">Markdown examples</a></li><li><a class href="/interactive">Interactive MDX</a></li></ul></div></div></aside><main id="content" class="hn-doc-main"><article class="hn-doc"><h1 class="hn-doc-title">Tag: markdown</h1><p class="hn-doc-lead">Pages tagged “markdown”</p><div class="hn-doc-content"><article class="pp-tag-index"><h1 class="pp-heading" id="tag-markdown">Pages tagged: markdown</h1><p class="pp-tag-index-count">1 page(s).</p><ul class="pp-tag-index-list">
+  <li><a href="/markdown-examples">Markdown examples</a></li>
+</ul></article></div><footer class="hn-doc-meta"></footer></article></main></div><footer class="hn-footer">Built with PreactPress.</footer></div></div>
+    <script type="module" crossorigin src="/assets/main-Bqi-VFEk.js"></script>
+  </body>
+</html>

package/templates/hono/guide/commands.md

@@ -0,0 +1,44 @@
+---
+title: Commands
+description: PreactPress CLI reference for local development and production builds
+---
+
+PreactPress ships a small CLI. Run commands from your site root (where `.preactpress/config.ts` lives).
+
+## Development
+
+```bash
+pnpm exec preactpress dev
+```
+
+Starts Vite with SSR, hot reload, and the same HTML head shape as production.
+
+## Production
+
+```bash
+pnpm exec preactpress build
+pnpm exec preactpress preview
+```
+
+`build` writes static HTML to `outDir` (default `dist/`). `preview` serves that folder locally — not for production hosting.
+
+## Project setup
+
+```bash
+pnpm exec preactpress init
+pnpm exec preactpress init --template docs
+```
+
+Scaffolds a new site. The `docs` template includes this guide, i18n examples, and reference pages.
+
+## Validation
+
+```bash
+pnpm exec preactpress check
+```
+
+Validates config, route collisions, nav/sidebar links, internal Markdown links, and draft pages before you deploy.
+
+::: tip
+Add `check` to CI so broken sidebar links fail the pipeline before merge.
+:::

package/templates/hono/guide/configuration.md

@@ -0,0 +1,177 @@
+---
+title: Configuration
+description: Site config, theme options, and common frontmatter fields
+---
+
+Configuration lives in `.preactpress/config.ts` at your site root.
+
+## Site metadata
+
+```ts
+export default {
+  site: {
+    title: 'My docs',
+    description: 'Short site summary for SEO',
+    base: '/',
+    url: 'https://example.com',
+    titleTemplate: ':title | :siteTitle'
+  }
+}
+```
+
+Set `site.url` before production so canonical URLs, `sitemap.xml`, Open Graph, and `hreflang` alternates resolve correctly.
+
+## Content directory
+
+| Option | Purpose |
+| --- | --- |
+| `srcDir` | Folder with `.md` / `.mdx` pages (default `.`) |
+| `srcExclude` | Glob patterns for non-page Markdown, e.g. `['**/README.md']` |
+| `lastUpdatedGit` | Use git commit time for “last updated” (falls back to file mtime) |
+
+## Theme without custom code
+
+`themeConfig` drives the default layout:
+
+- `nav` — top links; supports nested dropdowns via `items`
+- `sidebar` — flat array **or** path map: `{ '/guide/': [...], '/reference/': [...] }`; groups and items support `collapsed` and nested `items`
+- `outline`, `search`, `socialLinks`, `footer`, `lastUpdated`, `editLink`, `logo`, `labels`
+- `logo` — string URL or `{ light, dark }` for theme-aware images
+- `search` — `true` or `{ provider: 'local' }` for sidebar search; `{ provider: 'algolia', options }` for Algolia DocSearch in the nav bar
+- `socialLinks` — `{ icon, link, ariaLabel? }[]` with built-in icons (`github`, `discord`, `x`, …) or custom `{ svg }`
+
+Per-locale overrides go under `locales.<key>.themeConfig`.
+
+Example nested nav and sidebar:
+
+```ts
+themeConfig: {
+  logo: { light: '/logo-light.svg', dark: '/logo-dark.svg' },
+  labels: { search: 'Find pages' },
+  nav: [
+    { text: 'Guide', items: [{ text: 'Intro', link: '/guide/intro' }] },
+    { text: 'Blog', link: '/blog' }
+  ],
+  sidebar: [
+    {
+      text: 'Guide',
+      collapsed: false,
+      items: [
+        { text: 'Intro', link: '/guide/intro' },
+        {
+          text: 'Advanced',
+          collapsed: true,
+          items: [{ text: 'API', link: '/guide/api' }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Search providers
+
+Local search (default when `search: true`) filters the sidebar and loads `preactpress-search.json` at build time.
+
+Algolia DocSearch mounts a search button in the nav bar:
+
+```ts
+themeConfig: {
+  search: {
+    provider: 'algolia',
+    options: {
+      appId: 'YOUR_APP_ID',
+      apiKey: 'YOUR_SEARCH_API_KEY',
+      indexName: 'YOUR_INDEX_NAME',
+      locales: {
+        de: { indexName: 'YOUR_DE_INDEX' }
+      }
+    }
+  }
+}
+```
+
+### Social links
+
+```ts
+themeConfig: {
+  socialLinks: [
+    { icon: 'github', link: 'https://github.com/your-org/your-repo' },
+    { icon: { svg: '<svg ...></svg>' }, link: 'https://example.com', ariaLabel: 'Company site' }
+  ]
+}
+```
+
+## Global head tags
+
+```ts
+head: [
+  ['meta', { name: 'theme-color', content: '#0f766e' }]
+],
+async transformHead({ route, title, tags, site }) {
+  return [['meta', { name: 'pp-route', content: route }]]
+}
+```
+
+## Build hooks
+
+Hooks run during `dev` and `build` unless noted otherwise.
+
+```ts
+async transformPageData(page, { route, site }) {
+  if (page.kind !== 'markdown') return page
+  return {
+    ...page,
+    meta: { ...page.meta, sourceRoute: route }
+  }
+},
+
+async transformHtml(html, { route }) {
+  return html.replace('</body>', `<!-- built:${route} --></body>`)
+},
+
+async buildEnd({ site, pages }) {
+  console.log(`Built ${pages.length} pages to ${site.outDir}`)
+}
+```
+
+### Async config
+
+Export a factory to load nav or sidebar from an API at config time:
+
+```ts
+import { defineConfig } from '@kamod-ch/preactpress/config'
+
+export default defineConfig(async () => ({
+  site: { title: 'My docs', description: 'Docs from CMS' },
+  themeConfig: {
+    nav: await fetchNav(),
+    sidebar: await fetchSidebar()
+  }
+}))
+```
+
+## Page frontmatter
+
+| Field | Purpose |
+| --- | --- |
+| `title` / `description` | Page title and SEO summary |
+| `titleTemplate` | Override site template; `false` uses the raw page title |
+| `head` | Extra `<meta>` / `<link>` / `<script>` tags for this page only |
+| `draft: true` | Excluded from routes, search, and sitemap |
+
+Example per-page head:
+
+```yaml
+---
+title: About
+head:
+  - - meta
+    - name: author
+      content: Your Name
+---
+```
+
+::: warning
+Enable `markdown.html` only for trusted authors — it allows raw HTML in Markdown.
+:::

package/templates/hono/guide/creating-pages.md

@@ -0,0 +1,171 @@
+---
+title: Creating pages
+description: Add new Markdown and MDX pages, understand URLs, and wire them into navigation
+---
+
+# Creating pages
+
+PreactPress builds pages from files — there is no separate page editor or CMS. Every `.md` or `.mdx` file under the source directory (`srcDir`, default: project root) automatically becomes a public URL.
+
+## Quick overview
+
+1. Create a new file (e.g. `contact.md` or `guide/new-page.md`).
+2. Optionally add frontmatter with `title`, `description`, and `layout`.
+3. Write content in Markdown or MDX.
+4. The dev server picks up changes automatically — no restart required.
+5. Optionally add entries to `nav` and `sidebar` in `.preactpress/config.ts`.
+
+## Step by step: a simple page
+
+Create a Markdown file in the project root (or under `srcDir`), for example `contact.md`:
+
+```md
+---
+title: Contact
+description: How to reach us
+layout: page
+---
+
+# Contact
+
+Email us at **hello@example.com**.
+```
+
+Save the file — with `pnpm run dev` running, the page is immediately available at **/contact**.
+
+> **Note**
+> The file name (without extension) determines the URL path. `contact.md` → `/contact`, not `/contact.md`.
+
+## File location → URL
+
+PreactPress uses **file-based routing**. The path relative to `srcDir` becomes the route:
+
+| File | URL |
+| --- | --- |
+| `index.md` | `/` |
+| `about.md` | `/about` |
+| `guide/intro.md` | `/guide/intro` |
+| `guide/index.md` | `/guide` |
+| `news/2025/intro.md` | `/news/2025/intro` |
+| `interactive.mdx` | `/interactive` |
+
+Production builds write directory indexes (`dist/about/index.html`) so URLs work without `.html`.
+
+More detail: [Routing](/guide/routing).
+
+## Source directory (`srcDir`)
+
+By default, Markdown files live in the project root next to `.preactpress/`. You can move content into a subfolder:
+
+```ts
+// .preactpress/config.ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+Then all pages live under `docs/` — e.g. `docs/index.md` → `/`, `docs/guide/foo.md` → `/guide/foo`. URLs stay the same; only the file location changes.
+
+## Frontmatter (optional but recommended)
+
+YAML at the top of the file controls metadata and layout:
+
+```md
+---
+title: My page
+description: Short summary for search, SEO, and social previews
+layout: doc
+---
+```
+
+| Field | Purpose |
+| --- | --- |
+| `title` | Page title (nav, `<title>`, search) |
+| `description` | Summary for SEO and search |
+| `layout: doc` | Docs layout with sidebar, outline, and previous/next links |
+| `layout: page` | Content page without sidebar or doc outline |
+| `layout: home` | Home layout with optional `hero` and `features` |
+| `draft: true` | Excluded from build, sitemap, and search |
+
+Additional fields (`tags`, `sidebar: false`, `navbar: false`, …) are documented in the package README and starter reference.
+
+## MDX pages with components
+
+When you need interactive UI, use `.mdx` instead of `.md`:
+
+```mdx
+---
+title: Demo
+description: Interactive component
+---
+
+import Counter from './components/Counter.tsx'
+
+## Counter
+
+<Counter initial={3} />
+```
+
+Import components relative to the MDX file. `##` and `###` headings feed the on-page outline (with `layout: doc`).
+
+Example in this starter: [Interactive MDX](/interactive).
+
+## Add to navigation
+
+New pages do **not** appear in the header or sidebar automatically. Register them in `.preactpress/config.ts`:
+
+```ts
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Contact', link: '/contact' }
+    ],
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Creating pages', link: '/guide/creating-pages' },
+          { text: 'Contact', link: '/contact' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+For multilingual sites (`locales`), put `nav` and `sidebar` in each locale block — see [Getting Started](/guide/getting-started).
+
+## Translated page (locale)
+
+With locales configured, add translations in language folders:
+
+```text
+contact.md       -> /contact
+de/contact.md    -> /de/contact
+```
+
+Each locale is a **separate file**, not an alias of the default page.
+
+## Drafts and validation
+
+- **`draft: true`** in frontmatter: visible in dev only, excluded from production builds.
+- **`pnpm run check`**: validates missing links, unknown layouts, route collisions, and warns on drafts without descriptions.
+
+## Common issues
+
+| Problem | Fix |
+| --- | --- |
+| Page returns 404 | `.md` / `.mdx` extension? File under `srcDir`? Dev server running? |
+| Markdown link broken | Omit extension: `/guide/foo`, not `/guide/foo.md` |
+| Duplicate URL | Two files must not map to the same route (e.g. `foo.md` and `foo/index.md`) |
+| Page missing from nav | Add to `nav` / `sidebar` in config |
+
+## Next steps
+
+| Topic | Link |
+| --- | --- |
+| First changes in 5 minutes | [Your first 5 minutes](/guide/first-five-minutes) |
+| Routing, `srcDir`, tags | [Routing](/guide/routing) |
+| Markdown syntax | [Markdown examples](/markdown-examples) |
+| Production build | [Deploy](/guide/deploy) |