@codemeall/create-word-pages 0.1.0

package/bin/create-word-pages.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(__dirname, "..")
+const templateRoot = path.join(packageRoot, "template")
+
+const rawTarget = process.argv[2] ?? "word-pages-site"
+const targetDir = path.resolve(process.cwd(), rawTarget)
+const projectName = path.basename(targetDir)
+
+async function ensureEmptyOrCreate(dir) {
+  await mkdir(dir, { recursive: true })
+  const entries = await readdir(dir)
+  if (entries.length > 0) {
+    throw new Error(`Target directory is not empty: ${dir}`)
+  }
+}
+
+async function replacePlaceholders(filePath) {
+  const info = await stat(filePath)
+  if (!info.isFile()) return
+
+  const textExtensions = new Set([
+    ".css",
+    ".html",
+    ".js",
+    ".json",
+    ".md",
+    ".mjs",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".yml"
+  ])
+
+  if (!textExtensions.has(path.extname(filePath))) return
+
+  const source = await readFile(filePath, "utf8")
+  const updated = source.replaceAll("__WORD_PAGES_PROJECT_NAME__", projectName)
+  if (updated !== source) {
+    await writeFile(filePath, updated)
+  }
+}
+
+async function walk(dir, visitor) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      await walk(fullPath, visitor)
+    } else {
+      await visitor(fullPath)
+    }
+  }
+}
+
+try {
+  await ensureEmptyOrCreate(targetDir)
+  await cp(templateRoot, targetDir, { recursive: true })
+  await walk(targetDir, replacePlaceholders)
+
+  console.log(`Created Word Pages starter in ${targetDir}`)
+  console.log("")
+  console.log("Next steps:")
+  console.log(`  cd ${path.relative(process.cwd(), targetDir) || "."}`)
+  console.log("  npm install")
+  console.log("  npm run wizard")
+  console.log("  npm run preview")
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@codemeall/create-word-pages",
+  "version": "0.1.0",
+  "description": "Scaffold a Word Pages Obsidian-to-GitHub-Pages starter.",
+  "type": "module",
+  "bin": {
+    "create-word-pages": "./bin/create-word-pages.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10.9"
+  },
+  "license": "MIT"
+}

package/template/.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Deploy Word 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:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .word-pages/quartz/public
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

package/template/README.md

@@ -0,0 +1,54 @@
+# Word Pages Starter
+
+Word Pages publishes an Obsidian-authored Markdown vault to GitHub Pages with a Quartz-powered reading experience.
+
+## Quick Start
+
+```bash
+npm install
+npm run wizard
+npm run preview
+```
+
+Open `content/` as an Obsidian vault. Write pages, posts, and notes there. A Markdown file is rendered only when it has `publish: true` in frontmatter.
+
+Important: `publish: true` controls whether the generated site renders a page. It does not make committed source Markdown private. If this repository is public, committed files can be visible on GitHub even when they are not rendered.
+
+## Content Contract
+
+Use frontmatter to classify content:
+
+```yaml
+---
+title: "My post"
+type: post
+publish: true
+date: 2026-06-06
+tags:
+  - writing
+---
+```
+
+Supported types:
+
+- `page`: routed to `/` when `slug: index` or `slug: home`; otherwise routed to `/:slug/`.
+- `post`: routed to `/posts/:slug/`.
+- `note`: routed to `/notes/:slug/`.
+
+Wikilinks, backlinks, graph view, tags, search, and dark/light mode are provided by Quartz.
+
+## GitHub Pages
+
+The included workflow builds the site with GitHub Actions and publishes the generated `public/` folder. For project Pages, set your GitHub username and repository name in the wizard so the Quartz `baseUrl` is correct. Quartz expects this value without protocol or slashes, for example `octocat.github.io/my-site`.
+
+Custom domains are supported by GitHub Pages, but Word Pages v1 only documents that workflow and does not automate DNS setup.
+
+## Import Jekyll Posts
+
+To import an existing Jekyll `_posts` folder:
+
+```bash
+npm run import:jekyll -- /path/to/site/_posts
+```
+
+The importer copies Markdown files into `content/posts`, preserves common frontmatter, adds `type: post`, and adds `publish: true`.

