@codemeall/create-word-pages 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,116 @@
+# Word Pages
+
+Word Pages turns an Obsidian-authored Markdown vault into a Quartz-powered portfolio, blog, and knowledge-base site that can be deployed to GitHub Pages.
+
+It is designed for people who want to manage content locally in Obsidian, keep source files in GitHub, and publish a static public site without paid sync or hosted storage.
+
+## Quick Start
+
+Requirements:
+
+- Node.js 22 or newer
+- npm 10.9 or newer
+- A GitHub account
+- Obsidian, optional but recommended
+
+Create a new site:
+
+```bash
+npx @codemeall/create-word-pages my-site
+cd my-site
+npm install
+npm run wizard
+npm run preview
+```
+
+Open the `content/` folder in Obsidian and start editing.
+
+## How Publishing Works
+
+Word Pages uses `content/` as the Obsidian vault. Markdown files render only when they include:
+
+```yaml
+---
+title: "My page"
+type: note
+publish: true
+---
+```
+
+Supported content types:
+
+- `page`: portfolio/home/about pages
+- `post`: blog posts under `/posts/`
+- `note`: knowledge-base notes under `/notes/`
+
+The generated site is built by Quartz and can be deployed by the included GitHub Actions workflow.
+
+## GitHub Pages Setup
+
+1. Create a new GitHub repository.
+2. Push the generated site folder to that repository.
+3. In GitHub, open `Settings -> Pages`.
+4. Set the source to `GitHub Actions`.
+5. Push to `main`.
+
+The included workflow builds and deploys the site automatically.
+
+For project pages, run the wizard and set your GitHub username and repository name so the site URL is configured correctly.
+
+## Privacy Rule
+
+`publish: true` means “render this file into the public website.”
+
+It does not make the Markdown source private. If the GitHub repository is public, committed Markdown files may be visible on GitHub even when they are not rendered.
+
+For private drafts, use a private repository or keep drafts outside the published repo.
+
+## Import Existing Jekyll Posts
+
+If you have a Jekyll blog with `_posts`, import it like this:
+
+```bash
+npm run import:jekyll -- /path/to/site/_posts
+```
+
+The importer copies posts into `content/posts`, adds `type: post`, adds `publish: true`, and preserves common frontmatter such as title, date, tags, category, and description.
+
+## Common Commands
+
+```bash
+npm run wizard
+```
+
+Configure site identity, GitHub Pages URL details, and visibility guidance.
+
+```bash
+npm run preview
+```
+
+Build and serve the site locally.
+
+```bash
+npm run build
+```
+
+Build the static site for production.
+
+```bash
+npm run prepare:content
+```
+
+Stage only publishable Markdown into the Quartz build input.
+
+## Client Handoff Checklist
+
+- Create the site with `npx @codemeall/create-word-pages client-site`.
+- Run the wizard and set the correct GitHub username and repository name.
+- Open `content/` in Obsidian.
+- Replace the sample home, about, post, and note files.
+- Commit and push to GitHub.
+- Enable GitHub Pages with GitHub Actions.
+- Confirm the first deployment succeeds.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemeall/create-word-pages",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold a Word Pages Obsidian-to-GitHub-Pages starter.",
   "type": "module",
   "bin": {
@@ -18,4 +18,4 @@
     "npm": ">=10.9"
   },
   "license": "MIT"
-}
+}

package/template/wizard/src/main.tsx

@@ -2,6 +2,8 @@ import React, { useEffect, useMemo, useState } from "react"
 import { createRoot } from "react-dom/client"
 import "./styles.css"
 
