@kamod-ch/preactpress 1.0.0

package/src/shared/sidebar.ts

@@ -0,0 +1,67 @@
+import type { NavItem, ResolvedI18n, SidebarGroup, SidebarItem } from '../node/siteConfig.js'
+import { routePathKey } from './locale.js'
+import { normalizeRoute } from './route.js'
+
+export type SidebarConfig = SidebarGroup[] | Record<string, SidebarGroup[]>
+
+export function isPathSidebarConfig(
+  sidebar: SidebarConfig | undefined
+): sidebar is Record<string, SidebarGroup[]> {
+  return Boolean(sidebar && !Array.isArray(sidebar))
+}
+
+export function resolveSidebarForRoute(
+  sidebar: SidebarConfig | undefined,
+  route: string,
+  i18n?: ResolvedI18n
+): SidebarGroup[] {
+  if (!sidebar) return []
+  if (Array.isArray(sidebar)) return sidebar
+
+  const pathKey = routePathKey(route, i18n)
+  const entries = Object.entries(sidebar)
+    .map(([prefix, groups]) => ({ prefix: normalizeRoute(prefix), groups }))
+    .filter(({ prefix }) => prefix !== '/')
+    .sort((a, b) => b.prefix.length - a.prefix.length)
+
+  for (const { prefix, groups } of entries) {
+    if (pathKey === prefix || pathKey.startsWith(`${prefix}/`)) {
+      return groups
+    }
+  }
+
+  return sidebar['/'] ?? sidebar[''] ?? []
+}
+
+export function flattenSidebarLeafItems(
+  items: SidebarItem[]
+): Array<{ text: string; link: string }> {
+  const out: Array<{ text: string; link: string }> = []
+  for (const item of items) {
+    if (item.link) out.push({ text: item.text, link: item.link })
+    if (item.items?.length) out.push(...flattenSidebarLeafItems(item.items))
+  }
+  return out
+}
+
+export function flattenSidebarItems(
+  sidebar: SidebarConfig | undefined
+): Array<{ text: string; link: string }> {
+  return allSidebarGroups(sidebar).flatMap((group) => flattenSidebarLeafItems(group.items))
+}
+
+export function flattenNavLeafItems(
+  items: NavItem[] | undefined
+): Array<{ text: string; link: string }> {
+  const out: Array<{ text: string; link: string }> = []
+  for (const item of items ?? []) {
+    if (item.link) out.push({ text: item.text, link: item.link })
+    if (item.items?.length) out.push(...flattenNavLeafItems(item.items))
+  }
+  return out
+}
+
+export function allSidebarGroups(sidebar: SidebarConfig | undefined): SidebarGroup[] {
+  if (!sidebar) return []
+  return Array.isArray(sidebar) ? sidebar : Object.values(sidebar).flat()
+}

package/src/shared/slug.ts