package/template/content/notes/publishing-model.md

@@ -0,0 +1,19 @@
+---
+title: "Publishing Model"
+type: note
+slug: publishing-model
+publish: true
+tags:
+  - docs
+  - github-pages
+---
+
+# Publishing Model
+
+Word Pages stages publishable notes into Quartz routes before building the static site.
+
+- `page` content becomes top-level pages.
+- `post` content becomes `/posts/:slug/`.
+- `note` content becomes `/notes/:slug/`.
+
+Only files with `publish: true` are rendered. Source privacy still depends on repository visibility.

package/template/content/pages/about.md

@@ -0,0 +1,14 @@
+---
+title: "About"
+type: page
+slug: about
+publish: true
+tags:
+  - portfolio
+---
+
+# About
+
+Add your profile, services, contact links, or agency positioning here.
+
+Word Pages keeps the public site static and lets GitHub Pages host it from your repository.

package/template/content/pages/home.md

@@ -0,0 +1,16 @@
+---
+title: "Home"
+type: page
+slug: index
+publish: true
+tags:
+  - portfolio
+---
+
+# Word Pages
+
+This is your public home page. Open the `content/` folder in Obsidian and edit this note.
+
+Use this space for a calm portfolio introduction, featured writing, client knowledge base links, or a personal digital garden.
+
+Start with [[notes/publishing-model|the publishing model]] or read the sample [[posts/launching-word-pages|launch post]].

package/template/content/posts/launching-word-pages.md

@@ -0,0 +1,16 @@
+---
+title: "Launching Word Pages"
+type: post
+slug: launching-word-pages
+publish: true
+date: 2026-06-06
+tags:
+  - writing
+  - word-pages
+---
+
+# Launching Word Pages
+
+This sample post shows the blog side of your Obsidian vault.
+
+Posts are routed under `/posts/` and can link to notes like [[notes/publishing-model|Publishing Model]].

package/template/content/templates/post.md

@@ -0,0 +1,12 @@
+---
+title: ""
+type: post
+slug: ""
+publish: false
+date: 2026-06-06
+tags: []
+---
+
+# Untitled Post
+
+Write in Obsidian, then set `publish: true` when ready.

package/template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "__WORD_PAGES_PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "wizard": "vite --host 127.0.0.1 --config wizard/vite.config.ts",
+    "prepare:content": "node scripts/prepare-quartz-content.mjs",
+    "import:jekyll": "node scripts/import-jekyll-posts.mjs",
+    "quartz:install": "node scripts/install-quartz.mjs",
+    "build": "npm run prepare:content && npm run quartz:install && node scripts/run-quartz.mjs build -d ../quartz-content -o public",
+    "preview": "npm run prepare:content && npm run quartz:install && node scripts/run-quartz.mjs build -d ../quartz-content --serve",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^5.0.0",
+    "vite": "^7.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10.9"
+  },
+  "wordPages": {
+    "quartzRepository": "https://github.com/jackyzha0/quartz.git"
+  }
+}

package/template/quartz.config.ts