+type SaveState = "idle" | "dirty" | "saving" | "saved" | "failed"
+
 type WordPagesConfig = {
   site: {
     title: string
@@ -34,15 +36,26 @@ function displayPagesUrl(baseUrl: string) {
 function App() {
   const [config, setConfig] = useState<WordPagesConfig | null>(null)
   const [status, setStatus] = useState("Loading")
+  const [saveState, setSaveState] = useState<SaveState>("idle")
+  const [message, setMessage] = useState("Load the wizard, edit settings, then save.")
+  const [lastSavedAt, setLastSavedAt] = useState("")
 
   useEffect(() => {
     fetch("/api/config")
-      .then((response) => response.json())
+      .then((response) => {
+        if (!response.ok) throw new Error("Could not load word-pages.config.json")
+        return response.json()
+      })
       .then((data) => {
         setConfig(data)
         setStatus("Ready")
+        setMessage("Configuration loaded from word-pages.config.json.")
+      })
+      .catch((error) => {
+        setStatus("Could not load configuration")
+        setSaveState("failed")
+        setMessage(error instanceof Error ? error.message : "Restart npm run wizard from the site root.")
       })
-      .catch(() => setStatus("Could not load configuration"))
   }, [])
 
   const pageUrl = useMemo(() => {
@@ -51,7 +64,16 @@ function App() {
   }, [config])
 
   if (!config) {
-    return <main className="shell"><p>{status}</p></main>
+    return (
+      <main className="shell">
+        <section className={`status-panel ${saveState}`} role="status" aria-live="polite">
+          <div>
+            <strong>{status}</strong>
+            <p>{message}</p>
+          </div>
+        </section>
+      </main>
+    )
   }
 
   function updateSite<K extends keyof WordPagesConfig["site"]>(key: K, value: WordPagesConfig["site"][K]) {
@@ -68,16 +90,36 @@ function App() {
           : current.site.baseUrl
       }
     })
+    setSaveState("dirty")
+    setMessage("Unsaved changes. Click Save changes to write word-pages.config.json.")
   }
 
   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")
+    try {
+      setStatus("Saving")
+      setSaveState("saving")
+      setMessage("Saving word-pages.config.json...")
+
+      const response = await fetch("/api/config", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(config)
+      })
+      const result = await response.json().catch(() => ({ message: "No response body" }))
+      if (!response.ok || result.ok === false) {
+        throw new Error(result.message ?? "Save failed")
+      }
+
+      const savedAt = new Date().toLocaleTimeString()
+      setStatus("Saved")
+      setSaveState("saved")
+      setLastSavedAt(savedAt)
+      setMessage(`Saved to word-pages.config.json at ${savedAt}. Run npm run preview in another terminal to rebuild the site.`)
+    } catch (error) {
+      setStatus("Save failed")
+      setSaveState("failed")
+      setMessage(error instanceof Error ? error.message : "Save failed")
+    }
   }
 
   return (
@@ -88,7 +130,17 @@ function App() {
           <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>
+        <button type="button" onClick={save} disabled={saveState === "saving"}>
+          {saveState === "saving" ? "Saving..." : "Save changes"}
+        </button>
+      </section>
+
+      <section className={`status-panel ${saveState}`} role="status" aria-live="polite">
+        <div>
+          <strong>{status}</strong>
+          <p>{message}</p>
+        </div>
+        {lastSavedAt && <span>Last saved {lastSavedAt}</span>}
       </section>
 
       <section className="grid">
@@ -133,6 +185,27 @@ function App() {
         <p><strong>Expected Pages URL:</strong> {pageUrl}</p>
       </section>
 
+      <section className="next-steps">
+        <h2>Next steps</h2>
+        <div className="steps-grid">
+          <div>
+            <span>1</span>
+            <h3>Edit content</h3>
+            <p>Open <code>content/</code> in Obsidian and update pages, posts, and notes.</p>
+          </div>
+          <div>
+            <span>2</span>
+            <h3>Preview locally</h3>
+            <p>Run <code>npm run preview</code> in a second terminal. Quartz serves the site at its local preview URL.</p>
+          </div>
+          <div>
+            <span>3</span>
+            <h3>Publish</h3>
+            <p>Commit, push to GitHub, and enable Pages with GitHub Actions.</p>
+          </div>
+        </div>
+      </section>
+
       <footer>
         <span>{status}</span>
         <span>Next: open <code>content/</code> in Obsidian, then run <code>npm run preview</code>.</span>

package/template/wizard/src/styles.css

@@ -59,6 +59,48 @@ button {
   cursor: pointer;
 }
 
+button:disabled {
+  cursor: wait;
+  opacity: 0.72;
+}
+
+.status-panel {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin: 24px 0 0;
+  border: 1px solid #d8d0c0;
+  border-left: 5px solid #8a8376;
+  border-radius: 8px;
+  padding: 16px;
+  background: #fffdf8;
+}
+
+.status-panel p {
+  margin: 4px 0 0;
+  color: #5f594f;
+}
+
+.status-panel.saved {
+  border-left-color: #28786f;
+}
+
+.status-panel.dirty,
+.status-panel.saving {
+  border-left-color: #8d5c2c;
+}
+
+.status-panel.failed {
+  border-left-color: #b83232;
+}
+
+.status-panel > span {
+  white-space: nowrap;
+  color: #6f675c;
+  font-size: 0.92rem;
+}
+
 .grid {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -105,6 +147,44 @@ textarea {
   margin-top: 0;
 }
 
+.next-steps {
+  margin-top: 24px;
+}
+
+.steps-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.steps-grid > div {
+  border: 1px solid #ded8ca;
+  border-radius: 8px;
+  padding: 18px;
+  background: #fffdf8;
+}
+
+.steps-grid span {
+  display: inline-grid;
+  width: 28px;
+  height: 28px;
+  place-items: center;
+  border-radius: 50%;
+  color: white;
+  background: #28786f;
+  font-size: 0.9rem;
+  font-weight: 800;
+}
+
+.steps-grid h3 {
+  margin: 14px 0 8px;
+}
+
+.steps-grid p {
+  margin: 0;
+  color: #5f594f;
+}
+
 code {
   border-radius: 4px;
   padding: 2px 5px;
@@ -121,12 +201,18 @@ footer {
 
 @media (max-width: 720px) {
   .hero,
-  footer {
+  footer,
+  .status-panel {
     align-items: stretch;
     flex-direction: column;
   }
 
-  .grid {
+  .grid,
+  .steps-grid {
     grid-template-columns: 1fr;
   }
+
+  .status-panel > span {
+    white-space: normal;
+  }
 }

package/template/wizard/vite.config.ts

@@ -13,29 +13,48 @@ export default defineConfig({
       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`)
+          try {
+            if (req.method === "GET") {
+              const body = await readFile(configPath, "utf8")
               res.setHeader("Content-Type", "application/json")
-              res.end(JSON.stringify({ ok: true }))
-            })
-            return
-          }
+              res.end(body)
+              return
+            }
 
-          res.statusCode = 405
-          res.end("Method not allowed")
+            if (req.method === "POST") {
+              let raw = ""
+              req.on("data", (chunk) => {
+                raw += chunk
+              })
+              req.on("end", async () => {
+                try {
+                  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, path: configPath }))
+                } catch (error) {
+                  res.statusCode = 500
+                  res.setHeader("Content-Type", "application/json")
+                  res.end(JSON.stringify({
+                    ok: false,
+                    message: error instanceof Error ? error.message : "Could not save configuration"
+                  }))
+                }
+              })
+              return
+            }
+
+            res.statusCode = 405
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({ ok: false, message: "Method not allowed" }))
+          } catch (error) {
+            res.statusCode = 500
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({
+              ok: false,
+              message: error instanceof Error ? error.message : "Configuration API failed"
+            }))
+          }
         })
       }
     }