create-ngmd 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ngmd",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Scaffold a NgMd Angular docs site. Run via `pnpm create ngmd@latest` / `npm create ngmd@latest` / `yarn create ngmd` / `bun create ngmd`.",
   "license": "MIT",
   "author": {

package/template/README.md

@@ -11,7 +11,7 @@ pnpm dev
 
 ## Add a page
 
-Drop a `.md` file under `src/app/pages/` (or under `src/content/` and reference it via `injectContent`). Headings become anchors automatically.
+Drop a `.md` file under `src/content/`. The path becomes the URL: `src/content/install.md` resolves at `/install`, `src/content/guides/auth.md` at `/guides/auth`. No `.page.ts` wrapper needed; the catch-all at `src/app/pages/[...slug].page.ts` renders every prose route.
 
 ## Build
 

package/template/link-guard.plugin.ts

@@ -10,8 +10,8 @@ import type { Plugin } from 'vite';
  *   - `[text](/path)` — `/path` must be a known route
  *   - `[text](/path#fragment)` — both the route and the heading slug must exist
  *
- * Routes are discovered by scanning `src/content/*.md` (mapped via the same
- * CONTENT_TO_ROUTE convention page-meta uses) and `src/app/pages/**\/*.page.ts`.
+ * Routes are discovered by walking `src/content/**\/*.md` (each markdown
+ * file's path under content/ becomes its route) and `src/app/pages/**\/*.page.ts`.
  * External (`http(s)://`), mail (`mailto:`), and relative (`./foo`) links are
  * skipped; the existing externalLinkGuard covers raw HTML external anchors.
  *
@@ -19,21 +19,6 @@ import type { Plugin } from 'vite';
  * rule the rendered TOC uses, so dev-time and runtime stay in sync.
  */
 
-const CONTENT_TO_ROUTE: Record<string, string> = {
-  welcome: '/welcome',
-  about: '/getting-started/about',
-  changelog: '/getting-started/changelog',
-  installation: '/getting-started/installation',
-  'quick-start': '/getting-started/quick-start',
-  theming: '/concepts/theming',
-  components: '/concepts/components',
-  'markdown-routes': '/concepts/markdown-routes',
-  'stack-overview': '/stack/overview',
-  'stack-technologies': '/stack/technologies',
-  'stack-installation': '/stack/installation',
-  support: '/support',
-};
-
 function slugify(s: string): string {
   return s
     .toLowerCase()
@@ -55,6 +40,32 @@ function walkPageFiles(dir: string, root: string, out: string[] = []): string[]
   return out;
 }
 
+/**
+ * Walk `src/content/**\/*.md` and return `[relativePath, route]` pairs.
+ * Route mirrors the path under `src/content/` with the .md stripped.
+ * Example: `src/content/concepts/theming.md` → `/concepts/theming`.
+ */
+function walkContentFiles(
+  dir: string,
+  root: string,
+  baseDir: string = dir,
+  out: Array<[string, string]> = [],
+): Array<[string, string]> {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkContentFiles(full, root, baseDir, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const rel = relative(root, full);
+      const fromContent = relative(baseDir, full)
+        .replace(/\\/g, '/')
+        .replace(/\.md$/, '');
+      out.push([rel, '/' + fromContent]);
+    }
+  }
+  return out;
+}
+
 function routeFromPagePath(rel: string): string {
   const trimmed = rel
     .replace(/^src\/app\/pages\//, '')
@@ -86,17 +97,17 @@ export function internalLinkGuard(): Plugin {
     if (primed) return;
     primed = true;
 
-    // .md → route
-    for (const [name, route] of Object.entries(CONTENT_TO_ROUTE)) {
-      const rel = `src/content/${name}.md`;
-      const full = join(root, rel);
-      try {
-        statSync(full);
-      } catch {
-        continue;
+    // .md → route (walk src/content/ tree)
+    const contentDir = join(root, 'src/content');
+    try {
+      statSync(contentDir);
+      for (const [rel, route] of walkContentFiles(contentDir, root)) {
+        const full = join(root, rel);
+        routes.set(route, rel);
+        headingsByRoute.set(route, extractHeadings(readFileSync(full, 'utf8')));
       }
-      routes.set(route, rel);
-      headingsByRoute.set(route, extractHeadings(readFileSync(full, 'utf8')));
+    } catch {
+      // src/content missing — skip
     }
 
     // .page.ts → route (no heading scrape; just makes the route resolvable)

package/template/page-meta.plugin.ts

@@ -6,10 +6,11 @@ import type { Plugin } from 'vite';
 /**
  * Build-time map of page URL → { editUrl, lastUpdated }.
  *
- * Walks `src/app/pages` (for `.page.ts` routes) and `src/content` (for `.md`
- * referenced by `injectContent({ customFilename })`), pulls the latest commit
- * date via `git log`, and emits a typed module under the virtual id
- * `virtual:ngmd/page-meta` which the runtime imports.
+ * Walks `src/app/pages` (for `.page.ts` routes) and `src/content/**\/*.md`
+ * (each markdown file's path under content/ becomes its route, matching the
+ * `[...slug].page.ts` catch-all), pulls the latest commit date via `git log`,
+ * and emits a typed module under the virtual id `virtual:ngmd/page-meta`
+ * which the runtime imports.
  *
  * If the file is uncommitted, lastUpdated falls back to its mtime in ISO
  * date form so dev iteration still shows something.
@@ -64,21 +65,31 @@ function routeFromPagePath(rel: string): string {
   return '/' + trimmed;
 }
 
-const CONTENT_TO_ROUTE: Record<string, string> = {
-  // Maps customFilename (without .md) → page route for content-driven pages.
-  welcome: '/welcome',
-  about: '/getting-started/about',
-  changelog: '/getting-started/changelog',
-  installation: '/getting-started/installation',
-  'quick-start': '/getting-started/quick-start',
-  theming: '/concepts/theming',
-  components: '/concepts/components',
-  'markdown-routes': '/concepts/markdown-routes',
-  'stack-overview': '/stack/overview',
-  'stack-technologies': '/stack/technologies',
-  'stack-installation': '/stack/installation',
-  support: '/support',
-};
+/**
+ * Walk `src/content/**\/*.md` and return `[relativePath, route]` pairs.
+ * Route mirrors the path under `src/content/` with the .md stripped.
+ * Example: `src/content/concepts/theming.md` → `/concepts/theming`.
+ */
+function walkContentFiles(
+  dir: string,
+  root: string,
+  baseDir: string = dir,
+  out: Array<[string, string]> = [],
+): Array<[string, string]> {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkContentFiles(full, root, baseDir, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const rel = relative(root, full);
+      const fromContent = relative(baseDir, full)
+        .replace(/\\/g, '/')
+        .replace(/\.md$/, '');
+      out.push([rel, '/' + fromContent]);
+    }
+  }
+  return out;
+}
 
 export function pageMetaPlugin(opts: {
   repoUrl: string;
@@ -114,16 +125,21 @@ export function pageMetaPlugin(opts: {
         };
       }
 
-      // src/content/<name>.md → route via CONTENT_TO_ROUTE
-      for (const [name, route] of Object.entries(CONTENT_TO_ROUTE)) {
-        const rel = `src/content/${name}.md`;
-        const date = gitDate(rel, root);
-        if (!date) continue;
-        // .md edit URL wins when present (more useful for prose pages)
-        map[route] = {
-          editUrl: `${opts.repoUrl}/edit/${branch}/${rel}`,
-          lastUpdated: date,
-        };
+      // src/content/**/*.md → route (mirrors the [...slug] catch-all)
+      const contentDir = join(root, 'src/content');
+      try {
+        statSync(contentDir);
+        for (const [rel, route] of walkContentFiles(contentDir, root)) {
+          const date = gitDate(rel, root);
+          if (!date) continue;
+          // .md edit URL wins when present (more useful for prose pages)
+          map[route] = {
+            editUrl: `${opts.repoUrl}/edit/${branch}/${rel}`,
+            lastUpdated: date,
+          };
+        }
+      } catch {
+        // src/content missing — skip
       }
 
       return `export const pageMeta = ${JSON.stringify(map, null, 2)};`;

package/template/sitemap.plugin.ts

@@ -7,28 +7,39 @@ import type { Plugin } from 'vite';
  * Emits `sitemap.xml` and `robots.txt` into the client build output.
  *
  * Discovery mirrors the page-meta plugin: walks `src/app/pages/*.page.ts` and
- * `src/content/*.md` (mapped via CONTENT_TO_ROUTE), pulls each file's last
- * commit date via `git log -1 --format=%cs` to populate `<lastmod>`, falls
- * back to mtime for uncommitted files, and writes both files via Rollup's
- * `emitFile` so they land at the client root.
+ * `src/content/**\/*.md` (each markdown file's path becomes its route), pulls
+ * each file's last commit date via `git log -1 --format=%cs` to populate
+ * `<lastmod>`, falls back to mtime for uncommitted files, and writes both
+ * files via Rollup's `emitFile` so they land at the client root.
  *
  * `robots.txt` is a one-liner pointing at the sitemap.
  */
 
-const CONTENT_TO_ROUTE: Record<string, string> = {
-  welcome: '/welcome',
-  about: '/getting-started/about',
-  changelog: '/getting-started/changelog',
-  installation: '/getting-started/installation',
-  'quick-start': '/getting-started/quick-start',
-  theming: '/concepts/theming',
-  components: '/concepts/components',
-  'markdown-routes': '/concepts/markdown-routes',
-  'stack-overview': '/stack/overview',
-  'stack-technologies': '/stack/technologies',
-  'stack-installation': '/stack/installation',
-  support: '/support',
-};
+/**
+ * Walk `src/content/**\/*.md` and return `[relativePath, route]` pairs.
+ * Route mirrors the path under `src/content/` with the .md stripped.
+ * Example: `src/content/concepts/theming.md` → `/concepts/theming`.
+ */
+function walkContentFiles(
+  dir: string,
+  root: string,
+  baseDir: string = dir,
+  out: Array<[string, string]> = [],
+): Array<[string, string]> {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkContentFiles(full, root, baseDir, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const rel = relative(root, full);
+      const fromContent = relative(baseDir, full)
+        .replace(/\\/g, '/')
+        .replace(/\.md$/, '');
+      out.push([rel, '/' + fromContent]);
+    }
+  }
+  return out;
+}
 
 function gitDate(file: string, cwd: string): string {
   try {
@@ -107,14 +118,14 @@ export function sitemapPlugin(opts: { siteUrl: string }): Plugin {
         // src/app/pages missing — fine
       }
 
-      for (const [name, route] of Object.entries(CONTENT_TO_ROUTE)) {
-        const rel = `src/content/${name}.md`;
-        try {
-          statSync(join(root, rel));
-        } catch {
-          continue;
+      const contentDir = join(root, 'src/content');
+      try {
+        statSync(contentDir);
+        for (const [rel, route] of walkContentFiles(contentDir, root)) {
+          entries.set(route, gitDate(rel, root));
         }
-        entries.set(route, gitDate(rel, root));
+      } catch {
+        // src/content missing — skip
       }
 
       const urls = [...entries.entries()]

package/template/src/app/pages/[...slug].page.ts

@@ -0,0 +1,79 @@
+import { AsyncPipe } from '@angular/common';
+import { Component, OnDestroy, computed, effect, inject } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { RouterLink } from '@angular/router';
+import { injectContent, MarkdownComponent } from '@analogjs/content';
+import { LayoutMode } from '../layout-mode.service';
+
+/**
+ * Catch-all route for every markdown page.
+ *
+ * Mirrors the adev pattern: one shared component renders every prose route.
+ * `injectContent()` reads the `slug` route param (which the `[...slug]`
+ * convention populates with the full nested path) and looks up the matching
+ * `src/content/<slug>.md`. Pages that need bespoke layouts (the landing
+ * page, the components gallery) keep their named `.page.ts` and Angular's
+ * router prefers the more specific match.
+ *
+ * Doubles as the 404 page: when no markdown matches the requested URL,
+ * `injectContent` returns the sentinel below as the body, the docs chrome
+ * is hidden, and the 404 UI is rendered instead.
+ */
+
+const NOT_FOUND = '__ngmd-not-found__';
+
+@Component({
+  selector: 'app-doc',
+  imports: [AsyncPipe, MarkdownComponent, RouterLink],
+  template: `
+    @if (content$ | async; as doc) {
+      @if (doc.content === notFound) {
+        <section class="mx-auto max-w-2xl px-6 py-24 text-center">
+          <p class="text-sm font-medium tracking-[0.2em] text-zinc-400 dark:text-zinc-500">
+            404
+          </p>
+          <h1 class="mt-3 text-4xl sm:text-5xl font-bold tracking-tight">
+            Page not found
+          </h1>
+          <p class="mt-4 text-lg text-zinc-600 dark:text-zinc-400">
+            The page you're looking for doesn't exist or has moved.
+          </p>
+          <div class="mt-10 flex flex-wrap items-center justify-center gap-3">
+            <a
+              routerLink="/"
+              class="rounded-md bg-zinc-900 dark:bg-zinc-50 px-5 py-2.5 text-sm font-medium text-zinc-50 dark:text-zinc-900 hover:bg-zinc-700 dark:hover:bg-zinc-200"
+            >
+              Go home
+            </a>
+            <a
+              routerLink="/welcome"
+              class="rounded-md border border-zinc-200 dark:border-zinc-800 px-5 py-2.5 text-sm font-medium hover:bg-zinc-100 dark:hover:bg-zinc-900"
+            >
+              Read the docs
+            </a>
+          </div>
+        </section>
+      } @else {
+        <article class="max-w-3xl mx-auto p-8">
+          <analog-markdown [content]="doc.content" />
+        </article>
+      }
+    }
+  `,
+})
+export default class DocPage implements OnDestroy {
+  private readonly layout = inject(LayoutMode);
+  protected readonly notFound = NOT_FOUND;
+
+  readonly content$ = injectContent<{ title: string }>('slug', NOT_FOUND);
+  private readonly doc = toSignal(this.content$);
+  private readonly missing = computed(() => this.doc()?.content === NOT_FOUND);
+
+  constructor() {
+    effect(() => this.layout.chromeHidden.set(this.missing()));
+  }
+
+  ngOnDestroy(): void {
+    this.layout.chromeHidden.set(false);
+  }
+}

package/template/src/content/welcome.md

@@ -8,7 +8,7 @@ This is your first docs page, rendered from `src/content/welcome.md`.
 
 ## Add a page
 
-Drop a new `.md` file under `src/content/` and load it with `injectContent({ customFilename })` in a `.page.ts` route, or put `.md` files directly under `src/app/pages/` to get a file-router route with zero TypeScript.
+Drop a new `.md` file under `src/content/`. The path becomes the URL: `src/content/install.md` resolves at `/install`, `src/content/guides/auth.md` at `/guides/auth`. The catch-all at `src/app/pages/[...slug].page.ts` renders every prose route, no wrapper required.
 
 ## Add nav
 
@@ -16,4 +16,4 @@ Edit the `nav` array in `src/ngmd.config.ts`. Sidebar, command palette, breadcru
 
 ## Authoring components
 
-NgMd ships a small authoring component library under `src/app/ui/`: callouts, alerts, cards, tabs (Spartan brain), pill rows, workflows, hero, and a code block with shiki highlighting. Compose them in `.page.ts` around your markdown.
+NgMd ships a small authoring component library under `src/app/ui/`: callouts, alerts, cards, tabs (Spartan brain), pill rows, workflows, hero, and a code block with shiki highlighting. Compose them in a `.page.ts` route for pages that need bespoke layout; for prose pages, stick with markdown.

package/template/src/app/pages/[...not-found].page.ts

@@ -1,47 +0,0 @@
-import { Component, inject, OnDestroy, OnInit } from '@angular/core';
-import { RouterLink } from '@angular/router';
-import { LayoutMode } from '../layout-mode.service';
-
-@Component({
-  selector: 'app-not-found',
-  imports: [RouterLink],
-  template: `
-    <section class="mx-auto max-w-2xl px-6 py-24 text-center">
-      <p class="text-sm font-medium tracking-[0.2em] text-zinc-400 dark:text-zinc-500">
-        404
-      </p>
-      <h1 class="mt-3 text-4xl sm:text-5xl font-bold tracking-tight">
-        Page not found
-      </h1>
-      <p class="mt-4 text-lg text-zinc-600 dark:text-zinc-400">
-        The page you're looking for doesn't exist or has moved.
-      </p>
-
-      <div class="mt-10 flex flex-wrap items-center justify-center gap-3">
-        <a
-          routerLink="/"
-          class="rounded-md bg-zinc-900 dark:bg-zinc-50 px-5 py-2.5 text-sm font-medium text-zinc-50 dark:text-zinc-900 hover:bg-zinc-700 dark:hover:bg-zinc-200"
-        >
-          Go home
-        </a>
-        <a
-          routerLink="/welcome"
-          class="rounded-md border border-zinc-200 dark:border-zinc-800 px-5 py-2.5 text-sm font-medium hover:bg-zinc-100 dark:hover:bg-zinc-900"
-        >
-          Read the docs
-        </a>
-      </div>
-    </section>
-  `,
-})
-export default class NotFoundPage implements OnInit, OnDestroy {
-  private readonly layout = inject(LayoutMode);
-
-  ngOnInit(): void {
-    this.layout.chromeHidden.set(true);
-  }
-
-  ngOnDestroy(): void {
-    this.layout.chromeHidden.set(false);
-  }
-}

package/template/src/app/pages/welcome.page.ts

@@ -1,18 +0,0 @@
-import { AsyncPipe } from '@angular/common';
-import { Component } from '@angular/core';
-import { injectContent, MarkdownComponent } from '@analogjs/content';
-
-@Component({
-  selector: 'app-welcome',
-  imports: [AsyncPipe, MarkdownComponent],
-  template: `
-    @if (content$ | async; as doc) {
-      <article class="max-w-3xl mx-auto p-8">
-        <analog-markdown [content]="doc.content" />
-      </article>
-    }
-  `,
-})
-export default class WelcomePage {
-  readonly content$ = injectContent<{ title: string }>({ customFilename: 'welcome' });
-}