@@ -0,0 +1,78 @@
+import { QuartzConfig } from "./quartz/cfg"
+import * as Plugin from "./quartz/plugins"
+
+const config: QuartzConfig = {
+  configuration: {
+    pageTitle: __WORD_PAGES_TITLE__,
+    enableSPA: true,
+    enablePopovers: true,
+    analytics: null,
+    locale: "en-US",
+    baseUrl: __WORD_PAGES_BASE_URL__,
+    ignorePatterns: ["private", "templates", ".obsidian"],
+    defaultDateType: "modified",
+    theme: {
+      fontOrigin: "googleFonts",
+      cdnCaching: true,
+      typography: {
+        header: "Schibsted Grotesk",
+        body: "Source Sans 3",
+        code: "IBM Plex Mono"
+      },
+      colors: {
+        lightMode: {
+          light: "#faf8f3",
+          lightgray: "#e5e0d5",
+          gray: "#8a8376",
+          darkgray: "#3e3a33",
+          dark: "#171613",
+          secondary: "#28786f",
+          tertiary: "#8d5c2c",
+          highlight: "rgba(40, 120, 111, 0.14)",
+          textHighlight: "#fff0a8"
+        },
+        darkMode: {
+          light: "#181816",
+          lightgray: "#2a2a26",
+          gray: "#aaa394",
+          darkgray: "#ddd8cb",
+          dark: "#f8f3e7",
+          secondary: "#73c6b6",
+          tertiary: "#d39b63",
+          highlight: "rgba(115, 198, 182, 0.16)",
+          textHighlight: "#5e4d18"
+        }
+      }
+    }
+  },
+  plugins: {
+    transformers: [
+      Plugin.FrontMatter(),
+      Plugin.CreatedModifiedDate({ priority: ["frontmatter", "filesystem"] }),
+      Plugin.SyntaxHighlighting(),
+      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
+      Plugin.GitHubFlavoredMarkdown(),
+      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
+      Plugin.Description(),
+      Plugin.Latex({ renderEngine: "katex" })
+    ],
+    filters: [
+      Plugin.ExplicitPublish()
+    ],
+    emitters: [
+      Plugin.AliasRedirects(),
+      Plugin.ComponentResources(),
+      Plugin.ContentPage(),
+      Plugin.FolderPage(),
+      Plugin.TagPage(),
+      Plugin.ContentIndex({
+        enableSiteMap: true,
+        enableRSS: true
+      }),
+      Plugin.Assets(),
+      Plugin.Static()
+    ]
+  }
+}
+
+export default config

package/template/scripts/frontmatter.mjs

