@kamod-ch/preactpress 1.0.0

package/templates/docs/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/docs/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/docs/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/docs/guide/markdown-and-mdx.md

@@ -0,0 +1,59 @@
+---
+title: Markdown and MDX
+description: Author static Markdown pages and interactive MDX pages.
+---
+
+Use `.md` for content that does not need browser-side components. Use `.mdx` when a page imports and renders Preact components.
+
+## Markdown
+
+Markdown pages support frontmatter, heading anchors, syntax highlighting, tables, containers, GFM alerts, code groups, file includes, snippet imports, emoji, optional MathJax, and `[[toc]]`.
+
+```md
+---
+title: API guide
+description: Integrate the API
+---
+
+## Authentication
+
+::: warning
+Never commit production credentials.
+:::
+```
+
+Raw HTML is disabled by default. Enable `markdown.html` only when every author is trusted.
+
+## MDX
+
+```mdx
+---
+title: Counter demo
+---
+
+import Counter from './components/Counter.tsx'
+
+## Demo
+
+<Counter initial={3} />
+```
+
+MDX pages hydrate in the browser. Regular Markdown payloads are loaded as HTML, which keeps larger documentation sites from bundling every page body into JavaScript.
+
+## Reusing content
+
+Import a source snippet relative to `srcDir`:
+
+```md
+<<< @/snippets/example.ts{2,4}
+```
+
+Include a Markdown fragment:
+
+```md
+<!--@include: @/partials/shared-note.md-->
+```
+
+Exclude fragments from routing with `srcExclude`.
+
+See [Markdown examples](/markdown-examples) for rendered examples.