@kamod-ch/preactpress 1.0.0 → 1.0.2

package/templates/docs/examples/algolia-docsearch.md

@@ -0,0 +1,33 @@
+---
+title: Algolia DocSearch example
+description: Configure the default theme to mount Algolia DocSearch instead of local search.
+tags:
+  - examples
+  - search
+---
+
+# Algolia DocSearch example
+
+The default theme can use local search (`search: true`) or Algolia DocSearch. Keep local search enabled until you have real DocSearch credentials; placeholder credentials intentionally fail `preactpress check`.
+
+```ts
+import { defineConfig } from "@kamod-ch/preactpress/config";
+
+export default defineConfig({
+  themeConfig: {
+    search: {
+      provider: "algolia",
+      options: {
+        appId: "YOUR_APP_ID",
+        apiKey: "YOUR_SEARCH_API_KEY",
+        indexName: "YOUR_INDEX_NAME",
+        locales: {
+          de: { indexName: "YOUR_DE_INDEX_NAME" },
+        },
+      },
+    },
+  },
+});
+```
+
+When credentials are complete, the default theme renders the DocSearch button in the header and maps selected results back to PreactPress routes.

package/templates/docs/examples/content-loader.data.ts

@@ -0,0 +1,11 @@
+import { createContentLoader } from "@kamod-ch/preactpress/config";
+
+export default createContentLoader(["guide/*.md"], {
+  transform(items) {
+    return items.map((item) => ({
+      title: item.title,
+      route: item.route,
+      description: item.description,
+    }));
+  },
+});

package/templates/docs/examples/content-loader.md

@@ -0,0 +1,29 @@
+---
+title: Content loader example
+description: A runnable createContentLoader example that collects guide metadata at build time.
+tags:
+  - examples
+  - data
+---
+
+# Content loader example
+
+This page has a matching `examples/content-loader.data.ts` module. During `preactpress build`, it collects guide pages and attaches the transformed result to this route's page data.
+
+The default theme does not render `contentData` automatically, but custom themes can read it from `page.meta.contentData` just like the magazine starter does.
+
+```ts
+import { createContentLoader } from "@kamod-ch/preactpress/config";
+
+export default createContentLoader(["guide/*.md"], {
+  transform(items) {
+    return items.map((item) => ({
+      title: item.title,
+      route: item.route,
+      description: item.description,
+    }));
+  },
+});
+```
+
+Build this starter and inspect `dist/preactpress-content/examples/content-loader.json` to see the generated data payload.

package/templates/docs/examples/dynamic-routes.md

@@ -0,0 +1,16 @@
+---
+title: Dynamic route example
+description: Build multiple static pages from one bracket route template.
+tags:
+  - examples
+  - dynamic-routes
+---
+
+# Dynamic route example
+
+The docs starter includes a runnable dynamic route under `packages/[pkg].md`.
+
+- [PreactPress package page](/packages/preactpress)
+- [Preact package page](/packages/preact)
+
+The matching `packages/[pkg].paths.ts` module returns the static params and props that are rendered at build time. No production server is required.

package/templates/docs/examples/static-assets.md

@@ -0,0 +1,13 @@
+---
+title: Static assets example
+description: Serve files from the public directory with the generated static site.
+tags:
+  - examples
+  - deploy
+---
+
+# Static assets example
+
+Files in `public/` are copied to the root of `dist/` during `preactpress build`.
+
+This starter includes [`/preactpress-example.txt`](/preactpress-example.txt) as a tiny public asset. Use this pattern for `robots.txt` overrides, downloads, images, and other files that should keep a stable URL.

package/templates/docs/guide/advanced.md

@@ -8,12 +8,12 @@ description: Build hooks, data loaders, dynamic routes, MPA mode, and incrementa
 Export an async factory when navigation or metadata comes from another system.
 
 ```ts
-import { defineConfig } from '@kamod-ch/preactpress/config'
+import { defineConfig } from "@kamod-ch/preactpress/config";
 
 export default defineConfig(async () => ({
-  site: { title: 'CMS docs', description: 'Generated navigation' },
-  themeConfig: { sidebar: await loadSidebar() }
-}))
+  site: { title: "CMS docs", description: "Generated navigation" },
+  themeConfig: { sidebar: await loadSidebar() },
+}));
 ```
 
 ## Build hooks

package/templates/docs/guide/commands.md

@@ -5,16 +5,16 @@ description: Commands for scaffolding, development, validation, builds, and prev
 
 Run commands from the site root or pass a root path as the final argument.
 