@@ -0,0 +1,98 @@
+export function parseFrontmatter(source) {
+  if (!source.startsWith("---\n")) {
+    return { data: {}, content: source }
+  }
+
+  const end = source.indexOf("\n---", 4)
+  if (end === -1) {
+    return { data: {}, content: source }
+  }
+
+  const yaml = source.slice(4, end)
+  const content = source.slice(end + 4).replace(/^\n/, "")
+  return { data: parseYaml(yaml), content }
+}
+
+export function stringifyFrontmatter(content, data) {
+  return `---\n${stringifyYaml(data)}---\n\n${content.trimStart()}`
+}
+
+function parseYaml(yaml) {
+  const data = {}
+  const lines = yaml.split("\n")
+  let index = 0
+
+  while (index < lines.length) {
+    const line = lines[index]
+    if (!line.trim()) {
+      index += 1
+      continue
+    }
+
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!match) {
+      index += 1
+      continue
+    }
+
+    const [, key, rawValue] = match
+    if (rawValue === "") {
+      const values = []
+      let cursor = index + 1
+      while (cursor < lines.length) {
+        const item = lines[cursor].match(/^\s*-\s*(.*)$/)
+        if (!item) break
+        values.push(parseScalar(item[1]))
+        cursor += 1
+      }
+      data[key] = values
+      index = cursor
+      continue
+    }
+
+    data[key] = parseScalar(rawValue)
+    index += 1
+  }
+
+  return data
+}
+
+function parseScalar(raw) {
+  const value = raw.trim()
+  if (value === "true") return true
+  if (value === "false") return false
+  if (value === "[]") return []
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return value
+      .slice(1, -1)
+      .split(",")
+      .map((item) => parseScalar(item))
+      .filter((item) => item !== "")
+  }
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+function stringifyYaml(data) {
+  return Object.entries(data)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        if (value.length === 0) return `${key}: []\n`
+        return `${key}:\n${value.map((item) => `  - ${formatScalar(item)}`).join("\n")}\n`
+      }
+      return `${key}: ${formatScalar(value)}\n`
+    })
+    .join("")
+}
+
+function formatScalar(value) {
+  if (typeof value === "boolean") return value ? "true" : "false"
+  const text = String(value)
+  if (!text || /[:#\n{}[\],&*?|<>=!%@`]/.test(text)) {
+    return JSON.stringify(text)
+  }
+  return text
+}

package/template/scripts/import-jekyll-posts.mjs

@@ -0,0 +1,55 @@
+import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.mjs"
+
+const source = process.argv[2]
+if (!source) {
+  console.error("Usage: npm run import:jekyll -- /path/to/site/_posts")
+  process.exit(1)
+}
+
+const root = process.cwd()
+const destination = path.join(root, "content", "posts")
+await mkdir(destination, { recursive: true })
+
+function slugFromJekyllName(fileName) {
+  return fileName
+    .replace(/^\d{4}-\d{2}-\d{2}-/, "")
+    .replace(/\.md$/i, "")
+}
+
+const files = (await readdir(source)).filter((file) => file.endsWith(".md"))
+let imported = 0
+
+for (const file of files) {
+  const fullPath = path.join(source, file)
+  const raw = await readFile(fullPath, "utf8")
+  const parsed = parseFrontmatter(raw)
+  const slug = parsed.data.slug ?? slugFromJekyllName(file)
+
+  const data = {
+    ...parsed.data,
+    type: "post",
+    publish: true,
+    slug,
+    title: parsed.data.title ?? slug.replaceAll("-", " "),
+    date: parsed.data.date ?? file.slice(0, 10)
+  }
+
+  delete data.layout
+  delete data.permalink
+
+  const outputPath = path.join(destination, `${slug}.md`)
+  await writeFile(outputPath, stringifyFrontmatter(parsed.content.trimStart(), data))
+  imported += 1
+}
+
+const assetSource = path.resolve(source, "..", "assets")
+try {
+  await cp(assetSource, path.join(root, "content", "assets"), { recursive: true, force: true })
+  console.log("Copied assets into content/assets.")
+} catch {
+  console.log("No sibling assets folder copied.")
+}
+
+console.log(`Imported ${imported} Jekyll posts into content/posts.`)

package/template/scripts/install-quartz.mjs

@@ -0,0 +1,63 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises"
+import { spawn } from "node:child_process"
+import path from "node:path"
+
+const root = process.cwd()
+const quartzDir = path.join(root, ".word-pages", "quartz")
+const npmCache = path.join(root, ".word-pages", "npm-cache")
+const quartzRepo = "https://github.com/jackyzha0/quartz.git"
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: "inherit",
+      ...options
+    })
+    child.on("exit", (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${command} ${args.join(" ")} exited with ${code}`))
+    })
+  })
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+if (!await exists(path.join(quartzDir, "package.json"))) {
+  await mkdir(path.dirname(quartzDir), { recursive: true })
+  await run("git", ["clone", "--depth", "1", quartzRepo, quartzDir])
+}
+
+if (!await exists(path.join(quartzDir, "node_modules"))) {
+  await mkdir(npmCache, { recursive: true })
+  await run("npm", ["install"], {
+    cwd: quartzDir,
+    env: {
+      ...process.env,
+      npm_config_cache: npmCache
+    }
+  })
+}
+
+const config = JSON.parse(await readFile(path.join(root, "word-pages.config.json"), "utf8"))
+const configTemplate = await readFile(path.join(root, "quartz.config.ts"), "utf8")
+const renderedConfig = configTemplate
+  .replaceAll("__WORD_PAGES_TITLE__", JSON.stringify(config.site.title))
+  .replaceAll("__WORD_PAGES_BASE_URL__", JSON.stringify(config.site.baseUrl))
+
+await writeFile(path.join(quartzDir, "quartz.config.ts"), renderedConfig)
+await run("npm", ["exec", "quartz", "--", "plugin", "install", "--from-config"], {
+  cwd: quartzDir,
+  env: {
+    ...process.env,
+    npm_config_cache: npmCache
+  }
+})
+
+console.log(`Quartz is ready at ${quartzDir}.`)

package/template/scripts/prepare-quartz-content.mjs

@@ -0,0 +1,80 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.mjs"
+
+const root = process.cwd()
+const config = JSON.parse(await readFile(path.join(root, "word-pages.config.json"), "utf8"))
+const sourceRoot = path.join(root, config.content.source)
+const stagedRoot = path.join(root, config.content.staged)
+
+const allowedTypes = new Set(["page", "post", "note"])
+
+function slugify(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+async function collectMarkdown(dir) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = []
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === ".obsidian") continue
+      files.push(...await collectMarkdown(fullPath))
+    } else if (entry.name.endsWith(".md")) {
+      files.push(fullPath)
+    }
+  }
+  return files
+}
+
+function routeFor(filePath, data) {
+  const type = String(data.type ?? "").toLowerCase()
+  if (!allowedTypes.has(type)) {
+    throw new Error(`${filePath} has unsupported type "${data.type}". Use page, post, or note.`)
+  }
+
+  const fallbackSlug = slugify(data.title ?? path.basename(filePath, ".md"))
+  const slug = slugify(data.slug ?? fallbackSlug)
+  if (!slug) throw new Error(`${filePath} needs a title or slug.`)
+
+  if (type === "post") return path.join("posts", `${slug}.md`)
+  if (type === "note") return path.join("notes", `${slug}.md`)
+  if (slug === "index" || slug === "home") return "index.md"
+  return `${slug}.md`
+}
+
+await rm(stagedRoot, { recursive: true, force: true })
+await mkdir(stagedRoot, { recursive: true })
+
+const files = await collectMarkdown(sourceRoot)
+let published = 0
+
+for (const file of files) {
+  const raw = await readFile(file, "utf8")
+  const parsed = parseFrontmatter(raw)
+  if (parsed.data.publish !== true) continue
+
+  const relativeOutput = routeFor(file, parsed.data)
+  const outputPath = path.join(stagedRoot, relativeOutput)
+  await mkdir(path.dirname(outputPath), { recursive: true })
+
+  const data = {
+    ...parsed.data,
+    title: parsed.data.title ?? path.basename(file, ".md")
+  }
+
+  await writeFile(outputPath, stringifyFrontmatter(parsed.content.trimStart(), data))
+  published += 1
+}
+
+if (published === 0) {
+  throw new Error("No publishable Markdown files found. Add publish: true to at least one content file.")
+}
+
+console.log(`Prepared ${published} publishable Markdown files for Quartz.`)

package/template/scripts/run-quartz.mjs

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process"
+import path from "node:path"
+
+const root = process.cwd()
+const quartzDir = path.join(root, ".word-pages", "quartz")
+const npmCache = path.join(root, ".word-pages", "npm-cache")
+const args = process.argv.slice(2)
+
+const child = spawn("npm", ["exec", "quartz", "--", ...args], {
+  cwd: quartzDir,
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    npm_config_cache: npmCache
+  }
+})
+
+child.on("exit", (code) => {
+  process.exit(code ?? 1)
+})

package/template/wizard/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Word Pages Wizard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/wizard/src/main.tsx

@@ -0,0 +1,144 @@
+import React, { useEffect, useMemo, useState } from "react"
+import { createRoot } from "react-dom/client"
+import "./styles.css"
+
+type WordPagesConfig = {
+  site: {
+    title: string
+    description: string
+    author: string
+    githubUsername: string
+    repositoryName: string
+    visibility: "ask" | "public" | "private"
+    baseUrl: string
+  }
+  theme: {
+    preset: string
+  }
+  content: {
+    source: string
+    staged: string
+  }
+}
+
+function deriveBaseUrl(username: string, repositoryName: string) {
+  if (!username || !repositoryName) return ""
+  if (repositoryName.toLowerCase() === `${username.toLowerCase()}.github.io`) return `${username}.github.io`
+  return `${username}.github.io/${repositoryName}`
+}
+
+function displayPagesUrl(baseUrl: string) {
+  return baseUrl ? `https://${baseUrl}/` : "Configure GitHub details to preview the Pages URL."
+}
+
+function App() {
+  const [config, setConfig] = useState<WordPagesConfig | null>(null)
+  const [status, setStatus] = useState("Loading")
+
+  useEffect(() => {
+    fetch("/api/config")
+      .then((response) => response.json())
+      .then((data) => {
+        setConfig(data)
+        setStatus("Ready")
+      })
+      .catch(() => setStatus("Could not load configuration"))
+  }, [])
+
+  const pageUrl = useMemo(() => {
+    if (!config?.site.githubUsername || !config.site.repositoryName) return "Configure GitHub details to preview the Pages URL."
+    return displayPagesUrl(deriveBaseUrl(config.site.githubUsername, config.site.repositoryName))
+  }, [config])
+
+  if (!config) {
+    return <main className="shell"><p>{status}</p></main>
+  }
+
+  function updateSite<K extends keyof WordPagesConfig["site"]>(key: K, value: WordPagesConfig["site"][K]) {
+    setConfig((current) => current && {
+      ...current,
+      site: {
+        ...current.site,
+        [key]: value,
+        baseUrl: key === "githubUsername" || key === "repositoryName"
+          ? deriveBaseUrl(
+            key === "githubUsername" ? String(value) : current.site.githubUsername,
+            key === "repositoryName" ? String(value) : current.site.repositoryName
+          )
+          : current.site.baseUrl
+      }
+    })
+  }
+
+  async function save() {
+    setStatus("Saving")
+    const response = await fetch("/api/config", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(config)
+    })
+    setStatus(response.ok ? "Saved" : "Save failed")
+  }
+
+  return (
+    <main className="shell">
+      <section className="hero">
+        <div>
+          <p className="eyebrow">Word Pages setup</p>
+          <h1>Configure your Obsidian-powered site.</h1>
+          <p className="lede">This wizard writes local configuration only. It does not ask for GitHub credentials and does not upload your vault.</p>
+        </div>
+        <button onClick={save}>Save</button>
+      </section>
+
+      <section className="grid">
+        <label>
+          Site title
+          <input value={config.site.title} onChange={(event) => updateSite("title", event.target.value)} />
+        </label>
+        <label>
+          Author or organization
+          <input value={config.site.author} onChange={(event) => updateSite("author", event.target.value)} />
+        </label>
+        <label className="wide">
+          Description
+          <textarea value={config.site.description} onChange={(event) => updateSite("description", event.target.value)} />
+        </label>
+        <label>
+          GitHub username
+          <input value={config.site.githubUsername} onChange={(event) => updateSite("githubUsername", event.target.value)} />
+        </label>
+        <label>
+          Repository name
+          <input value={config.site.repositoryName} onChange={(event) => updateSite("repositoryName", event.target.value)} />
+        </label>
+        <label>
+          Repository visibility
+          <select value={config.site.visibility} onChange={(event) => updateSite("visibility", event.target.value as WordPagesConfig["site"]["visibility"])}>
+            <option value="ask">Decide before publishing</option>
+            <option value="public">Public</option>
+            <option value="private">Private</option>
+          </select>
+        </label>
+        <label>
+          GitHub Pages base URL
+          <input value={config.site.baseUrl} onChange={(event) => updateSite("baseUrl", event.target.value)} />
+        </label>
+      </section>
+
+      <section className="notice">
+        <h2>Publishing boundary</h2>
+        <p><strong>Rendered site:</strong> only Markdown with <code>publish: true</code> is staged for Quartz.</p>
+        <p><strong>Repository source:</strong> if this repo is public, committed Markdown may be visible on GitHub even when it is not rendered.</p>
+        <p><strong>Expected Pages URL:</strong> {pageUrl}</p>
+      </section>
+
+      <footer>
+        <span>{status}</span>
+        <span>Next: open <code>content/</code> in Obsidian, then run <code>npm run preview</code>.</span>
+      </footer>
+    </main>
+  )
+}
+
+createRoot(document.getElementById("root")!).render(<App />)

