@kamod-ch/preactpress 1.0.0

package/templates/docs/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 |

package/templates/docs/guide/what-is-preactpress.md

@@ -0,0 +1,87 @@
+---
+title: What is PreactPress?
+description: Learn what PreactPress is and when to use it
+---
+
+# What is PreactPress?
+
+PreactPress is a static site generator for fast, content-focused websites. You write pages in Markdown or MDX, configure navigation and theme options in `.preactpress/config.ts`, and PreactPress generates static HTML that can be deployed to any static host.
+
+It is built with [Vite](https://vite.dev/) and [Preact](https://preactjs.com/). The workflow is inspired by VitePress, but the component model is Preact instead of Vue.
+
+## Use cases
+
+### Documentation
+
+PreactPress ships with a small default theme for technical documentation. It includes navigation, sidebar groups, outline links, search, last-updated metadata, and Markdown rendering out of the box.
+
+Use it when your docs live naturally as files:
+
+```text
+index.md
+guide/getting-started.md
+guide/routing.md
+reference/api.md
+```
+
+Every Markdown or MDX file becomes a page, so documentation grows by adding files and linking them from the sidebar.
+
+### Blogs, portfolios, and marketing sites
+
+PreactPress can also power blogs, portfolios, and small marketing sites. Markdown handles content, MDX brings in interactive Preact components, and custom themes let you replace the default documentation shell.
+
+The separate `preactpress-examples` project includes a custom-theme example that shows a magazine-style layout with article teasers and tag pages.
+
+## Developer experience
+
+PreactPress focuses on keeping content work simple:
+
+| Feature | What it gives you |
+| --- | --- |
+| Vite dev server | Fast startup and hot updates while editing content |
+| Markdown frontmatter | Page titles, descriptions, tags, draft status, and social metadata |
+| MDX | Preact components inside content pages |
+| Default theme | Nav, sidebar, outline, search, footer, locale switcher |
+| `preactpress check` | Config, route, and link validation before release |
+
+For regular content, use `.md`. When a page needs interactivity, use `.mdx` and import a Preact component:
+
+```mdx
+import Counter from './components/Counter.tsx'
+
+## Demo
+
+<Counter initial={3} />
+```
+
+## Performance
+
+PreactPress produces static HTML for every route during the production build. The first visit receives HTML that already contains the page content, which is good for loading speed and SEO.
+
+After hydration, client-side navigation takes over. Markdown pages are loaded as small JSON payloads from `preactpress-content/*.json`, so large sites do not need to ship every Markdown body in the initial JavaScript bundle.
+
+The production output is static files only:
+
+| Output | Purpose |
+| --- | --- |
+| `index.html`, `*/index.html` | One HTML file per route |
+| `assets/*` | Hashed JavaScript and CSS from Vite |
+| `preactpress-search.json` | Search data for the default theme |
+| `preactpress-content/*.json` | Lazy-loaded Markdown page payloads |
+| `404.html` | Not-found page |
+
+## What about VitePress?
+
+If you know VitePress, PreactPress should feel familiar: both use Vite, file-based Markdown routing, a default docs theme, and static output.
+
+The main difference is the UI stack. VitePress uses Vue. PreactPress uses Preact and MDX, so interactive content and custom themes are written as Preact components.
+
+PreactPress is also static-only in production. You build the site once, upload the output directory, and serve it from Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3, Nginx, or another static host.
+
+## Next steps
+
+| Page | Why |
+| --- | --- |
+| [Getting Started](/guide/getting-started) | Install PreactPress and understand the starter structure |
+| [Routing](/guide/routing) | Learn how files become URLs |
+| [Deploy](/guide/deploy) | Build and publish a static site |

package/templates/docs/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>PreactPress</title>
+    <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" />
+    <link rel="apple-touch-icon" href="/favicon.png" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module">
+      import 'preactpress/app'
+    </script>
+  </body>
+</html>

package/templates/docs/index.md

@@ -0,0 +1,28 @@
+---
+layout: home
+title: PreactPress
+description: Build static documentation and content sites with Markdown, MDX, Vite, and Preact.
+hero:
+  name: PreactPress
+  text: Static sites, written in Markdown
+  tagline: Use Vite and Preact when you need speed, static HTML, and optional interactive components.
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/getting-started
+    - theme: alt
+      text: Configuration
+      link: /guide/configuration
+features:
+  - icon: ⚡
+    title: Fast development
+    details: Vite-powered SSR, hot reload, and static production output.
+  - icon: MD
+    title: Markdown and MDX
+    details: Keep regular pages small and add Preact components only where needed.
+  - icon: ✓
+    title: Release checks
+    details: Validate routes, links, navigation, locales, and drafts before deployment.
+---
+
+PreactPress generates deployable HTML and assets. No Node server is required in production.

package/templates/docs/interactive.mdx

@@ -0,0 +1,32 @@
+---
+title: Interactive MDX
+description: Markdown with imported Preact components
+---
+
+import Counter from './components/Counter.tsx'
+
+## Preact component
+
+MDX pages can import local Preact components and render them inline.
+
+<Counter initial={3} />
+
+## Image
+
+Markdown images work like in `.md` pages:
+
+![Sample photo from Lorem Picsum](https://picsum.photos/id/10/800/450)
+
+## YouTube
+
+Embed with a normal JSX `iframe` (replace the video id with your own):
+
+<iframe
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/aqz-KE-bpKQ"
+  title="YouTube video example"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowFullScreen
+/>

package/templates/docs/markdown-examples.md

@@ -0,0 +1,72 @@
+---
+title: Markdown examples
+description: Rendered examples of PreactPress Markdown extensions.
+tags:
+  - markdown
+---
+
+## Code highlighting
+
+```ts{2}
+export function greet(name: string) {
+  return `Hello, ${name}!`
+}
+```
+
+Inline code such as `themeConfig.outline` uses the theme's code tokens.
+
+## Snippet import
+
+<<< @/snippets/greet.ts{2}
+
+## Containers and alerts
+
+::: tip
+Custom containers support `tip`, `warning`, `danger`, `info`, and `details`.
+:::
+
+> [!NOTE]
+> GFM alert syntax is supported too.
+
+## Table
+
+| Source | Result |
+| --- | --- |
+| `# Title` | Heading |
+| YAML frontmatter | Page metadata |
+
+## Stable heading {#stable-heading}
+
+Use `{#id}` to control a heading fragment.
+
+## Inline table of contents
+
+[[toc]]
+
+### Nested section
+
+The generated table of contents includes level-three headings.
+
+## Code group
+
+::: code-group
+
+```bash [pnpm]
+pnpm add -D @kamod-ch/preactpress
+```
+
+```bash [npm]
+npm install --save-dev @kamod-ch/preactpress
+```
+
+:::
+
+## Included content
+
+<!--@include: @/partials/shared-note.md-->
+
+## Emoji and math
+
+This starter enables both options: :rocket:
+
+Inline math: $E = mc^2$

package/templates/docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "preactpress-docs-starter",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "preactpress dev",
+    "check": "preactpress check",
+    "build": "preactpress build",
+    "preview": "preactpress preview"
+  },
+  "devDependencies": {
+    "@kamod-ch/preactpress": "file:../..",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/docs/partials/shared-note.md

@@ -0,0 +1,3 @@
+::: tip Shared fragment
+This note is pulled in via `<!--@include: @/partials/shared-note.md-->`.
+:::

package/templates/docs/parts/include-body.md

@@ -0,0 +1,9 @@
+Line one — skipped.
+Line two — skipped.
+Line three — skipped.
+Line four — skipped.
+## Included body
+
+This paragraph is pulled in via `<!--@include: …{5,6}-->`.
+
+Line seven — skipped.