create-ngmd 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# create-ngmd
+
+Scaffold a new [NgMd](https://github.com/erkamyaman/ngmd) docs project.
+
+```bash
+pnpm create ngmd@latest my-docs
+# or
+npm create ngmd@latest my-docs
+# or
+yarn create ngmd my-docs
+# or
+bun create ngmd my-docs
+```
+
+Then:
+
+```bash
+cd my-docs
+pnpm install   # or npm install / yarn / bun install
+pnpm dev
+```
+
+Open `http://localhost:5173`.
+
+## What you get
+
+A working AnalogJS + Tailwind v4 + Shiki docs site with:
+
+- File-based markdown routes — drop `.md` under `src/app/pages/`, get a route
+- Authoring components: callout, alert, card, tabs, pill row, workflow, hero, code-block, video, image (all under `src/app/ui/`)
+- Sticky translucent header, sidebar, breadcrumb, scroll-spy TOC, Cmd+K palette
+- Per-page footer: prev/next navigation, edit-on-github, last-updated
+- Heading anchor copy buttons, code-block copy buttons
+- Build-time link guards (external + internal)
+- Sitemap + robots.txt auto-generated
+- Light / dark / auto theme with no-flash boot script
+- `*Keyword` inline auto-linking
+- ` ```ts file="src/foo.ts#L5-L20" ` code imports, group code tabs, line highlighting
+
+See the [NgMd repo](https://github.com/erkamyaman/ngmd) for the feature list.
+
+## Next steps
+
+1. Edit `src/content/welcome.md` to make the first page your own.
+2. Edit `src/ngmd.config.ts` to set brand name, navigation, and accent.
+3. Drop more `.md` files in `src/app/pages/` or `src/content/`.
+4. Build with `pnpm run build`, deploy `dist/` to any static host.
+
+## How it works
+
+`index.mjs` (Node 20+, zero npm deps) copies `template/` into the target directory and rewrites a few placeholders (`package.json` name, `ngmd.config.ts` brand, `index.html` title) so the new project matches the name you passed.
+
+`template/` is generated from the parent ngmd repo by `build-template.mjs` and is git-ignored. The `prepublishOnly` script regenerates it before every publish, so the npm artifact always carries an up-to-date starter.
+
+To preview a scaffolded project locally without publishing:
+
+```bash
+node create-ngmd/build-template.mjs   # populate create-ngmd/template/
+node create-ngmd/index.mjs my-docs    # scaffold ./my-docs
+```
+
+## Licence
+
+MIT

package/index.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(HERE, 'template');
+
+/**
+ * `create-ngmd <project-name>` — scaffolds a fresh NgMd project.
+ *
+ * Behaviour:
+ *   1. Accept project name from argv[2] or interactive prompt.
+ *   2. Validate (lowercase, hyphenated, no path traversal, dir not present).
+ *   3. Copy `template/` into ./<project-name>/.
+ *   4. Replace placeholders ({{name}}) in package.json, ngmd.config.ts, index.html.
+ *   5. Print next-step commands tailored to the detected package manager.
+ *
+ * Zero npm dependencies. Node 20+ builtins only.
+ */
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+};
+
+function detectPM() {
+  const ua = process.env.npm_config_user_agent ?? '';
+  if (ua.startsWith('pnpm')) return 'pnpm';
+  if (ua.startsWith('yarn')) return 'yarn';
+  if (ua.startsWith('bun')) return 'bun';
+  return 'npm';
+}
+
+function validName(s) {
+  return /^[a-z0-9][a-z0-9._-]*$/.test(s) && !s.includes('..');
+}
+
+async function prompt(rl, question, defaultValue) {
+  const tail = defaultValue ? ` ${c.dim}(${defaultValue})${c.reset}` : '';
+  const answer = (await rl.question(`${question}${tail}: `)).trim();
+  return answer || defaultValue || '';
+}
+
+function replacePlaceholders(target, name) {
+  const subs = [
+    {
+      file: 'package.json',
+      replacer: (s) => s.replace(/"name":\s*"ngmd"/, `"name": "${name}"`),
+    },
+    {
+      file: 'src/ngmd.config.ts',
+      replacer: (s) =>
+        s
+          .replace(/name:\s*'NgMd'/, `name: '${name}'`)
+          .replace(
+            /githubUrl:\s*'[^']*'/,
+            `githubUrl: 'https://github.com/your-org/${name}'`,
+          ),
+    },
+    {
+      file: 'index.html',
+      replacer: (s) =>
+        s
+          .replace(/<title>[^<]*<\/title>/, `<title>${name}</title>`)
+          .replace(/og:title"\s+content="[^"]*"/, `og:title" content="${name}"`),
+    },
+  ];
+
+  for (const { file, replacer } of subs) {
+    const path = join(target, file);
+    if (!existsSync(path)) continue;
+    writeFileSync(path, replacer(readFileSync(path, 'utf8')));
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const requested = argv[0];
+
+  console.log(`\n${c.bold}${c.cyan}create-ngmd${c.reset} ${c.dim}— scaffold a new NgMd project${c.reset}\n`);
+
+  if (!existsSync(TEMPLATE_DIR)) {
+    console.error(`${c.red}error:${c.reset} template directory missing at ${TEMPLATE_DIR}`);
+    console.error('Run `node create-ngmd/build-template.mjs` from the ngmd repo first.');
+    process.exit(1);
+  }
+
+  let name = requested;
+  if (!name) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    name = await prompt(rl, 'Project name', 'my-docs');
+    rl.close();
+  }
+
+  if (!validName(name)) {
+    console.error(
+      `${c.red}error:${c.reset} "${name}" is not a valid project name.\n` +
+        `Use lowercase letters, digits, dots, underscores, or hyphens.`,
+    );
+    process.exit(1);
+  }
+
+  const target = resolve(process.cwd(), name);
+  if (existsSync(target)) {
+    const isEmpty = readdirSync(target).length === 0;
+    if (!isEmpty) {
+      console.error(`${c.red}error:${c.reset} directory "${name}" already exists and is not empty.`);
+      process.exit(1);
+    }
+  } else {
+    mkdirSync(target, { recursive: true });
+  }
+
+  console.log(`${c.dim}scaffolding into${c.reset} ${target}\n`);
+
+  cpSync(TEMPLATE_DIR, target, {
+    recursive: true,
+    filter: (src) => {
+      const base = src.replace(TEMPLATE_DIR, '').replace(/^[/\\]/, '');
+      // Belt-and-braces: never copy these, even if they slip into template/.
+      return !/^(node_modules|dist|\.angular|\.vite|pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb)/.test(
+        base,
+      );
+    },
+  });
+
+  // npm rewrites .gitignore → .npmignore on publish; restore the dotfile.
+  const gitignoreFromNpm = join(target, 'gitignore');
+  if (existsSync(gitignoreFromNpm)) {
+    cpSync(gitignoreFromNpm, join(target, '.gitignore'));
+    const { rmSync } = await import('node:fs');
+    rmSync(gitignoreFromNpm);
+  }
+
+  replacePlaceholders(target, name);
+
+  const pm = detectPM();
+  const install = pm === 'yarn' ? 'yarn' : `${pm} install`;
+  const dev = pm === 'npm' ? 'npm run dev' : `${pm} dev`;
+
+  console.log(`${c.green}✓${c.reset} ${c.bold}done${c.reset}\n`);
+  console.log(`${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.cyan}cd${c.reset} ${name}`);
+  console.log(`  ${c.cyan}${install}${c.reset}`);
+  console.log(`  ${c.cyan}${dev}${c.reset}\n`);
+  console.log(`${c.dim}Docs:${c.reset} https://ngmd.netlify.app`);
+  console.log(`${c.dim}Issues:${c.reset} https://github.com/erkamyaman/ngmd/issues\n`);
+}
+
+main().catch((err) => {
+  console.error(`\n${c.red}aborted:${c.reset} ${err.message ?? err}\n`);
+  process.exit(1);
+});
+
+function statSafe(p) {
+  try { return statSync(p); } catch { return null; }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "create-ngmd",
+  "version": "0.0.1",
+  "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": {
+    "name": "Kam",
+    "url": "https://github.com/erkamyaman"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erkamyaman/ngmd.git",
+    "directory": "create-ngmd"
+  },
+  "bugs": "https://github.com/erkamyaman/ngmd/issues",
+  "homepage": "https://github.com/erkamyaman/ngmd#readme",
+  "keywords": [
+    "angular",
+    "angular-docs",
+    "analogjs",
+    "docs",
+    "documentation",
+    "starter",
+    "scaffolder",
+    "shiki",
+    "tailwind",
+    "vite",
+    "create"
+  ],
+  "type": "module",
+  "bin": {
+    "create-ngmd": "index.mjs"
+  },
+  "scripts": {
+    "build-template": "node build-template.mjs",
+    "prepublishOnly": "node build-template.mjs"
+  },
+  "engines": {
+    "node": ">=20.19.1"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/README.md

@@ -0,0 +1,26 @@
+# NgMd starter
+
+A docs site scaffolded with `create-ngmd`.
+
+## Develop
+
+```bash
+pnpm install    # or npm / yarn / bun
+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.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Output lands in `dist/`. Sitemap and `robots.txt` emit alongside the client bundle.
+
+## Configure
+
+Edit `src/ngmd.config.ts` to change brand, navigation, and public URL.

package/template/angular.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "my-app": {
+      "projectType": "application",
+      "root": ".",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@analogjs/platform:vite",
+          "options": {
+            "configFile": "vite.config.ts",
+            "main": "src/main.ts",
+            "outputPath": "dist/client",
+            "tsConfig": "tsconfig.app.json"
+          },
+          "defaultConfiguration": "production",
+          "configurations": {
+            "development": {
+              "mode": "development"
+            },
+            "production": {
+              "sourcemap": false,
+              "mode": "production"
+            }
+          }
+        },
+        "serve": {
+          "builder": "@analogjs/platform:vite-dev-server",
+          "defaultConfiguration": "development",
+          "options": {
+            "buildTarget": "my-app:build",
+            "port": 5173
+          },
+          "configurations": {
+            "development": {
+              "buildTarget": "my-app:build:development",
+              "hmr": true
+            },
+            "production": {
+              "buildTarget": "my-app:build:production"
+            }
+          }
+        },
+        "test": {
+          "builder": "@analogjs/vitest-angular:test"
+        }
+      }
+    }
+  }
+}

package/template/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>NgMd</title>
+    <meta
+      name="description"
+      content="Modern Angular docs-site starter built on AnalogJS, Spartan UI, and Tailwind. Drop a markdown file, get a route."
+    />
+    <meta property="og:title" content="NgMd" />
+    <meta
+      property="og:description"
+      content="Modern Angular docs-site starter built on AnalogJS, Spartan UI, and Tailwind. Drop a markdown file, get a route."
+    />
+    <meta property="og:image" content="/logo.svg" />
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="alternate icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@500;700&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/src/styles.css" />
+    <script>
+      (function () {
+        try {
+          var stored = localStorage.getItem('ngmd-theme');
+          var mode = stored === 'light' || stored === 'dark' ? stored : 'auto';
+          var resolved =
+            mode === 'auto'
+              ? matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light'
+              : mode;
+          if (resolved === 'dark') document.documentElement.classList.add('dark');
+        } catch (_) {}
+      })();
+    </script>
+  </head>
+  <body>
+    <app-root></app-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/link-guard.plugin.ts

@@ -0,0 +1,190 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { Plugin } from 'vite';
+
+/**
+ * Build-time guard that errors on broken internal links inside markdown files.
+ *
+ * Validates three cases:
+ *   - `[text](#fragment)` — fragment must be a real heading slug in the same file
+ *   - `[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`.
+ * External (`http(s)://`), mail (`mailto:`), and relative (`./foo`) links are
+ * skipped; the existing externalLinkGuard covers raw HTML external anchors.
+ *
+ * Heading slugs are computed with the same lowercase + dash + strip-punct
+ * 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()
+    .replace(/[`*_~]/g, '')
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+function walkPageFiles(dir: string, root: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkPageFiles(full, root, out);
+    } else if (entry.isFile() && entry.name.endsWith('.page.ts')) {
+      out.push(relative(root, full));
+    }
+  }
+  return out;
+}
+
+function routeFromPagePath(rel: string): string {
+  const trimmed = rel
+    .replace(/^src\/app\/pages\//, '')
+    .replace(/\.page\.ts$/, '');
+  if (trimmed === 'index') return '/';
+  if (trimmed.startsWith('[')) return '';
+  return '/' + trimmed;
+}
+
+function extractHeadings(markdown: string): Set<string> {
+  const slugs = new Set<string>();
+  const headingRe = /^#{1,6}\s+(.+?)\s*$/gm;
+  let m;
+  while ((m = headingRe.exec(markdown)) !== null) {
+    slugs.add(slugify(m[1]));
+  }
+  return slugs;
+}
+
+export function internalLinkGuard(): Plugin {
+  let root = process.cwd();
+  // route → headings, populated lazily on first transform() call
+  const headingsByRoute = new Map<string, Set<string>>();
+  // route → source file (relative path)
+  const routes = new Map<string, string>();
+  let primed = false;
+
+  function prime(): void {
+    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;
+      }
+      routes.set(route, rel);
+      headingsByRoute.set(route, extractHeadings(readFileSync(full, 'utf8')));
+    }
+
+    // .page.ts → route (no heading scrape; just makes the route resolvable)
+    const pagesDir = join(root, 'src/app/pages');
+    try {
+      const pageFiles = walkPageFiles(pagesDir, root);
+      for (const rel of pageFiles) {
+        const route = routeFromPagePath(rel);
+        if (!route) continue;
+        if (!routes.has(route)) routes.set(route, rel);
+      }
+    } catch {
+      // src/app/pages missing — fine for non-app projects
+    }
+  }
+
+  return {
+    name: 'ngmd-internal-link-guard',
+    enforce: 'pre',
+    configResolved(cfg) {
+      root = cfg.root;
+    },
+    transform(_code, id) {
+      // Vite may append `?import` / `?raw` query suffixes
+      const cleanId = id.split('?')[0];
+      if (!cleanId.endsWith('.md')) return null;
+      prime();
+
+      const file = cleanId;
+      const content = readFileSync(file, 'utf8');
+      const ownSlugs = extractHeadings(content);
+      const issues: string[] = [];
+
+      const validate = (href: string, label: string) => {
+        if (!href) return;
+        // external / mail / relative — skip
+        if (
+          /^(https?:|mailto:|tel:|#)/.test(href) === false &&
+          !href.startsWith('/')
+        )
+          return;
+        if (/^(https?:|mailto:|tel:)/.test(href)) return;
+
+        const [path, fragment] = href.split('#');
+        if (path === '') {
+          // in-page fragment: must exist in this file
+          if (fragment && !ownSlugs.has(fragment)) {
+            issues.push(
+              `  ${label} → "#${fragment}" has no matching heading in this file`,
+            );
+          }
+          return;
+        }
+
+        // absolute route: must be a known route
+        if (!routes.has(path)) {
+          issues.push(`  ${label} → "${path}" is not a known route`);
+          return;
+        }
+        if (fragment) {
+          const targetSlugs = headingsByRoute.get(path);
+          if (targetSlugs && !targetSlugs.has(fragment)) {
+            issues.push(
+              `  ${label} → "${path}#${fragment}" — fragment not found in target page`,
+            );
+          }
+          // if targetSlugs is undefined (e.g. .page.ts route), skip fragment check
+        }
+      };
+
+      const mdLinkRe = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+      const htmlAnchorRe = /<a\s[^>]*href=["']([^"']+)["']/g;
+      let m: RegExpExecArray | null;
+      while ((m = mdLinkRe.exec(content)) !== null) {
+        validate(m[2], `[${m[1]}](${m[2]})`);
+      }
+      while ((m = htmlAnchorRe.exec(content)) !== null) {
+        validate(m[1], `<a href="${m[1]}">`);
+      }
+
+      if (issues.length > 0) {
+        this.error(
+          `[ngmd] Broken internal links in ${relative(root, file)}:\n${issues.join('\n')}\n` +
+            `Fix the link target, or update the heading slug it points to.`,
+        );
+      }
+
+      return null;
+    },
+  };
+}

package/template/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "ngmd",
+  "version": "0.0.1",
+  "description": "NgMd docs site",
+  "license": "MIT",
+  "keywords": [
+    "angular",
+    "analogjs",
+    "spartan-ui",
+    "tailwind",
+    "docs",
+    "documentation",
+    "starter",
+    "shiki",
+    "markdown"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.1"
+  },
+  "scripts": {
+    "ng": "ng",
+    "dev": "vite",
+    "start": "pnpm run dev",
+    "build": "vite build",
+    "watch": "vite build --watch",
+    "test": "vitest",
+    "preview": "node dist/analog/server/index.mjs"
+  },
+  "dependencies": {
+    "@analogjs/content": "^2.5.1",
+    "@analogjs/router": "^2.5.1",
+    "@angular/animations": "^21.0.0",
+    "@angular/common": "^21.0.0",
+    "@angular/compiler": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/forms": "^21.0.0",
+    "@angular/platform-browser": "^21.0.0",
+    "@angular/platform-server": "^21.0.0",
+    "@angular/router": "^21.0.0",
+    "@spartan-ng/brain": "0.0.1-alpha.694",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.1.4",
+    "front-matter": "^4.0.2",
+    "h3": "^1.13.0",
+    "lucide-angular": "^0.577.0",
+    "marked": "^15.0.7",
+    "marked-gfm-heading-id": "^4.1.1",
+    "marked-highlight": "^2.2.1",
+    "marked-mangle": "^1.1.10",
+    "marked-shiki": "^1.2.1",
+    "postcss": "^8.5.3",
+    "prismjs": "^1.29.0",
+    "rxjs": "~7.8.0",
+    "shiki": "^1.29.2",
+    "tailwindcss": "^4.1.4",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@analogjs/platform": "^2.5.1",
+    "@analogjs/vite-plugin-angular": "^2.5.1",
+    "@analogjs/vitest-angular": "^2.5.1",
+    "@angular/build": "^21.0.0",
+    "@angular/cli": "^21.0.0",
+    "@angular/compiler-cli": "^21.0.0",
+    "jsdom": "^22.0.0",
+    "typescript": "~5.9.0",
+    "vite": "^8.0.0",
+    "vite-tsconfig-paths": "^4.2.0",
+    "vitest": "^4.1.0"
+  },
+  "overrides": {
+    "vite": "$vite",
+    "vitest": "$vitest"
+  }
+}