@@ -0,0 +1,23 @@
+import type { OutlineItem } from '../node/siteConfig.js'
+
+export function slugifySegment(text: string, fallback = 'section'): string {
+  const slug = text
+    .toLowerCase()
+    .trim()
+    .replace(/<[^>]+>/g, '')
+    .replace(/&[a-z0-9#]+;/gi, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || fallback
+}
+
+export function uniqueSlug(base: string, existing: OutlineItem[]): string {
+  let id = base
+  let i = 1
+  const used = new Set(existing.map((h) => h.id))
+  while (used.has(id)) {
+    i += 1
+    id = `${base}-${i}`
+  }
+  return id
+}

package/src/shared/socialIcons.ts

@@ -0,0 +1,44 @@
+/** Built-in simple-icons-style SVGs for common `themeConfig.socialLinks` icons. */
+export const SOCIAL_ICON_SVGS: Record<string, string> = {
+  github:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>GitHub</title><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.404 1.02.005 2.04.137 3 .404 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>',
+  gitlab:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>GitLab</title><path fill="currentColor" d="m23.955 13.587-.035-.086L20.55 2.395A.795.795 0 0 0 19.786 2H4.214a.795.795 0 0 0-.764.395L.08 13.501l-.035.086a6.015 6.015 0 0 0 2.13 6.953l.011.008.03.022 5.08 3.802.03.022.011.008a6.014 6.014 0 0 0 11.73 0l.011-.008.03-.022 5.08-3.802.03-.022.011-.008a6.015 6.015 0 0 0 2.13-6.953Z"/></svg>',
+  discord:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Discord</title><path fill="currentColor" d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286z"/></svg>',
+  twitter:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>X</title><path fill="currentColor" d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"/></svg>',
+  x:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>X</title><path fill="currentColor" d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"/></svg>',
+  mastodon:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Mastodon</title><path fill="currentColor" d="M23.268 5.313c-.35-2.578-2.858-4.532-5.573-4.776-2.005-.18-3.927.586-5.01 1.776-1.083-1.19-3.005-1.956-5.01-1.776C4.97.781 2.462 2.735 2.112 5.313c-.372 2.75-.372 5.75 0 8.5.35 2.578 2.858 4.532 5.573 4.776 2.005.18 3.927-.586 5.01-1.776 1.083 1.19 3.005 1.956 5.01 1.776 2.715-.244 5.223-2.198 5.573-4.776.372-2.75.372-5.75 0-8.5ZM8.708 15.855c-1.365 0-2.47-1.105-2.47-2.47s1.105-2.47 2.47-2.47 2.47 1.105 2.47 2.47-1.105 2.47-2.47 2.47Zm6.584 0c-1.365 0-2.47-1.105-2.47-2.47s1.105-2.47 2.47-2.47 2.47 1.105 2.47 2.47-1.105 2.47-2.47 2.47Z"/></svg>',
+  bluesky:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Bluesky</title><path fill="currentColor" d="M12 10.8c-1.087-2.114-4.046-6.053-6.798-7.995C2.566.944 1.561 1.266.902 1.565.139 1.908 0 3.08 0 3.768c0 .69.378 5.65.624 6.479.815 2.736 3.713 3.66 6.387 3.364.136-.02.275-.039.415-.056-.138.022-.276.04-.415.056-3.912.58-7.387 2.526-2.833 8.916 4.777 6.508 6.547-1.423 7.447-5.46.9 4.037 2.67 11.968 7.447 5.46 4.37-5.946 1.053-8.337-2.833-8.916.139.016.277.034.415.056 2.674.297 5.572-.628 6.387-3.364.246-.828.624-5.79.624-6.478 0-.69-.139-1.861-.902-2.206-.659-.298-1.664-.62-4.3 1.24C16.046 4.748 13.087 8.687 12 10.8Z"/></svg>',
+  linkedin:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>LinkedIn</title><path fill="currentColor" d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/></svg>',
+  youtube:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>YouTube</title><path fill="currentColor" d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z"/></svg>',
+  slack:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Slack</title><path fill="currentColor" d="M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52zM6.313 15.165a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313zM8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834zM8.834 6.313a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312zM18.956 8.834a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834zM17.688 8.834a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312zM15.165 18.956a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52zM15.165 17.688a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.527 2.527 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313z"/></svg>',
+  npm:
+    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>npm</title><path fill="currentColor" d="M1.763 0C.786 0 0 .786 0 1.763v20.474C0 23.214.786 24 1.763 24h20.474c.977 0 1.763-.786 1.763-1.763V1.763C24 .786 23.214 0 22.237 0ZM5.13 5.323l13.837.019-.009 13.836h-3.464l.01-10.382h-3.456L12.04 19.17H5.113Z"/></svg>'
+}
+
+export type SocialLinkIcon = string | { svg: string }
+
+export interface SocialLink {
+  icon: SocialLinkIcon
+  link: string
+  ariaLabel?: string
+}
+
+export function socialIconSvg(icon: SocialLinkIcon): string | undefined {
+  if (typeof icon === 'object') return icon.svg
+  return SOCIAL_ICON_SVGS[icon.toLowerCase()]
+}
+
+export function socialLinkLabel(icon: SocialLinkIcon, ariaLabel?: string): string {
+  if (ariaLabel) return ariaLabel
+  if (typeof icon === 'string') return icon
+  return 'Social link'
+}

package/src/shared/tags.ts

@@ -0,0 +1,36 @@
+import { normalizeRoute } from './route.js'
+import { slugifySegment } from './slug.js'
+
+/** URL path segment for a tag (lowercase, hyphenated ASCII). */
+export function slugifyTagSegment(tag: string): string {
+  return slugifySegment(tag, '')
+}
+
+export function parseTagsField(value: unknown): string[] {
+  if (value == null) return []
+  if (typeof value === 'string') return value.trim() ? [value.trim()] : []
+  if (!Array.isArray(value)) return []
+  const out: string[] = []
+  for (const v of value) {
+    if (typeof v === 'string' && v.trim()) out.push(v.trim())
+    else if (typeof v === 'number' || typeof v === 'boolean') out.push(String(v))
+  }
+  return out
+}
+
+export function resolvePageTags(meta: Record<string, unknown>): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const tag of [...parseTagsField(meta.tags), ...parseTagsField(meta.tag)]) {
+    const slug = slugifyTagSegment(tag)
+    if (!slug || seen.has(slug)) continue
+    seen.add(slug)
+    out.push(tag.trim())
+  }
+  return out
+}
+
+export function tagIndexPageRoute(slug: string, prefix = ''): string {
+  const cleanPrefix = prefix ? normalizeRoute(prefix) : ''
+  return normalizeRoute(`${cleanPrefix}/tags/${slug}`)
+}

