@kamod-ch/preactpress 1.0.0

package/templates/hono/guide/deploy.md

@@ -0,0 +1,197 @@
+---
+title: Deploy
+description: Build and publish a PreactPress site
+---
+
+# Deploy
+
+PreactPress builds static files. Production deployment means running a build and uploading the output directory, usually `dist/`, to a static host.
+
+No Node server is required in production.
+
+## Build and test locally
+
+Run the release checks and production build from your site directory:
+
+```bash
+pnpm run check
+pnpm run build
+```
+
+Preview the build locally:
+
+```bash
+pnpm run preview
+```
+
+The preview server serves the built output at **http://localhost:4173** by default.
+
+## Configure production metadata
+
+Set `site.url` before publishing. PreactPress uses it for canonical URLs, Open Graph metadata, `sitemap.xml`, and `robots.txt`.
+
+```ts
+export default {
+  site: {
+    title: 'My site',
+    description: 'Short summary for search and social previews',
+    url: 'https://example.com',
+    base: '/'
+  },
+  build: {
+    sitemap: true,
+    robots: true
+  }
+}
+```
+
+## Public base path
+
+By default, PreactPress assumes your site is served at the domain root:
+
+```text
+https://example.com/
+```
+
+If the site is served from a subpath, set `site.base`:
+
+```ts
+export default {
+  site: {
+    url: 'https://user.github.io',
+    base: '/my-repo/'
+  }
+}
+```
+
+You can also override the base path for a single build:
+
+```bash
+pnpm exec preactpress build --base /my-repo/
+```
+
+## Build output
+
+The default output directory is `dist/`:
+
+| Output | Description |
+| --- | --- |
+| `index.html`, `*/index.html` | Static HTML for each route |
+| `assets/*` | Hashed JavaScript and CSS from Vite |
+| `404.html` | Not-found page |
+| `preactpress-search.json` | Search index for the default theme |
+| `preactpress-content/*.json` | Lazy-loaded Markdown payloads for client navigation |
+| `sitemap.xml`, `robots.txt` | Generated when `site.url` and build flags are set |
+| `feed.xml` | Generated when `build.feed` is configured |
+
+Deploy only the output directory. Do not deploy `node_modules`, `.preactpress`, or the build cache.
+
+## Platform settings
+
+For most static hosts, use these settings:
+
+| Host | Build command | Output directory |
+| --- | --- | --- |
+| Netlify | `pnpm run build` | `dist` |
+| Vercel | `pnpm run build` | `dist` |
+| Cloudflare Pages | `pnpm run build` | `dist` |
+| Render Static Site | `pnpm run build` | `dist` |
+
+Install command:
+
+```bash
+pnpm install
+```
+
+Node version: **20 or higher**.
+
+## GitHub Pages
+
+For a project site at `https://user.github.io/my-repo/`, configure:
+
+```ts
+export default {
+  site: {
+    url: 'https://user.github.io',
+    base: '/my-repo/'
+  }
+}
+```
+
+Then deploy the `dist/` directory.
+
+A minimal GitHub Actions workflow can look like this:
+
+```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
+```
+
+In your repository settings, set Pages source to **GitHub Actions**.
+
+## Monorepos
+
+In a monorepo, run commands from the site package directory:
+
+```bash
+cd packages/docs
+pnpm run check
+pnpm run build
+```
+
+Or pass the site path to the CLI:
+
+```bash
+pnpm exec preactpress build ./packages/docs
+```
+
+## Cache headers
+
+Files under `assets/` include content hashes in their filenames. If your host lets you set HTTP headers, cache those files aggressively:
+
+```text
+Cache-Control: public, max-age=31536000, immutable
+```
+
+Do not apply immutable caching to HTML files or JSON payloads such as `preactpress-search.json` and `preactpress-content/*.json`, because those URLs can keep the same names when content changes.

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

@@ -0,0 +1,82 @@
+---
+title: Your first 5 minutes
+description: Change the site title, add a page, and update navigation
+---
+
+# Your first 5 minutes
+
+This hands-on tutorial follows the setup overview in [Getting Started](/guide/getting-started). Follow the steps below in **your** project — this site is the result.
+
+## 1. Change the site title
+
+Edit `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: {
+    title: 'My Docs',
+    description: 'Short summary for search and social previews'
+  }
+}
+```
+
+Save the file. The dev server picks up config changes on the next request.
+
+## 2. Add a page
+
+Create `about.md`:
+
+```md
+---
+title: About
+description: About this site
+---
+
+# About us
+
+Your content here.
+```
+
+PreactPress serves it at `/about`. Every `.md` or `.mdx` file under `srcDir` (default: project root) becomes a URL automatically.
+
+Example: `news/2025/intro.md` → `/news/2025/intro`.
+
+This starter already includes [About](/about) so you can see the finished page.
+
+## 3. Add it to the navigation
+
+In `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: { title: 'My Docs' },
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'About', link: '/about' }
+    ],
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Home', link: '/' },
+          { text: 'About', link: '/about' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Save — the dev server hot-reloads your changes.
+
+## Next steps
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm run dev` | Dev server with SSR and hot reload |
+| `pnpm run check` | Validate config, links, and routes |
+| `pnpm run build` | Static production build → `dist/` |
+| `pnpm run preview` | Local preview of the build |
+
+Before deploying, set `site.url` in config for canonical URLs, Open Graph tags, and `sitemap.xml`. Continue with [Routing](/guide/routing) to understand file-based routes, then [Deploy](/guide/deploy) for production build steps.

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