package/template/wizard/src/styles.css

@@ -0,0 +1,132 @@
+:root {
+  color: #1d1b16;
+  background: #f9f6ee;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+.shell {
+  width: min(1040px, calc(100vw - 32px));
+  margin: 0 auto;
+  padding: 40px 0;
+}
+
+.hero {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: 24px;
+  padding-bottom: 28px;
+  border-bottom: 1px solid #ded8ca;
+}
+
+.eyebrow {
+  margin: 0 0 10px;
+  color: #28786f;
+  font-size: 0.82rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+h1 {
+  max-width: 720px;
+  margin: 0;
+  font-size: clamp(2rem, 4vw, 3.7rem);
+  line-height: 1.02;
+}
+
+.lede {
+  max-width: 650px;
+  color: #5f594f;
+  font-size: 1.05rem;
+}
+
+button {
+  min-height: 44px;
+  border: 0;
+  border-radius: 6px;
+  padding: 0 20px;
+  color: white;
+  background: #28786f;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px;
+  margin: 28px 0;
+}
+
+label {
+  display: grid;
+  gap: 8px;
+  color: #413d35;
+  font-weight: 700;
+}
+
+.wide {
+  grid-column: 1 / -1;
+}
+
+input,
+select,
+textarea {
+  width: 100%;
+  border: 1px solid #cfc7b7;
+  border-radius: 6px;
+  padding: 12px;
+  color: #1d1b16;
+  background: #fffdf8;
+  font: inherit;
+}
+
+textarea {
+  min-height: 104px;
+  resize: vertical;
+}
+
+.notice {
+  border: 1px solid #ded8ca;
+  border-radius: 8px;
+  padding: 20px;
+  background: #fffdf8;
+}
+
+.notice h2 {
+  margin-top: 0;
+}
+
+code {
+  border-radius: 4px;
+  padding: 2px 5px;
+  background: #ece6d8;
+}
+
+footer {
+  display: flex;
+  justify-content: space-between;
+  gap: 20px;
+  margin-top: 24px;
+  color: #6f675c;
+}
+
+@media (max-width: 720px) {
+  .hero,
+  footer {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}

package/template/wizard/vite.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react"
+import { readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+const configPath = path.resolve(process.cwd(), "word-pages.config.json")
+
+export default defineConfig({
+  root: "wizard",
+  plugins: [
+    react(),
+    {
+      name: "word-pages-config-api",
+      configureServer(server) {
+        server.middlewares.use("/api/config", async (req, res) => {
+          if (req.method === "GET") {
+            const body = await readFile(configPath, "utf8")
+            res.setHeader("Content-Type", "application/json")
+            res.end(body)
+            return
+          }
+
+          if (req.method === "POST") {
+            let raw = ""
+            req.on("data", (chunk) => {
+              raw += chunk
+            })
+            req.on("end", async () => {
+              const parsed = JSON.parse(raw)
+              await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`)
+              res.setHeader("Content-Type", "application/json")
+              res.end(JSON.stringify({ ok: true }))
+            })
+            return
+          }
+
+          res.statusCode = 405
+          res.end("Method not allowed")
+        })
+      }
+    }
+  ]
+})

package/template/word-pages.config.json

@@ -0,0 +1,18 @@
+{
+  "site": {
+    "title": "Word Pages",
+    "description": "A public knowledge base, blog, and portfolio managed from Obsidian.",
+    "author": "Your Name",
+    "githubUsername": "",
+    "repositoryName": "__WORD_PAGES_PROJECT_NAME__",
+    "visibility": "ask",
+    "baseUrl": "/"
+  },
+  "theme": {
+    "preset": "clean-garden"
+  },
+  "content": {
+    "source": "content",
+    "staged": ".word-pages/quartz-content"
+  }
+}