package/src/shared/theme.ts

@@ -0,0 +1,26 @@
+export const PREACTPRESS_THEME_STORAGE_KEY = 'preactpress-theme' as const
+export const PREACTPRESS_THEME_SCRIPT = 'preactpress-theme.js' as const
+
+export type PreactpressStoredTheme = 'light' | 'dark'
+
+export function readStoredTheme(): PreactpressStoredTheme | null {
+  if (typeof localStorage === 'undefined') return null
+  try {
+    const v = localStorage.getItem(PREACTPRESS_THEME_STORAGE_KEY)
+    return v === 'light' || v === 'dark' ? v : null
+  } catch {
+    return null
+  }
+}
+
+export function applyTheme(theme: PreactpressStoredTheme | null): void {
+  if (typeof document === 'undefined') return
+  const root = document.documentElement
+  if (theme === null) root.removeAttribute('data-theme')
+  else root.setAttribute('data-theme', theme)
+}
+
+/** Synced into dev `index.html` (via Vite plugin) and production HTML (`build.ts`) before first paint. */
+export const PREACTPRESS_THEME_BOOT_SCRIPT = `(function(){try{var k=${JSON.stringify(
+  PREACTPRESS_THEME_STORAGE_KEY
+)};var m=localStorage.getItem(k);if(m==='light'||m==='dark')document.documentElement.setAttribute('data-theme',m);}catch(e){}})();`

package/src/shared/themeLabels.ts

@@ -0,0 +1,72 @@
+import type { ThemeLabels } from '../node/siteConfig.js'
+
+export interface ResolvedThemeLabels {
+  skip: string
+  navigation: string
+  menu: string
+  closeMenu: string
+  search: string
+  filterPages: string
+  searchResults: string
+  previous: string
+  next: string
+  lastUpdated: string
+  onThisPage: string
+  language: string
+}
+
+const EN_LABELS: ResolvedThemeLabels = {
+  skip: 'Skip to content',
+  navigation: 'Navigation',
+  menu: 'Menu',
+  closeMenu: 'Close menu',
+  search: 'Search',
+  filterPages: 'Filter pages',
+  searchResults: 'Search results',
+  previous: 'Previous',
+  next: 'Next',
+  lastUpdated: 'Last updated',
+  onThisPage: 'On this page',
+  language: 'Language'
+}
+
+const DE_LABELS: ResolvedThemeLabels = {
+  skip: 'Zum Inhalt springen',
+  navigation: 'Navigation',
+  menu: 'Menü',
+  closeMenu: 'Menü schließen',
+  search: 'Suche',
+  filterPages: 'Seiten filtern',
+  searchResults: 'Suchergebnisse',
+  previous: 'Zurück',
+  next: 'Weiter',
+  lastUpdated: 'Zuletzt aktualisiert',
+  onThisPage: 'Auf dieser Seite',
+  language: 'Sprache'
+}
+
+export function defaultLabelsForLang(lang: string): ResolvedThemeLabels {
+  return lang.toLowerCase().startsWith('de') ? DE_LABELS : EN_LABELS
+}
+
+export function resolveThemeLabels(
+  lang: string,
+  overrides: ThemeLabels | undefined
+): ResolvedThemeLabels {
+  const defaults = defaultLabelsForLang(lang)
+  if (!overrides) return defaults
+  return {
+    skip: overrides.skip ?? defaults.skip,
+    navigation: overrides.navigation ?? defaults.navigation,
+    menu: overrides.menu ?? defaults.menu,
+    closeMenu: overrides.closeMenu ?? defaults.closeMenu,
+    search: overrides.search ?? defaults.search,
+    filterPages: overrides.filterPages ?? defaults.filterPages,
+    searchResults: overrides.searchResults ?? defaults.searchResults,
+    previous: overrides.previous ?? defaults.previous,
+    next: overrides.next ?? defaults.next,
+    lastUpdated: overrides.lastUpdated ?? defaults.lastUpdated,
+    onThisPage: overrides.onThisPage ?? defaults.onThisPage,
+    language: overrides.language ?? defaults.language
+  }
+}

package/src/shared/url.ts

@@ -0,0 +1,14 @@
+export function publicUrl(siteBase: string, file: string): string {
+  const b = siteBase === '/' ? '' : siteBase.replace(/\/$/, '')
+  const f = file.startsWith('/') ? file : `/${file}`
+  return `${b}${f}`
+}
+
+export function canonicalUrl(opts: {
+  url?: string
+  base: string
+  route: string
+}): string {
+  const path = publicUrl(opts.base, opts.route === '/' ? '/' : `${opts.route}/`)
+  return opts.url ? `${opts.url}${path}` : path
+}