@@ -0,0 +1,146 @@
+---
+title: Getting Started
+description: Install PreactPress and start a new documentation site
+---
+
+# Getting Started
+
+This guide shows how to create a PreactPress site, understand the generated files, and start the development server.
+
+## Prerequisites
+
+You need:
+
+| Requirement | Version |
+| --- | --- |
+| Node.js | 20 or higher |
+| Package manager | pnpm recommended; npm, yarn, and bun also work |
+| Editor | Any editor with Markdown and TypeScript support |
+
+## Create a site
+
+Start in an empty directory:
+
+```bash
+mkdir my-site
+cd my-site
+pnpm dlx @kamod-ch/preactpress init
+pnpm install
+pnpm run dev
+```
+
+With npm:
+
+```bash
+mkdir my-site
+cd my-site
+npx @kamod-ch/preactpress init
+npm install
+npm run dev
+```
+
+Open **http://localhost:5173** to see the starter site.
+
+> **Note**
+> `preactpress init` copies the built-in starter template and writes `@kamod-ch/preactpress` to `devDependencies`. You do not need to install PreactPress separately before running the initializer.
+
+## File structure
+
+After initialization, the project looks like this:
+
+```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
+```
+
+The `.preactpress` directory contains site configuration. Markdown and MDX files outside `.preactpress` are source files and become routes.
+
+## The config file
+
+The starter config lives at `.preactpress/config.ts`:
+
+```ts
+export default {
+  site: {
+    title: 'My Docs',
+    description: 'Short summary for search and social previews'
+  },
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/what-is-preactpress' }
+    ],
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is PreactPress?', link: '/guide/what-is-preactpress' },
+          { text: 'Getting Started', link: '/guide/getting-started' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Use `site` for site-wide metadata and `themeConfig` for default-theme options such as logo (`logo: '/logo.svg'`), nav, sidebar, search, outline, footer, and edit links.
+
+## Source files
+
+PreactPress uses file-based routing. By default, the source directory is the project root:
+
+```text
+index.md                  -> /
+about.md                  -> /about
+guide/getting-started.md  -> /guide/getting-started
+interactive.mdx           -> /interactive
+```
+
+You can change the source directory with `srcDir`:
+
+```ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+With this config, PreactPress reads pages from `docs/` while `.preactpress/config.ts` still belongs to the project root.
+
+## Commands
+
+The starter includes npm scripts:
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm run dev` | Start the dev server with SSR and hot reload |
+| `pnpm run check` | Validate config, routes, and links |
+| `pnpm run build` | Build the static production site into `dist/` |
+| `pnpm run preview` | Preview the production build locally |
+
+You can also call the CLI directly:
+
+```bash
+pnpm exec preactpress dev
+pnpm exec preactpress check
+pnpm exec preactpress build
+pnpm exec preactpress preview
+```
+
+## What's next?
+
+| Page | Why |
+| --- | --- |
+| [Your first 5 minutes](/guide/first-five-minutes) | Change the title, add a page, and wire navigation |
+| [Routing](/guide/routing) | Learn how Markdown files map to URLs |
+| [Deploy](/guide/deploy) | Build and publish the generated `dist/` directory |

package/templates/hono/guide/routing.md

@@ -0,0 +1,263 @@
+---
+title: Routing
+description: Understand how PreactPress maps files to URLs
+---
+
+# Routing
+
+PreactPress uses file-based routing. Every `.md` and `.mdx` file under `srcDir` becomes a route, and production builds write each route as static HTML.
+
+## File-based routing
+
+Given this structure:
+
+```text
+.
+├── index.md
+├── about.md
+├── guide/
+│   ├── index.md
+│   └── getting-started.md
+└── interactive.mdx
+```
+
+PreactPress creates these routes:
+
+```text
+index.md                  -> /
+about.md                  -> /about
+guide/index.md            -> /guide
+guide/getting-started.md  -> /guide/getting-started
+interactive.mdx           -> /interactive
+```
+
+During production builds, routes are written as directory indexes:
+
+```text
+/                      -> dist/index.html
+/about                 -> dist/about/index.html
+/guide/getting-started -> dist/guide/getting-started/index.html
+```
+
+By default (`cleanUrls: true`), builds emit directory indexes so hosts can serve extensionless URLs.
+
+## Project root and source directory
+
+The project root is where PreactPress looks for `.preactpress/config.ts`.
+
+By default, source files also live in the project root:
+
+```text
+.
+├── .preactpress/
+│   └── config.ts
+├── index.md
+└── guide/
+    └── getting-started.md
+```
+
+You can move content into a nested source directory with `srcDir`:
+
+```ts
+export default {
+  srcDir: 'docs'
+}
+```
+
+That produces this shape:
+
+```text
+.
+├── .preactpress/
+│   └── config.ts
+└── docs/
+    ├── index.md
+    └── guide/
+        └── getting-started.md
+```
+
+The resulting routes stay the same:
+
+```text
+docs/index.md                  -> /
+docs/guide/getting-started.md  -> /guide/getting-started
+```
+
+## Linking between pages
+
+Use absolute or relative links. The recommended style is to omit file extensions:
+
+```md
+[Getting Started](/guide/getting-started)
+[Routing](./routing)
+[Home](../)
+```
+
+Avoid linking directly to generated HTML or source Markdown:
+
+```md
+<!-- Avoid -->
+[Getting Started](/guide/getting-started.md)
+[Getting Started](/guide/getting-started.html)
+```
+
+`preactpress check` validates local Markdown links that use `.md`, `.mdx`, or `.html` extensions and reports missing pages.
+
+## Locale routes
+
+PreactPress supports VitePress-style locale folders. Keep the default language at the root and put translations in locale folders:
+
+```text
+index.md                       -> /
+guide/getting-started.md       -> /guide/getting-started
+de/index.md                    -> /de
+de/guide/getting-started.md    -> /de/guide/getting-started
+```
+
+Configure locale labels, language codes, and locale-specific nav in `.preactpress/config.ts`:
+
+```ts
+export default {
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en'
+    },
+    de: {
+      label: 'Deutsch',
+      lang: 'de',
+      link: '/de/'
+    }
+  }
+}
+```
+
+The default theme shows a language switcher when multiple locales are configured.
+
+## Tag routes
+
+Pages can define tags in frontmatter:
+
+```md
+---
+title: Release notes
+tags: [release, changelog]
+---
+```
+
+Each tag receives an index page:
+
+```text
+release   -> /tags/release
+changelog -> /tags/changelog
+```
+
+For localized content, tag pages are scoped to the locale:
+
+```text
+de/guide/intro.md with tag "Markdown" -> /de/tags/markdown
+```
+
+If a real Markdown or MDX page exists at the same route as a generated tag index, the real page wins.
+
+## Base path
+
+Use `site.base` when the site is served from a subpath, for example GitHub Pages project sites:
+
+```ts
+export default {
+  site: {
+    base: '/my-repo/'
+  }
+}
+```
+
+You can also override it for one build:
+
+```bash
+pnpm exec preactpress build --base /my-repo/
+```
+
+## Route rewrites
+
+Map a public URL to existing content without duplicating files:
+
+```ts
+export default {
+  rewrites: {
+    '/docs': '/guide',
+    '/getting-started': '/guide/intro'
+  }
+}
+```
+
+Keys are the routes visitors use; values must point at routes that already exist from your Markdown files. `preactpress check` validates rewrite sources and collisions.
+
+## Clean URLs and hosting
+
+| `cleanUrls` | Output for `/about` | Typical host |
+| --- | --- | --- |
+| `true` (default) | `dist/about/index.html` | Netlify, Vercel, Cloudflare Pages, GitHub Pages |
+| `false` | `dist/about.html` | Static buckets without directory index support |
+
+```ts
+export default {
+  cleanUrls: false
+}
+```
+
+Most modern static hosts work with the default. Set `cleanUrls: false` only when your host cannot resolve `/about` to `about/index.html`.
+
+## Dynamic routes
+
+Generate routes at build time with a bracket template and a colocated `.paths.ts` file:
+
+```md
+<!-- packages/[pkg].md -->
+---
+title: "{{ params.pkg }}"
+---
+
+# {{ params.pkg }}
+```
+
+```ts
+// packages/[pkg].paths.ts
+export default {
+  paths() {
+    return [
+      { params: { pkg: 'preact' } },
+      { params: { pkg: 'vite' }, props: { note: 'Build tool' } }
+    ]
+  }
+}
+```
+
+This emits `/packages/preact` and `/packages/vite`. Use `{{ params.key }}` and `{{ props.key }}` in frontmatter and body.
+
+## Data loaders
+
+Colocate `*.data.ts` with a page to load build-time data via `createContentLoader` from `@kamod-ch/preactpress/config`. The result is exposed on `page.meta.contentData` (and in themes through the `page` prop).
+
+```ts
+// blog.data.ts
+import { createContentLoader } from '@kamod-ch/preactpress/config'
+
+export default createContentLoader('posts/*.md', {
+  transform(items) {
+    return items.map((item) => ({
+      title: item.title,
+      route: item.route
+    }))
+  }
+})
+```
+
+Pair with `blog.md` or `blog/index.md` for route `/blog`.
+
+## Current limitations
+
+| Feature | Status |
+| --- | --- |
+| Dynamic MDX templates (`[id].mdx`) | Not supported (use `.md` templates) |
+| Pattern-based rewrites with params | Not supported |