@zvndev/darkmown 1.0.0 → 1.2.0

package/src/scaffold.js

@@ -1,24 +1,60 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(moduleDir, "templates");
 
 const darkmownVersion = JSON.parse(
   fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")
 ).version;
 
 /**
- * Scaffold a new Darkmown project into `root`, creating files that don't exist.
+ * List the available scaffold templates (directory names under `src/templates`).
+ * @returns {string[]}
+ */
+export function availableTemplates() {
+  if (!fs.existsSync(templatesDir)) return [];
+  return fs
+    .readdirSync(templatesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/**
+ * Scaffold a new Darkmown project into `root` from a template, creating files
+ * that don't already exist (never overwriting). `package.json` is generated (so
+ * the name tracks the directory and the `@zvndev/darkmown` dep pins the installed
+ * version); every other file is copied verbatim from the chosen template.
  * @param {string} root Absolute path to the target project directory.
- * @returns {{ root: string }}
+ * @param {{ template?: string }} [options] `template` defaults to `"starter"`.
+ * @returns {{ root: string, template: string }}
  */
-export function initProject(root) {
+export function initProject(root, options = {}) {
+  const template = options.template || "starter";
+  const templateDir = path.join(templatesDir, template);
+  if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
+    const list = availableTemplates().join(", ");
+    throw new Error(
+      `Unknown template "${template}". Available templates: ${list || "(none)"}. ` +
+        "Use: darkmown init [dir] --template <name>"
+    );
+  }
+
   fs.mkdirSync(root, { recursive: true });
+
+  // package.json is generated, not copied: the name follows the target directory,
+  // the dep pins the installed Darkmown version, and `type: "module"` makes a
+  // project `api/*.js` import as ESM in `darkmown dev` and on every host.
   writeNew(
     root,
     "package.json",
-    JSON.stringify(
+    `${JSON.stringify(
       {
         name: packageNameFromRoot(root),
         private: true,
+        type: "module",
         scripts: {
           dev: "darkmown dev",
           build: "darkmown build",
@@ -30,161 +66,57 @@ export function initProject(root) {
       },
       null,
       2
-    )
-  );
-  writeNew(
-    root,
-    "site/pages/index.wd",
-    [
-      "---",
-      "title: My Darkmown site",
-      "---",
-      "",
-      "@include /nav.wd",
-      "",
-      "<main>",
-      "",
-      "# My Darkmown site",
-      "",
-      "Plain Markdown works. Rename to `.wd` when you want directives.",
-      "",
-      ":state count = 0",
-      "",
-      "Count: { count }",
-      "",
-      ':button "Increment" -> count++',
-      "",
-      ':state todos = ["Write a page"]',
-      "",
-      "@loop todos into todo",
-      "- { todo }",
-      "@endloop",
-      "",
-      ':button "Add" -> todos += "Add a loop"',
-      "",
-      "</main>"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "site/pages/index.skin",
-    [
-      "tokens",
-      "  ink #172026",
-      "  paper #f7f2e8",
-      "  accent #0f8b8d",
-      "",
-      "page",
-      "  margin 0",
-      "  font ui-sans-serif, system-ui, sans-serif",
-      "  color $ink",
-      "  bg $paper",
-      "",
-      "main",
-      "  max-width 760px",
-      "  margin 0 auto",
-      "  padding 3rem 1.5rem",
-      "",
-      "nav",
-      "  display flex",
-      "  align-items center",
-      "  justify-content space-between",
-      "  gap 1rem",
-      "  max-width 760px",
-      "  margin 0 auto",
-      "  padding 1.25rem 1.5rem",
-      "",
-      "nav strong",
-      "  font-size 1.1rem",
-      "",
-      "nav .links",
-      "  display flex",
-      "  gap 1.25rem",
-      "",
-      "nav a",
-      "  color $ink",
-      "  text-decoration none",
-      "  opacity .8",
-      "",
-      "nav a:hover",
-      "  opacity 1",
-      "  color $accent",
-      "",
-      "button",
-      "  bg $accent",
-      "  color white",
-      "  border 0",
-      "  padding .75rem 1rem",
-      "  radius 8px"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "site/_/nav.wd",
-    [
-      "<nav>",
-      "  <strong>My site</strong>",
-      '  <span class="links">',
-      '    <a href="/">Home</a>',
-      '    <a href="/about/">About</a>',
-      "  </span>",
-      "</nav>"
-    ].join("\n")
+    )}\n`
   );
-  writeNew(
-    root,
-    "site/pages/about.md",
-    [
-      "---",
-      "title: About",
-      "---",
-      "",
-      "# About",
-      "",
-      "This page is plain Markdown (`.md`) — strict CommonMark, zero framework JavaScript.",
-      "Rename it to `.wd` when you want directives like state, loops, or forms.",
-      "",
-      "[Back home](/)"
-    ].join("\n")
-  );
-  writeNew(
-    root,
-    "README.md",
-    [
-      "# My Darkmown site",
-      "",
-      "Run `npm install` and `npm run dev` to start the live compiler.",
-      "",
-      "## Commands",
-      "",
-      "- `npm run dev` — live compiler on http://localhost:5173 with hot reload.",
-      "- `npm run build` — compile the site to `dist/`.",
-      "- `npm run preview` — serve the built `dist/` locally.",
-      "",
-      "## Layout",
-      "",
-      "- Pages live in `site/pages`.",
-      "- Shared includes live in `site/_`.",
-      "- Hidden route files start with `.` or `-`.",
-      "- Colocated `index.skin` and `index.js` attach automatically.",
-      "- Any other file under `site/pages` (images, fonts, …) copies to `dist/` at its own path."
-    ].join("\n")
-  );
-  return { root };
+
+  for (const rel of walk(templateDir)) {
+    copyNew(path.join(templateDir, rel), path.join(root, rel));
+  }
+  return { root, template };
 }
 
 /**
- * Write a file relative to `root` only if it does not already exist.
+ * Write a file relative to `root` only if it does not already exist. Content is
+ * written verbatim (callers include any trailing newline).
  * @param {string} root Project root directory.
  * @param {string} file Path relative to `root`.
- * @param {string} content File contents (a trailing newline is added).
+ * @param {string} content File contents.
  * @returns {void}
  */
 function writeNew(root, file, content) {
   const target = path.join(root, file);
   if (fs.existsSync(target)) return;
   fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, `${content}\n`);
+  fs.writeFileSync(target, content);
+}
+
+/**
+ * Copy a template file to `dest`, preserving bytes, only if `dest` is absent.
+ * @param {string} source
+ * @param {string} dest
+ * @returns {void}
+ */
+function copyNew(source, dest) {
+  if (fs.existsSync(dest)) return;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(source, dest);
+}
+
+/**
+ * Relative paths of every file under `dir` (POSIX-separated), recursively.
+ * @param {string} dir
+ * @param {string} [base]
+ * @returns {string[]}
+ */
+function walk(dir, base = dir) {
+  /** @type {string[]} */
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(abs, base));
+    else files.push(path.relative(base, abs).replaceAll(path.sep, "/"));
+  }
+  return files;
 }
 
 /**

package/src/templates/blog/README.md

@@ -0,0 +1,25 @@
+# Blog — a Darkmown template
+
+A markdown-native blog. Posts are plain `.md` files in `site/pages/posts/`; the
+home page loops `site/_/posts.json` to list them. Static pages, zero JavaScript.
+
+## Add a post
+
+1. Create `site/pages/posts/<slug>.md` with a `title` in frontmatter.
+2. Add an entry to `site/_/posts.json` (`slug`, `url`, `title`, `date`, `excerpt`).
+
+## Commands
+
+- `npm run dev` — live compiler on http://localhost:5173.
+- `npm run build` — compile to `dist/`.
+- `npm run preview` — serve the built `dist/` locally.
+
+## Deploy
+
+```sh
+npx darkmown deploy vercel       # or: npx darkmown deploy cloudflare
+```
+
+[![Deploy to Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=YOUR_REPO_URL)
+&nbsp;
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=YOUR_REPO_URL)

package/src/templates/blog/site/_/nav.wd

@@ -0,0 +1,6 @@
+<nav>
+  <strong>My Blog</strong>
+  <span class="links">
+    <a href="/">Posts</a>
+  </span>
+</nav>

package/src/templates/blog/site/_/posts.json

@@ -0,0 +1,16 @@
+[
+  {
+    "slug": "hello-darkmown",
+    "url": "/posts/hello-darkmown/",
+    "title": "Hello, Darkmown",
+    "date": "2026-06-15",
+    "excerpt": "Why I rewrote my blog as plain Markdown files — and shipped zero framework JavaScript."
+  },
+  {
+    "slug": "markdown-native",
+    "url": "/posts/markdown-native/",
+    "title": "Markdown-native, by default",
+    "date": "2026-06-01",
+    "excerpt": "Every post is a .md file. The index is one .wd loop over this manifest. That's the whole site."
+  }
+]

package/src/templates/blog/site/pages/index.skin

@@ -0,0 +1,51 @@
+tokens
+  ink #1d2530
+  paper #fbfaf7
+  muted #6b7785
+  accent #2f6df0
+
+page
+  margin 0
+  font ui-sans-serif, system-ui, sans-serif
+  color $ink
+  bg $paper
+  line-height 1.6
+
+main
+  max-width 720px
+  margin 0 auto
+  padding 2.5rem 1.5rem
+
+nav
+  display flex
+  align-items center
+  justify-content space-between
+  max-width 720px
+  margin 0 auto
+  padding 1.25rem 1.5rem
+
+nav strong
+  font-size 1.1rem
+
+nav a
+  color $accent
+  text-decoration none
+
+.post-card
+  padding 1.5rem 0
+  border-bottom 1px solid #e7e3da
+
+.post-card h3
+  margin 0 0 .25rem
+
+.post-card a
+  color $ink
+  text-decoration none
+
+.post-card a:hover
+  color $accent
+
+.post-meta
+  margin 0 0 .5rem
+  color $muted
+  font-size .9rem

package/src/templates/blog/site/pages/index.wd

@@ -0,0 +1,24 @@
+---
+title: My Blog
+description: A markdown-native blog built with Darkmown.
+transitions: true
+---
+
+@include /nav.wd
+
+<main>
+
+# My Blog
+
+Posts are plain Markdown files in `site/pages/posts/`. This index is one `.wd`
+loop over a small JSON manifest — sorted newest-first, shipping zero JavaScript.
+
+@loop /posts.json into post sort by post.date desc
+::: post-card
+### [{ post.title }]({ post.url })
+<p class="post-meta">{ post.date }</p>
+{ post.excerpt }
+:::
+@endloop
+
+</main>

package/src/templates/blog/site/pages/posts/hello-darkmown.md

@@ -0,0 +1,16 @@
+---
+title: Hello, Darkmown
+description: Why I rewrote my blog as plain Markdown files.
+transitions: true
+---
+
+# Hello, Darkmown
+
+This post is a plain `.md` file — strict CommonMark, **zero** framework
+JavaScript. It loads instantly and is trivial to edit.
+
+When I want something interactive — a like button, a live filter, a form — I
+rename a file to `.wd` and add a directive. Static stays static; only the pages
+that need it ship the tiny reactive runtime.
+
+[← Back to all posts](/)

package/src/templates/blog/site/pages/posts/markdown-native.md

@@ -0,0 +1,20 @@
+---
+title: Markdown-native, by default
+description: Every post is a .md file; the index is one .wd loop.
+transitions: true
+---
+
+# Markdown-native, by default
+
+To add a post, drop a Markdown file in `site/pages/posts/` and add a line to
+`site/_/posts.json`. The home page loops that manifest:
+
+```wd
+@loop /posts.json into post sort by post.date desc
+### [{ post.title }]({ post.url })
+@endloop
+```
+
+No build config, no plugins, no content layer. The file *is* the page.
+
+[← Back to all posts](/)

package/src/templates/dashboard/README.md

@@ -0,0 +1,25 @@
+# Dashboard — a Darkmown template
+
+A live dashboard. The page is static; the stat cards `:fetch` their data from
+`api/metrics.js` — a plain Web-standard `(request) => Response` function that runs
+in `darkmown dev` and on every host. Loading and error states are handled inline.
+
+- **Data** — `api/metrics.js`. Replace its body with a real query (DB, analytics,
+  billing). Add more endpoints as `api/<name>.js`; each maps to `/api/<name>`.
+- **View** — `site/pages/index.wd` fetches `/api/metrics` and renders stat cards.
+
+## Commands
+
+- `npm run dev` — live compiler + local `/api/*` runner on http://localhost:5173.
+- `npm run build` — compile to `dist/`.
+- `npm run preview` — serve the built `dist/` locally (static only; use `dev` for `/api`).
+
+## Deploy
+
+```sh
+npx darkmown deploy vercel       # or: npx darkmown deploy cloudflare
+```
+
+[![Deploy to Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=YOUR_REPO_URL)
+&nbsp;
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=YOUR_REPO_URL)

package/src/templates/dashboard/api/metrics.js

@@ -0,0 +1,15 @@
+// Demo metrics endpoint. A plain Web-standard `(request) => Response` handler:
+// it runs in `darkmown dev` and on Vercel Edge / Cloudflare Pages with no extra
+// config. Returns a snapshot of stats — replace the body with a real query
+// (database, analytics API, billing provider, …).
+export const config = { runtime: "edge" };
+
+export default function () {
+  return Response.json({
+    revenue: 48230,
+    orders: 312,
+    visitors: 8940,
+    conversion: 3.5,
+    updatedAt: new Date().toISOString()
+  });
+}

package/src/templates/dashboard/site/_/nav.wd

@@ -0,0 +1,6 @@
+<nav>
+  <strong>Dashboard</strong>
+  <span class="links">
+    <a href="/">Overview</a>
+  </span>
+</nav>

package/src/templates/dashboard/site/pages/index.skin

@@ -0,0 +1,74 @@
+tokens
+  ink #0f1722
+  paper #0b1018
+  panel #131c28
+  line #243245
+  muted #8aa0b8
+  accent #4f9cff
+
+page
+  margin 0
+  font ui-sans-serif, system-ui, sans-serif
+  color #e7eefc
+  bg $paper
+  line-height 1.55
+
+main
+  max-width 880px
+  margin 0 auto
+  padding 2rem 1.5rem
+
+nav
+  display flex
+  align-items center
+  justify-content space-between
+  max-width 880px
+  margin 0 auto
+  padding 1.25rem 1.5rem
+
+nav strong
+  font-size 1.1rem
+
+nav a
+  color $accent
+  text-decoration none
+
+.stat-grid
+  display grid
+  grid-template-columns repeat(auto-fit, minmax(160px, 1fr))
+  gap 1rem
+  margin 1.5rem 0
+
+.stat
+  background $panel
+  border 1px solid $line
+  radius 12px
+  padding 1.1rem 1.25rem
+
+.stat-label
+  color $muted
+  font-size .85rem
+  text-transform uppercase
+  letter-spacing .04em
+
+.stat-num
+  font-size 1.9rem
+  font-weight 700
+  margin-top .35rem
+
+.note
+  background $panel
+  border 1px solid $line
+  radius 10px
+  padding 1rem
+
+.error
+  background #2a1620
+  border 1px solid #5b2738
+  radius 10px
+  padding 1rem
+
+.updated
+  color $muted
+  font-size .85rem
+  margin-top .5rem

package/src/templates/dashboard/site/pages/index.wd

@@ -0,0 +1,75 @@
+---
+title: Dashboard — built with Darkmown
+description: A live dashboard — stat cards fetched from a serverless function, on an otherwise static page.
+transitions: true
+---
+
+@include /nav.wd
+
+<main>
+
+::: section #dash
+
+# Dashboard
+
+:fetch metrics from "/api/metrics"
+
+:if metrics_loading
+::: card .note
+Loading metrics…
+:::
+:endif
+
+:if metrics_error
+::: card .error
+Couldn't load metrics: { metrics_error }
+:::
+:endif
+
+:if metrics
+::: stat-grid
+::: card .stat
+::: stat-label
+Revenue
+:::
+::: stat-num
+{ metrics.revenue | money }
+:::
+:::
+::: card .stat
+::: stat-label
+Orders
+:::
+::: stat-num
+{ metrics.orders }
+:::
+:::
+::: card .stat
+::: stat-label
+Visitors
+:::
+::: stat-num
+{ metrics.visitors }
+:::
+:::
+::: card .stat
+::: stat-label
+Conversion
+:::
+::: stat-num
+{ metrics.conversion }%
+:::
+:::
+:::
+
+::: updated
+Updated { metrics.updatedAt }
+:::
+:endif
+
+The numbers come from `api/metrics.js` — a serverless function that runs in
+`darkmown dev` and on your host. The page itself stays static; only the data fetches.
+
+:::
+
+</main>

package/src/templates/landing/README.md

@@ -0,0 +1,25 @@
+# Landing — a Darkmown template
+
+A marketing one-pager: a hero, a feature grid, and a testimonials **carousel**.
+The static parts ship zero framework JavaScript; only the carousel loads a tiny,
+pay-for-what-you-use behavior module (`/__wd/behaviors/carousel.js`).
+
+- **Carousel** — the `:carousel … :endcarousel` block; native CSS scroll-snap +
+  the behavior add prev/next, dots, and mouse drag. Touch swipe is native.
+- **Everything else** — plain Markdown + `:::` containers, no JavaScript.
+
+## Commands
+
+- `npm run dev` — live compiler on http://localhost:5173.
+- `npm run build` — compile to `dist/`.
+- `npm run preview` — serve the built `dist/` locally.
+
+## Deploy
+
+```sh
+npx darkmown deploy vercel       # or: npx darkmown deploy cloudflare
+```
+
+[![Deploy to Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=YOUR_REPO_URL)
+ 
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=YOUR_REPO_URL)

package/src/templates/landing/site/_/nav.wd

@@ -0,0 +1,6 @@
+<nav>
+  <strong>Acme</strong>
+  <span class="links">
+    <a href="#start">Get started</a>
+  </span>
+</nav>