package/templates/default/.preactpress/config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from '@kamod-ch/preactpress/config'
+
+export default defineConfig({
+  srcExclude: ['README.md', 'partials/**', 'parts/**'],
+  site: {
+    title: 'My PreactPress Site',
+    description: 'A simple static site built with PreactPress'
+  },
+  markdown: {
+    html: false
+  },
+  themeConfig: {
+    outline: true,
+    search: true,
+    footer: 'Built with PreactPress.',
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'About', link: '/about' }
+    ],
+    sidebar: [
+      {
+        text: 'Start',
+        items: [
+          { text: 'Home', link: '/' },
+          { text: 'About', link: '/about' },
+          { text: 'Your first 5 minutes', link: '/guide/first-five-minutes' }
+        ]
+      }
+    ]
+  }
+})

package/templates/default/README.md

@@ -0,0 +1,45 @@
+# PreactPress starter site
+
+This folder was scaffolded with `preactpress init`. It is the minimal starter: a home page, an about page, and one short guide.
+
+## Commands
+
+| Script | What it does |
+| --- | --- |
+| `pnpm run dev` | Start the dev server at http://localhost:5173 |
+| `pnpm run check` | Validate config, routes, and links |
+| `pnpm run build` | Write static HTML to `dist/` |
+| `pnpm run preview` | Serve the production build locally |
+
+## Where to edit
+
+| Path | Purpose |
+| --- | --- |
+| `*.md`, `*.mdx` | Page content — file path becomes the URL |
+| `.preactpress/config.ts` | Site title, nav, sidebar, build options |
+| `index.html` | Vite entry (rarely edited) |
+
+## Layout examples
+
+The default starter shows all built-in default-theme layouts:
+
+| File | Layout |
+| --- | --- |
+| `index.md` | `layout: home` |
+| `about.md` | `layout: page` |
+| `guide/first-five-minutes.md` | `layout: doc` |
+
+Start with [Your first 5 minutes](/guide/first-five-minutes) in the local site, or read the full PreactPress README in the npm package / repository.
+
+For a larger documentation starter, run `preactpress init --template docs`. For a custom magazine-style theme, run `preactpress init --template magazine`.
+
+## Deploy
+
+```bash
+pnpm run check
+pnpm run build
+```
+
+Upload **only** `dist/` to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any static host. No Node server is required in production.
+
+Before the first production build, set `site.url` (and `site.base` for subpath hosting) in `.preactpress/config.ts`.

package/templates/default/about.md

@@ -0,0 +1,11 @@
+---
+title: About
+description: About this site
+layout: page
+---
+
+# About us
+
+Your content here.
+
+This page was added as part of the [Your first 5 minutes](/guide/first-five-minutes) tutorial. Replace this text with your own copy — team bio, project mission, contact details, or anything else that belongs on an About page.

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

@@ -0,0 +1,83 @@
+---
+title: Your first 5 minutes
+description: Change the site title, add a page, and update navigation
+layout: doc
+---
+
+# Your first 5 minutes
+
+This hands-on tutorial walks through the smallest useful PreactPress workflow. Follow the steps below in **your** project — this starter already includes the finished 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`. Read the package README for routing, MDX, deployment, and custom theme details.

package/templates/default/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/default/index.md

@@ -0,0 +1,55 @@
+---
+title: Welcome
+description: Get started with PreactPress in minutes
+layout: home
+hero:
+  name: PreactPress
+  text: Vite and Preact powered static sites
+  tagline: Write Markdown and MDX, configure navigation, and ship a small static documentation site.
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/first-five-minutes
+    - theme: alt
+      text: About this site
+      link: /about
+features:
+  - icon: V
+    title: Fast by default
+    details: Static HTML output, Vite dev server, and optional client navigation.
+  - icon: M
+    title: Markdown first
+    details: Frontmatter, MDX, tags, search metadata, and outline extraction.
+  - icon: T
+    title: Themeable
+    details: Use the default theme or replace it with your own Preact layout.
+---
+
+## Quick start
+
+From this folder:
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+Open **http://localhost:5173**. Edit Markdown files, adjust `.preactpress/config.ts`, and the dev server hot-reloads your changes.
+
+## What to read next
+
+| Page | Why |
+| --- | --- |
+| [Your first 5 minutes](/guide/first-five-minutes) | Change the title, add a page, wire up navigation |
+| [About](/about) | A plain content page you can replace |
+
+## What you get
+
+| Feature | Included |
+| --- | --- |
+| Static HTML build | Yes |
+| Client navigation | Yes |
+| Markdown frontmatter | Yes |
+| Sidebar search | Yes |
+
+The default template is intentionally small. Use `preactpress init --template docs` when you want a fuller documentation starter, or `preactpress init --template magazine` for a custom-theme example.

package/templates/default/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "preactpress-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"
+  }
+}