-| Command | Purpose |
-| --- | --- |
-| `preactpress init [dir]` | Scaffold the minimal starter |
-| `preactpress init [dir] --template docs` | Scaffold the full documentation starter |
-| `preactpress init [dir] --template magazine` | Scaffold a custom editorial theme |
-| `preactpress init [dir] --template hono` | Scaffold a product/docs custom theme |
-| `preactpress dev [root]` | Start Vite SSR and hot reload |
-| `preactpress check [root]` | Validate config, routes, links, locales, and drafts |
-| `preactpress build [root]` | Emit static production files |
-| `preactpress preview [root]` | Serve `outDir` locally |
+| Command                                      | Purpose                                             |
+| -------------------------------------------- | --------------------------------------------------- |
+| `preactpress init [dir]`                     | Scaffold the minimal starter                        |
+| `preactpress init [dir] --template docs`     | Scaffold the full documentation starter             |
+| `preactpress init [dir] --template magazine` | Scaffold a custom editorial theme                   |
+| `preactpress init [dir] --template hono`     | Scaffold a product/docs custom theme                |
+| `preactpress dev [root]`                     | Start Vite SSR and hot reload                       |
+| `preactpress check [root]`                   | Validate config, routes, links, locales, and drafts |
+| `preactpress build [root]`                   | Emit static production files                        |
+| `preactpress preview [root]`                 | Serve `outDir` locally                              |
 
 ## Recommended workflow
 

package/templates/docs/guide/configuration.md

@@ -6,34 +6,34 @@ description: Complete reference for PreactPress site, theme, Markdown, build, an
 Configuration lives in `.preactpress/config.ts`. A plain object works without imports; `defineConfig` adds type inference once PreactPress is installed.
 
 ```ts
-import { defineConfig } from '@kamod-ch/preactpress/config'
+import { defineConfig } from "@kamod-ch/preactpress/config";
 
 export default defineConfig({
-  site: { title: 'My docs', description: 'Product documentation' }
-})
+  site: { title: "My docs", description: "Product documentation" },
+});
 ```
 
 ## Top-level options
 
-| Option | Purpose |
-| --- | --- |
-| `srcDir` | Content root, default `.` |
-| `srcExclude` | Glob patterns that must not become pages |
-| `outDir` | Static output directory, default `dist` |
-| `cacheDir` | Incremental build cache directory |
-| `cleanUrls` | Emit `path/index.html` when true |
-| `rewrites` | Map public routes to existing content routes |
-| `ignoreDeadLinks` | Boolean, glob list, or callback used by `check` |
-| `mpa` | Remove client navigation from regular Markdown pages |
-| `lastUpdatedGit` | Prefer git commit times for last-updated metadata |
-| `theme` | Custom Preact layout module relative to `.preactpress` |
-| `site` | Global title, description, language, URL, base, and title template |
-| `locales` | Locale metadata and locale-specific theme settings |
-| `themeConfig` | Default-theme navigation and page chrome |
-| `markdown` | Markdown parser features |
-| `head` | Global meta, link, and script tuples |
-| `vite` | User Vite configuration merged into the internal config |
-| `build` | Sitemap, robots, and feed output |
+| Option            | Purpose                                                            |
+| ----------------- | ------------------------------------------------------------------ |
+| `srcDir`          | Content root, default `.`                                          |
+| `srcExclude`      | Glob patterns that must not become pages                           |
+| `outDir`          | Static output directory, default `dist`                            |
+| `cacheDir`        | Incremental build cache directory                                  |
+| `cleanUrls`       | Emit `path/index.html` when true                                   |
+| `rewrites`        | Map public routes to existing content routes                       |
+| `ignoreDeadLinks` | Boolean, glob list, or callback used by `check`                    |
+| `mpa`             | Remove client navigation from regular Markdown pages               |
+| `lastUpdatedGit`  | Prefer git commit times for last-updated metadata                  |
+| `theme`           | Custom Preact layout module relative to `.preactpress`             |
+| `site`            | Global title, description, language, URL, base, and title template |
+| `locales`         | Locale metadata and locale-specific theme settings                 |
+| `themeConfig`     | Default-theme navigation and page chrome                           |
+| `markdown`        | Markdown parser features                                           |
+| `head`            | Global meta, link, and script tuples                               |
+| `vite`            | User Vite configuration merged into the internal config            |
+| `build`           | Sitemap, robots, and feed output                                   |
 
 ## Site metadata
 
@@ -52,19 +52,19 @@ Set `site.url` for canonical URLs, Open Graph, sitemap, robots, feeds, and local
 
 ## Theme options
 
-| Option | Purpose |
-| --- | --- |
-| `logo` | URL or `{ light, dark }` image pair |
-| `labels` | Override localized UI labels |
-| `nav` | Header links and nested dropdowns |
-| `sidebar` | Global groups or path-prefix map |
-| `outline` | Enable or choose heading levels |
-| `search` | Local search or Algolia DocSearch |
-| `socialLinks` | Built-in or custom SVG social icons |
-| `tags` | Show or hide page tag chips |
-| `footer` | Site footer text |
-| `editLink` | Repository edit URL pattern using `:path` |
-| `lastUpdated` | Show page timestamps |
+| Option        | Purpose                                   |
+| ------------- | ----------------------------------------- |
+| `logo`        | URL or `{ light, dark }` image pair       |
+| `labels`      | Override localized UI labels              |
+| `nav`         | Header links and nested dropdowns         |
+| `sidebar`     | Global groups or path-prefix map          |
+| `outline`     | Enable or choose heading levels           |
+| `search`      | Local search or Algolia DocSearch         |
+| `socialLinks` | Built-in or custom SVG social icons       |
+| `tags`        | Show or hide page tag chips               |
+| `footer`      | Site footer text                          |
+| `editLink`    | Repository edit URL pattern using `:path` |
+| `lastUpdated` | Show page timestamps                      |
 
 Available label keys are `skip`, `navigation`, `menu`, `closeMenu`, `search`, `filterPages`, `searchResults`, `previous`, `next`, `lastUpdated`, `onThisPage`, and `language`.
 
@@ -109,10 +109,10 @@ Import `defineConfig` from `@kamod-ch/preactpress/config` for typed site configu
 For blogs and magazines, optional content-model helpers are available:
 
 ```ts
-import { createContentLoader } from '@kamod-ch/preactpress/config'
-import { articleFromFrontmatter, type ArticlePost } from '@kamod-ch/preactpress/shared'
+import { createContentLoader } from "@kamod-ch/preactpress/config";
+import { articleFromFrontmatter, type ArticlePost } from "@kamod-ch/preactpress/shared";
 
-export default createContentLoader<ArticlePost[]>(['posts/*.md'], {
+export default createContentLoader<ArticlePost[]>(["posts/*.md"], {
   transform(items) {
     return items.map((item) =>
       articleFromFrontmatter({
@@ -120,11 +120,11 @@ export default createContentLoader<ArticlePost[]>(['posts/*.md'], {
         url: item.url,
         title: item.title,
         description: item.description,
-        frontmatter: item.frontmatter
-      })
-    )
-  }
-})
+        frontmatter: item.frontmatter,
+      }),
+    );
+  },
+});
 ```
 
 Loader output is exposed on `page.meta.contentData` for the matching route.

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

@@ -40,14 +40,14 @@ Save the file — with `pnpm run dev` running, the page is immediately available
 
 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` |
+| 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` |
+| `interactive.mdx`    | `/interactive`     |
 
 Production builds write directory indexes (`dist/about/index.html`) so URLs work without `.html`.
 
@@ -60,8 +60,8 @@ By default, Markdown files live in the project root next to `.preactpress/`. You
 ```ts
 // .preactpress/config.ts
 export default {
-  srcDir: 'docs'
-}
+  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.
@@ -78,14 +78,14 @@ 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 |
+| 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.
 
@@ -99,7 +99,7 @@ title: Demo
 description: Interactive component
 ---
 
-import Counter from './components/Counter.tsx'
+import Counter from "./components/Counter.tsx";
 
 ## Counter
 
@@ -110,6 +110,27 @@ Import components relative to the MDX file. `##` and `###` headings feed the on-
 
 Example in this starter: [Interactive MDX](/interactive).
 
+## Marketing pages with MDX
+
+For a homepage or landing page that should use the default shell but custom section design, keep `layout: home`, disable the default Markdown prose styles, and add a page-specific class:
+
+```mdx
+---
+layout: home
+title: Product docs
+sidebar: false
+pageClass: product-home
+markdownStyles: false
+---
+
+import "./components/product-home.css";
+import ProductHero from "./components/ProductHero.tsx";
+
+<ProductHero />
+```
+
+`pageClass` gives your CSS a stable scope, while `markdownStyles: false` prevents default prose spacing from fighting custom sections. The docs starter homepage uses this pattern in [`index.mdx`](/).
+
 ## Add to navigation
 
 New pages do **not** appear in the header or sidebar automatically. Register them in `.preactpress/config.ts`:
@@ -118,20 +139,20 @@ New pages do **not** appear in the header or sidebar automatically. Register the
 export default {
   themeConfig: {
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Contact', link: '/contact' }
+      { text: "Home", link: "/" },
+      { text: "Contact", link: "/contact" },
     ],
     sidebar: [
       {
-        text: 'Guide',
+        text: "Guide",
         items: [
-          { text: 'Creating pages', link: '/guide/creating-pages' },
-          { text: 'Contact', link: '/contact' }
-        ]
-      }
-    ]
-  }
-}
+          { 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).
@@ -154,18 +175,18 @@ Each locale is a **separate file**, not an alias of the default page.
 
 ## 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 |
+| 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 |
-| --- | --- |
+| 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) |
+| Routing, `srcDir`, tags    | [Routing](/guide/routing)                         |
+| Markdown syntax            | [Markdown examples](/markdown-examples)           |
+| Production build           | [Deploy](/guide/deploy)                           |

package/templates/docs/guide/custom-themes.md

@@ -7,31 +7,31 @@ Set `theme` to a TSX module relative to `.preactpress`:
 
 ```ts
 export default {
-  theme: './theme/Layout.tsx'
-}
+  theme: "./theme/Layout.tsx",
+};
 ```
 
 The module default-exports a Preact component receiving `LayoutProps` from `@kamod-ch/preactpress/client`.
 
 ```tsx
-import type { FunctionalComponent } from 'preact'
-import type { LayoutProps } from '@kamod-ch/preactpress/client'
-import './theme.css'
+import type { FunctionalComponent } from "preact";
+import type { LayoutProps } from "@kamod-ch/preactpress/client";
+import "./theme.css";
 
 const Layout: FunctionalComponent<LayoutProps> = ({ site, page }) => (
   <div>
     <header>{site.title}</header>
     <main id="content">
-      {page?.kind === 'markdown' ? (
+      {page?.kind === "markdown" ? (
         <article dangerouslySetInnerHTML={{ __html: page.html }} />
-      ) : page?.kind === 'mdx' ? (
+      ) : page?.kind === "mdx" ? (
         <page.Component />
       ) : null}
     </main>
   </div>
-)
+);
 
-export default Layout
+export default Layout;
 ```
 
 Theme authors are responsible for navigation, responsive behavior, focus management, search UI, and rendering Markdown versus MDX pages. Helpers for routes, page head data, tags, slugs, and theme state are exported from `@kamod-ch/preactpress/client` and `@kamod-ch/preactpress/shared`.

package/templates/docs/guide/deploy.md

@@ -33,16 +33,16 @@ Set `site.url` before publishing. PreactPress uses it for canonical URLs, Open G
 ```ts
 export default {
   site: {
-    title: 'My site',
-    description: 'Short summary for search and social previews',
-    url: 'https://example.com',
-    base: '/'
+    title: "My site",
+    description: "Short summary for search and social previews",
+    url: "https://example.com",
+    base: "/",
   },
   build: {
     sitemap: true,
-    robots: true
-  }
-}
+    robots: true,
+  },
+};
 ```
 
 ## Public base path
@@ -58,10 +58,10 @@ If the site is served from a subpath, set `site.base`:
 ```ts
 export default {
   site: {
-    url: 'https://user.github.io',
-    base: '/my-repo/'
-  }
-}
+    url: "https://user.github.io",
+    base: "/my-repo/",
+  },
+};
 ```
 
 You can also override the base path for a single build:
@@ -74,15 +74,15 @@ pnpm exec preactpress build --base /my-repo/
 
 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 |
+| 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 |
+| `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.
 
@@ -90,12 +90,12 @@ Deploy only the output directory. Do not deploy `node_modules`, `.preactpress`,
 
 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` |
+| 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:
 
@@ -112,10 +112,10 @@ For a project site at `https://user.github.io/my-repo/`, configure:
 ```ts
 export default {
   site: {
-    url: 'https://user.github.io',
-    base: '/my-repo/'
-  }
-}
+    url: "https://user.github.io",
+    base: "/my-repo/",
+  },
+};
 ```
 
 Then deploy the `dist/` directory.

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

@@ -14,10 +14,10 @@ Edit `.preactpress/config.ts`:
 ```ts
 export default {
   site: {
-    title: 'My Docs',
-    description: 'Short summary for search and social previews'
-  }
-}
+    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.
@@ -41,7 +41,7 @@ PreactPress serves it at `/about`. Every `.md` or `.mdx` file under `srcDir` (de
 
 Example: `news/2025/intro.md` → `/news/2025/intro`.
 
-This starter already includes [About](/about) so you can see the finished page.
+Create the file in your project, save it, and you can open `/about` right away.
 
 ## 3. Add it to the navigation
 
@@ -49,34 +49,34 @@ In `.preactpress/config.ts`:
 
 ```ts
 export default {
-  site: { title: 'My Docs' },
+  site: { title: "My Docs" },
   themeConfig: {
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'About', link: '/about' }
+      { text: "Home", link: "/" },
+      { text: "About", link: "/about" },
     ],
     sidebar: [
       {
-        text: 'Guide',
+        text: "Guide",
         items: [
-          { text: 'Home', link: '/' },
-          { text: 'About', link: '/about' }
-        ]
-      }
-    ]
-  }
-}
+          { 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 |
+| 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.