@kamod-ch/preactpress 1.0.3 → 2.0.0

package/templates/docs/examples/custom-theme.md

@@ -0,0 +1,266 @@
+---
+title: Custom theme example
+description: A minimal copy-pasteable PreactPress theme with navigation, Markdown, MDX, and styling.
+---
+
+This example shows a small custom theme you can copy into your project. For a larger production-style example, scaffold the bundled magazine template:
+
+```sh
+pnpm exec preactpress init my-magazine --template magazine
+```
+
+## File structure
+
+```txt
+.preactpress/
+  config.ts
+  theme/
+    Layout.tsx
+    theme.css
+index.md
+about.md
+```
+
+## Configure the theme
+
+```ts [.preactpress/config.ts]
+import { defineConfig } from "@kamod-ch/preactpress/config";
+
+export default defineConfig({
+  site: {
+    title: "Acme Docs",
+    description: "A custom themed PreactPress site",
+  },
+
+  // Relative to .preactpress/
+  theme: "./theme/Layout.tsx",
+
+  themeConfig: {
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "About", link: "/about" },
+    ],
+    footer: "Built with PreactPress",
+  },
+});
+```
+
+## Layout component
+
+```tsx [.preactpress/theme/Layout.tsx]
+import type { FunctionalComponent } from "preact";
+import {
+  createMdxHeadingComponents,
+  isActive,
+  withBase,
+  type LayoutProps,
+} from "@kamod-ch/preactpress/client";
+import "./theme.css";
+
+const Layout: FunctionalComponent<LayoutProps> = ({ site, themeConfig, routePath, page }) => {
+  const MdxComponent = page?.kind === "mdx" ? page.Component : undefined;
+  const mdxComponents = createMdxHeadingComponents({
+    headingClass: "ct-heading",
+    anchorClass: "ct-heading-anchor",
+    anchorLabel: "Link to this section",
+  });
+
+  return (
+    <div class="ct-layout">
+      <a class="ct-skip" href="#content">
+        Skip to content
+      </a>
+
+      <header class="ct-header">
+        <a class="ct-brand" href={withBase(site.base, "/")}>
+          {site.title}
+        </a>
+        <nav class="ct-nav" aria-label="Main navigation">
+          {(themeConfig.nav ?? []).map((item) => {
+            const active = isActive(routePath, item.link);
+            return (
+              <a
+                key={item.link}
+                href={withBase(site.base, item.link)}
+                class={active ? "active" : ""}
+                aria-current={active ? "page" : undefined}
+              >
+                {item.text}
+              </a>
+            );
+          })}
+        </nav>
+      </header>
+
+      <main id="content" class="ct-main" tabIndex={-1}>
+        <article class="ct-article">
+          <h1>{page?.title ?? site.title}</h1>
+          {page?.description ? <p class="ct-lead">{page.description}</p> : null}
+
+          {MdxComponent ? (
+            <div class="ct-content">
+              <MdxComponent components={mdxComponents} />
+            </div>
+          ) : (
+            <div
+              class="ct-content"
+              dangerouslySetInnerHTML={{ __html: page?.kind === "markdown" ? page.html : "" }}
+            />
+          )}
+        </article>
+      </main>
+
+      {themeConfig.footer ? <footer class="ct-footer">{themeConfig.footer}</footer> : null}
+    </div>
+  );
+};
+
+export default Layout;
+```
+
+## Styling
+
+```css [.preactpress/theme/theme.css]
+:root {
+  color-scheme: light dark;
+  --ct-bg: #f7f3ea;
+  --ct-panel: #fffaf0;
+  --ct-text: #1f2937;
+  --ct-muted: #6b7280;
+  --ct-border: #eadfca;
+  --ct-accent: #b45309;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ct-bg: #15110b;
+    --ct-panel: #1f1a12;
+    --ct-text: #f8ecd5;
+    --ct-muted: #c5bba9;
+    --ct-border: #3b3022;
+    --ct-accent: #fbbf24;
+  }
+}
+
+body {
+  margin: 0;
+  background: var(--ct-bg);
+  color: var(--ct-text);
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+.ct-skip {
+  position: absolute;
+  left: 1rem;
+  top: -4rem;
+  z-index: 10;
+  background: var(--ct-accent);
+  color: #111827;
+  padding: 0.5rem 0.75rem;
+  border-radius: 999px;
+}
+
+.ct-skip:focus {
+  top: 1rem;
+}
+
+.ct-header {
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: 1.25rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.ct-brand {
+  color: inherit;
+  font-weight: 800;
+  text-decoration: none;
+  letter-spacing: -0.04em;
+}
+
+.ct-nav {
+  display: flex;
+  gap: 0.35rem;
+}
+
+.ct-nav a {
+  color: var(--ct-muted);
+  text-decoration: none;
+  padding: 0.45rem 0.7rem;
+  border-radius: 999px;
+}
+
+.ct-nav a:hover,
+.ct-nav a.active {
+  background: color-mix(in srgb, var(--ct-accent) 16%, transparent);
+  color: var(--ct-text);
+}
+
+.ct-main {
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: 1.25rem;
+}
+
+.ct-article {
+  background: var(--ct-panel);
+  border: 1px solid var(--ct-border);
+  border-radius: 28px;
+  padding: clamp(1.5rem, 4vw, 3rem);
+  box-shadow: 0 24px 70px rgb(0 0 0 / 0.08);
+}
+
+.ct-article h1 {
+  margin: 0;
+  font-size: clamp(2.4rem, 8vw, 5rem);
+  letter-spacing: -0.07em;
+  line-height: 0.95;
+}
+
+.ct-lead {
+  color: var(--ct-muted);
+  font-size: 1.2rem;
+}
+
+.ct-content {
+  line-height: 1.75;
+}
+
+.ct-content a {
+  color: var(--ct-accent);
+}
+
+.ct-content pre {
+  overflow: auto;
+  padding: 1rem;
+  border-radius: 16px;
+  background: #111827;
+  color: #f9fafb;
+}
+
+.ct-heading-anchor {
+  opacity: 0;
+  margin-left: 0.4rem;
+  color: var(--ct-muted);
+  text-decoration: none;
+}
+
+.ct-heading:hover .ct-heading-anchor,
+.ct-heading-anchor:focus-visible {
+  opacity: 1;
+}
+
+.ct-footer {
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: 2rem 1.25rem;
+  color: var(--ct-muted);
+}
+```
+
+## Notes
+
+A custom theme receives the same `LayoutProps` as the default theme. Your layout is responsible for rendering Markdown versus MDX pages, navigation, responsive behavior, search UI, focus management, and any theme-specific styling.

