@kamod-ch/preactpress 1.0.2 → 2.0.0

package/src/shared/scrollRestoration.ts

@@ -0,0 +1,101 @@
+export const SCROLL_STATE_KEY = "ppScrollY";
+
+let skipScrollRestoreOnce = false;
+
+export function setupScrollRestoration(): () => void {
+  if (typeof window === "undefined") return () => {};
+
+  if ("scrollRestoration" in window.history) {
+    window.history.scrollRestoration = "manual";
+  }
+
+  const onScroll = () => {
+    persistScrollPosition();
+  };
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("pagehide", persistScrollPosition);
+  return () => {
+    window.removeEventListener("scroll", onScroll);
+    window.removeEventListener("pagehide", persistScrollPosition);
+  };
+}
+
+export function persistScrollPosition(): void {
+  if (typeof window === "undefined") return;
+  const scrollY = window.scrollY;
+  const state = window.history.state ?? {};
+  if (state[SCROLL_STATE_KEY] === scrollY) return;
+  window.history.replaceState({ ...state, [SCROLL_STATE_KEY]: scrollY }, "");
+}
+
+export function saveScrollPositionBeforeNavigation(): void {
+  persistScrollPosition();
+}
+
+export function readScrollPositionFromHistory(): number {
+  if (typeof window === "undefined") return 0;
+  const scrollY = window.history.state?.[SCROLL_STATE_KEY];
+  return typeof scrollY === "number" && Number.isFinite(scrollY) ? scrollY : 0;
+}
+
+export function restoreScrollPosition(): void {
+  if (typeof window === "undefined") return;
+  window.scrollTo({ top: readScrollPositionFromHistory(), left: 0, behavior: "auto" });
+}
+
+export async function restoreScrollPositionAfterLayout(): Promise<void> {
+  await scrollAfterLayout(readScrollPositionFromHistory());
+}
+
+export async function scrollToTopAfterLayout(): Promise<void> {
+  await scrollAfterLayout(0);
+}
+
+async function scrollAfterLayout(top: number): Promise<void> {
+  if (typeof window === "undefined") return;
+  await nextAnimationFrame();
+  await nextAnimationFrame();
+  await waitForImagesToSettle();
+  await nextAnimationFrame();
+
+  const html = document.documentElement;
+  const previous = html.style.scrollBehavior;
+  html.style.scrollBehavior = "auto";
+  window.scrollTo({ top, left: 0, behavior: "auto" });
+  html.style.scrollBehavior = previous;
+}
+
+function nextAnimationFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
+async function waitForImagesToSettle(timeoutMs = 1500): Promise<void> {
+  if (typeof document === "undefined") return;
+  const images = Array.from(document.images).filter((image) => !image.complete);
+  if (images.length === 0) return;
+
+  await Promise.race([
+    Promise.allSettled(
+      images.map(
+        (image) =>
+          new Promise<void>((resolve) => {
+            image.addEventListener("load", () => resolve(), { once: true });
+            image.addEventListener("error", () => resolve(), { once: true });
+          }),
+      ),
+    ),
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
+export function skipNextScrollRestore(): void {
+  skipScrollRestoreOnce = true;
+}
+
+export function consumeScrollRestoreOnPopstate(): boolean {
+  if (skipScrollRestoreOnce) {
+    skipScrollRestoreOnce = false;
+    return false;
+  }
+  return true;
+}

package/src/shared/search.ts

@@ -1,3 +1,5 @@
+import { saveScrollPositionBeforeNavigation, skipNextScrollRestore } from "./scrollRestoration.js";
+
 export type SearchProvider = "local" | "algolia";
 
 export interface LocalSearchConfig {
@@ -99,7 +101,9 @@ export function navigateDocSearchResult(itemUrl: string, base: string): void {
     window.location.assign(href);
     return;
   }
+  saveScrollPositionBeforeNavigation();
   window.history.pushState({}, "", href);
+  skipNextScrollRestore();
   window.dispatchEvent(new PopStateEvent("popstate"));
-  window.scrollTo({ top: 0 });
+  window.scrollTo({ top: 0, behavior: "auto" });
 }

package/templates/docs/.preactpress/config.ts

@@ -77,9 +77,14 @@ export default defineConfig({
             items: [
               { text: "Markdown examples", link: "/markdown-examples" },
               { text: "Interactive MDX", link: "/interactive" },
+              { text: "Preact Signals", link: "/examples/preact-signals" },
+              { text: "Mermaid diagrams", link: "/examples/mermaid" },
+              { text: "RSS / Atom feed", link: "/examples/rss" },
               { text: "Algolia DocSearch", link: "/examples/algolia-docsearch" },
               { text: "Content loader", link: "/examples/content-loader" },
               { text: "Dynamic routes", link: "/examples/dynamic-routes" },
+              { text: "Custom theme", link: "/examples/custom-theme" },
+              { text: "Cloudflare Pages", link: "/examples/cloudflare-pages" },
               { text: "Static assets", link: "/examples/static-assets" },
             ],
           },

package/templates/docs/examples/cloudflare-pages.md

@@ -0,0 +1,117 @@
+---
+title: Cloudflare Pages deployment
+description: Deploy a PreactPress static site to Cloudflare Pages.
+tags:
+  - deploy
+  - examples
+---
+
+PreactPress outputs static files, so Cloudflare Pages can serve the generated `dist/` directory without a Node server.
+
+## Prerequisites
+
+- A PreactPress site committed to GitHub or GitLab
+- Node.js 20 or newer
+- A package script like:
+
+```json [package.json]
+{
+  "scripts": {
+    "check": "preactpress check",
+    "build": "preactpress build"
+  }
+}
+```
+
+## Configure PreactPress
+
+Set the final production URL in `.preactpress/config.ts`:
+
+```ts [.preactpress/config.ts]
+import { defineConfig } from "@kamod-ch/preactpress/config";
+
+export default defineConfig({
+  site: {
+    title: "My Docs",
+    description: "Documentation built with PreactPress",
+    url: "https://docs.example.com",
+    base: "/",
+  },
+});
+```
+
+Use `base: "/"` for normal Cloudflare Pages deployments. Only change `base` if you intentionally serve the site from a subpath.
+
+## Deploy with the Cloudflare dashboard
+
+1. Open **Cloudflare Dashboard → Workers & Pages → Create application → Pages**.
+2. Connect your GitHub or GitLab repository.
+3. Choose your PreactPress project.
+4. Use these build settings:
+
+| Setting             | Value            |
+| ------------------- | ---------------- |
+| Framework preset    | `None` / custom  |
+| Build command       | `pnpm run build` |
+| Build output folder | `dist`           |
+| Root directory      | project root     |
+
+If your docs live in a monorepo subfolder, set **Root directory** to that folder, for example:
+
+```txt
+packages/docs
+```
+
+## Environment variables
+
+Set the Node version in Cloudflare Pages:
+
+| Variable       | Value |
+| -------------- | ----- |
+| `NODE_VERSION` | `22`  |
+
+Cloudflare Pages usually detects pnpm from `pnpm-lock.yaml`. If needed, set:
+
+| Variable       | Value     |
+| -------------- | --------- |
+| `PNPM_VERSION` | `10.12.4` |
+
+## Optional: run checks before build
+
+For stricter deployments, use this build command:
+
+```sh
+pnpm run check && pnpm run build
+```
+
+This fails the deployment when routes, nav links, sidebar links, or internal Markdown links are invalid.
+
+## Deploy with Wrangler
+
+You can also deploy the built `dist/` directory manually with Wrangler:
+
+```sh
+pnpm run check
+pnpm run build
+pnpm dlx wrangler pages deploy dist --project-name my-preactpress-site
+```
+
+For a monorepo, run those commands from the site package directory or pass the correct output path.
+
+## Custom domains
+
+After the first deployment, add your domain in **Pages → Custom domains**. Then update `site.url` to match the production domain:
+
+```ts
+export default defineConfig({
+  site: {
+    url: "https://docs.example.com",
+  },
+});
+```
+
+This keeps canonical URLs, Open Graph metadata, `sitemap.xml`, `robots.txt`, and feeds correct.
+
+## Cache notes
+
+Cloudflare can cache hashed files under `assets/` aggressively because their filenames change when content changes. Avoid immutable caching for HTML, `preactpress-search.json`, and `preactpress-content/*.json`.

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`.