package/templates/docs/examples/mermaid.md

@@ -0,0 +1,53 @@
+---
+title: Mermaid diagrams
+description: Render flowcharts, sequence diagrams, and other Mermaid diagrams in Markdown and MDX.
+tags:
+  - examples
+  - markdown
+---
+
+PreactPress renders Mermaid diagrams from fenced code blocks. Use the `mermaid` language name:
+
+````md
+```mermaid
+graph TD
+  A[Markdown] --> B[PreactPress]
+  B --> C[Static HTML]
+```
+````
+
+## Flowchart
+
+```mermaid
+graph TD
+  A[Markdown] --> B[PreactPress]
+  B --> C[Static HTML]
+  C --> D[Fast docs site]
+```
+
+## Sequence diagram
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Site as PreactPress Site
+  participant Mermaid
+
+  User->>Site: Open docs page
+  Site->>Mermaid: Render diagram block
+  Mermaid-->>Site: SVG diagram
+  Site-->>User: Interactive documentation
+```
+
+## State diagram
+
+```mermaid
+stateDiagram-v2
+  [*] --> Draft
+  Draft --> Review
+  Review --> Published
+  Review --> Draft
+  Published --> [*]
+```
+
+Mermaid is loaded on the client only when a page contains a diagram.

package/templates/docs/examples/preact-signals.md

@@ -0,0 +1,102 @@
+---
+title: Preact Signals
+description: Use @preact/signals in MDX components and custom PreactPress themes.
+tags:
+  - examples
+  - mdx
+---
+
+PreactPress is built on Preact, so you can use `@preact/signals` in MDX components and custom themes.
+
+Install Signals in your site project:
+
+```sh
+pnpm add @preact/signals
+```
+
+## Component example
+
+Create a normal Preact component:
+
+```tsx [components/SignalCounter.tsx]
+import { signal } from "@preact/signals";
+
+const count = signal(0);
+
+export default function SignalCounter() {
+  return (
+    <button type="button" onClick={() => count.value++}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+Then import it from an MDX page:
+
+```mdx [interactive.mdx]
+import SignalCounter from "./components/SignalCounter";
+
+# Signals demo
+
+<SignalCounter />
+```
+
+## Derived values
+
+Use `computed` for derived state:
+
+```tsx
+import { computed, signal } from "@preact/signals";
+
+const count = signal(0);
+const doubled = computed(() => count.value * 2);
+
+export default function DoubledCounter() {
+  return (
+    <div>
+      <button type="button" onClick={() => count.value++}>
+        Count: {count}
+      </button>
+      <p>Doubled: {doubled}</p>
+    </div>
+  );
+}
+```
+
+## Custom theme usage
+
+Signals also work inside a custom theme:
+
+```tsx [.preactpress/theme/Layout.tsx]
+import type { FunctionalComponent } from "preact";
+import { signal } from "@preact/signals";
+import type { LayoutProps } from "@kamod-ch/preactpress/client";
+
+const menuOpen = signal(false);
+
+const Layout: FunctionalComponent<LayoutProps> = ({ site, page }) => (
+  <div>
+    <header>
+      <a href="/">{site.title}</a>
+      <button type="button" onClick={() => (menuOpen.value = !menuOpen.value)}>
+        Menu
+      </button>
+    </header>
+
+    {menuOpen.value ? <nav>Navigation…</nav> : null}
+
+    <main id="content">
+      {page?.kind === "markdown" ? (
+        <article dangerouslySetInnerHTML={{ __html: page.html }} />
+      ) : page?.kind === "mdx" ? (
+        <page.Component />
+      ) : null}
+    </main>
+  </div>
+);
+
+export default Layout;
+```
+
+No special PreactPress configuration is required beyond installing `@preact/signals`.

package/templates/docs/examples/rss.md

@@ -0,0 +1,104 @@
+---
+title: RSS / Atom feed
+description: Generate a static feed.xml for blogs, changelogs, and magazine-style sites.
+tags:
+  - examples
+  - deploy
+---
+
+PreactPress can generate a static `feed.xml` during production builds. The feed uses the Atom XML format and is suitable for RSS readers.
+
+## Enable the feed
+
+Set `site.url` and enable `build.feed` in `.preactpress/config.ts`:
+
+```ts [.preactpress/config.ts]
+import { defineConfig } from "@kamod-ch/preactpress/config";
+
+export default defineConfig({
+  site: {
+    title: "Acme Blog",
+    description: "Product updates and engineering notes",
+    url: "https://example.com",
+  },
+
+  build: {
+    feed: { limit: 20 },
+  },
+});
+```
+
+After running a production build, PreactPress writes:
+
+```txt
+dist/feed.xml
+```
+
+## Add page metadata
+
+Feed entries use each page's title, description, route, and `lastUpdated` value.
+
+```md [posts/launch.md]
+---
+title: Launch notes
+description: What shipped in our first public release.
+lastUpdated: 2026-07-01T10:00:00.000Z
+tags:
+  - changelog
+---
+
+We shipped the first public version today.
+```
+
+## Build and inspect
+
+```sh
+pnpm run build
+```
+
+Then open or publish:
+
+```txt
+https://example.com/feed.xml
+```
+
+## Link the feed from your HTML head
+
+You can expose the feed to browsers and feed readers with `transformHead`:
+
+```ts [.preactpress/config.ts]
+import { defineConfig } from "@kamod-ch/preactpress/config";
+
+export default defineConfig({
+  site: {
+    title: "Acme Blog",
+    description: "Product updates and engineering notes",
+    url: "https://example.com",
+  },
+
+  build: {
+    feed: { limit: 20 },
+  },
+
+  transformHead() {
+    return [
+      [
+        "link",
+        {
+          rel: "alternate",
+          type: "application/atom+xml",
+          title: "Acme Blog feed",
+          href: "/feed.xml",
+        },
+      ],
+    ];
+  },
+});
+```
+
+## Notes
+
+- Feed generation requires `site.url`.
+- Draft pages are excluded from production output and therefore from the feed.
+- `build.feed: true` includes all pages.
+- `build.feed: { limit: 20 }` keeps only the newest entries.

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

@@ -36,4 +36,4 @@ 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`.
 
-The `magazine` and `hono` init templates are complete custom-theme examples.
+See the [custom theme example](/examples/custom-theme) for a copy-pasteable minimal theme. The `magazine` and `hono` init templates are complete custom-theme examples.

package/templates/docs/guide/deploy.md

@@ -97,6 +97,8 @@ For most static hosts, use these settings:
 | Cloudflare Pages   | `pnpm run build` | `dist`           |
 | Render Static Site | `pnpm run build` | `dist`           |
 
+See the [Cloudflare Pages deployment guide](/examples/cloudflare-pages) for dashboard settings, environment variables, Wrangler deployment, and custom domain notes.
+
 Install command:
 
 ```bash

package/templates/docs/guide/markdown-and-mdx.md

@@ -7,7 +7,7 @@ Use `.md` for content that does not need browser-side components. Use `.mdx` whe
 
 ## Markdown
 
-Markdown pages support frontmatter, heading anchors, syntax highlighting, tables, containers, GFM alerts, code groups, file includes, snippet imports, emoji, optional MathJax, and `[[toc]]`.
+Markdown pages support frontmatter, heading anchors, syntax highlighting, Mermaid diagrams, tables, containers, GFM alerts, code groups, file includes, snippet imports, emoji, optional MathJax, and `[[toc]]`.
 
 ```md
 ---

package/templates/docs/markdown-examples.md

@@ -23,6 +23,16 @@ export function greet(name: string) {
 
 Inline code like `themeConfig.outline` uses the same theme tokens as code blocks.
 
+## Mermaid diagrams
+
+Use a `mermaid` fenced code block to render diagrams in Markdown and MDX pages:
+
+```mermaid
+graph TD
+  A[Markdown] --> B[PreactPress]
+  B --> C[Static HTML]
+```
+
 ## Snippet import
 
 Reuse source files instead of duplicating code: