create-ngmd 0.0.1

package/template/src/app/ui/image.ts

@@ -0,0 +1,26 @@
+import { Component, input } from '@angular/core';
+
+@Component({
+  selector: 'ngmd-image',
+  template: `
+    <figure class="my-6 mx-0" [style.max-width]="width()">
+      <img
+        [src]="src()"
+        [alt]="alt()"
+        loading="lazy"
+        class="w-full h-auto rounded-lg border border-zinc-200 dark:border-zinc-800"
+      />
+      @if (caption()) {
+        <figcaption class="mt-2 text-center text-sm text-zinc-500 dark:text-zinc-400">
+          {{ caption() }}
+        </figcaption>
+      }
+    </figure>
+  `,
+})
+export class NgmdImage {
+  readonly src = input.required<string>();
+  readonly alt = input<string>('');
+  readonly caption = input<string>('');
+  readonly width = input<string>('');
+}

package/template/src/app/ui/index.ts

@@ -0,0 +1,45 @@
+export { NgmdAlert } from './alert';
+export { NgmdCallout } from './callout';
+export { NgmdCard } from './card';
+export { NgmdCodeBlock } from './code-block';
+export { NgmdHero } from './hero';
+export { NgmdImage } from './image';
+export { NgmdPill, NgmdPillRow } from './pill';
+export { NgmdStep, NgmdWorkflow } from './workflow';
+export { NgmdTab, NgmdTabs } from './tabs';
+export { NgmdVideo } from './video';
+
+import { NgmdAlert } from './alert';
+import { NgmdCallout } from './callout';
+import { NgmdCard } from './card';
+import { NgmdCodeBlock } from './code-block';
+import { NgmdHero } from './hero';
+import { NgmdImage } from './image';
+import { NgmdPill, NgmdPillRow } from './pill';
+import { NgmdStep, NgmdWorkflow } from './workflow';
+import { NgmdTab, NgmdTabs } from './tabs';
+import { NgmdVideo } from './video';
+
+/**
+ * Spread into a page's `imports` to get every chrome component in one go:
+ *   `imports: [...NgmdUi]`. For lighter pages, import only what you use.
+ *
+ * Not declared `as const`: Angular's standalone-component compiler needs
+ * to resolve the array contents statically; a readonly tuple makes it
+ * bail out and the page silently renders empty.
+ */
+export const NgmdUi = [
+  NgmdAlert,
+  NgmdCallout,
+  NgmdCard,
+  NgmdCodeBlock,
+  NgmdHero,
+  NgmdImage,
+  NgmdPill,
+  NgmdPillRow,
+  NgmdStep,
+  NgmdWorkflow,
+  NgmdTab,
+  NgmdTabs,
+  NgmdVideo,
+];

package/template/src/app/ui/pill.ts

@@ -0,0 +1,42 @@
+import { Component, computed, input } from '@angular/core';
+import { RouterLink } from '@angular/router';
+
+@Component({
+  selector: 'ngmd-pill',
+  imports: [RouterLink],
+  template: `
+    @if (isExternal()) {
+      <a
+        [href]="href()"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="inline-flex items-center px-3 py-1 rounded-full border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-950 text-sm font-medium text-zinc-900 dark:text-zinc-100 no-underline transition-colors hover:bg-zinc-50 dark:hover:bg-zinc-900"
+      >
+        {{ title() }}
+      </a>
+    } @else {
+      <a
+        [routerLink]="href()"
+        class="inline-flex items-center px-3 py-1 rounded-full border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-950 text-sm font-medium text-zinc-900 dark:text-zinc-100 no-underline transition-colors hover:bg-zinc-50 dark:hover:bg-zinc-900"
+      >
+        {{ title() }}
+      </a>
+    }
+  `,
+})
+export class NgmdPill {
+  readonly href = input.required<string>();
+  readonly title = input.required<string>();
+
+  readonly isExternal = computed(() => /^https?:\/\//.test(this.href()));
+}
+
+@Component({
+  selector: 'ngmd-pill-row',
+  template: `
+    <div class="flex flex-wrap gap-2 my-4">
+      <ng-content></ng-content>
+    </div>
+  `,
+})
+export class NgmdPillRow {}

package/template/src/app/ui/tabs.ts

@@ -0,0 +1,76 @@
+import { NgTemplateOutlet } from '@angular/common';
+import {
+  AfterContentInit,
+  Component,
+  ContentChildren,
+  Directive,
+  inject,
+  input,
+  QueryList,
+  signal,
+  TemplateRef,
+} from '@angular/core';
+import { BrnTabsImports } from '@spartan-ng/brain/tabs';
+
+@Directive({
+  selector: 'ng-template[ngmdTab]',
+  standalone: true,
+})
+export class NgmdTab {
+  readonly title = input.required<string>({ alias: 'ngmdTab' });
+  readonly templateRef = inject(TemplateRef);
+}
+
+@Component({
+  selector: 'ngmd-tabs',
+  imports: [BrnTabsImports, NgTemplateOutlet],
+  template: `
+    <div
+      [brnTabs]="active()"
+      (brnTabsChange)="active.set($any($event))"
+      class="my-6 rounded-xl border border-zinc-200 dark:border-zinc-800 overflow-hidden"
+    >
+      <div
+        brnTabsList
+        class="flex flex-wrap border-b border-zinc-200 dark:border-zinc-800 bg-zinc-50 dark:bg-zinc-900"
+      >
+        @for (tab of tabs(); track tab.key) {
+          <button
+            type="button"
+            [brnTabsTrigger]="tab.key"
+            class="px-4 py-2.5 text-sm font-medium border-b-2 cursor-pointer transition-colors data-[state=active]:border-zinc-900 dark:data-[state=active]:border-zinc-100 data-[state=active]:text-zinc-900 dark:data-[state=active]:text-zinc-100 data-[state=inactive]:border-transparent data-[state=inactive]:text-zinc-500 hover:text-zinc-900 dark:hover:text-zinc-100 bg-transparent"
+          >
+            {{ tab.label }}
+          </button>
+        }
+      </div>
+
+      @for (tab of tabs(); track tab.key) {
+        <div
+          [brnTabsContent]="tab.key"
+          class="p-5 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0"
+        >
+          <ng-container *ngTemplateOutlet="tab.template"></ng-container>
+        </div>
+      }
+    </div>
+  `,
+})
+export class NgmdTabs implements AfterContentInit {
+  @ContentChildren(NgmdTab) private readonly children!: QueryList<NgmdTab>;
+
+  readonly tabs = signal<
+    { key: string; label: string; template: TemplateRef<unknown> }[]
+  >([]);
+  readonly active = signal('');
+
+  ngAfterContentInit(): void {
+    const list = this.children.toArray().map((c, i) => ({
+      key: `tab-${i}`,
+      label: c.title(),
+      template: c.templateRef,
+    }));
+    this.tabs.set(list);
+    if (list[0]) this.active.set(list[0].key);
+  }
+}

package/template/src/app/ui/video.ts

@@ -0,0 +1,40 @@
+import { Component, computed, inject, input } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+
+@Component({
+  selector: 'ngmd-video',
+  template: `
+    <div class="relative w-full aspect-video my-6 rounded-xl overflow-hidden bg-zinc-100 dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800">
+      <iframe
+        [src]="safeUrl()"
+        [title]="title()"
+        class="absolute inset-0 w-full h-full border-0"
+        allow="accelerometer; encrypted-media; gyroscope; picture-in-picture"
+        allowfullscreen
+        loading="lazy"
+      ></iframe>
+    </div>
+  `,
+})
+export class NgmdVideo {
+  private readonly sanitizer = inject(DomSanitizer);
+
+  readonly src = input.required<string>();
+  readonly title = input<string>('Video player');
+
+  readonly safeUrl = computed(() =>
+    this.sanitizer.bypassSecurityTrustResourceUrl(this.embedUrl()),
+  );
+
+  private readonly embedUrl = computed(() => {
+    const src = this.src();
+    if (src.startsWith('https://www.youtube.com/embed/')) return src;
+    const yt = src.match(/youtube\.com\/watch\?v=([\w-]+)/);
+    if (yt) return `https://www.youtube.com/embed/${yt[1]}`;
+    const ytShort = src.match(/youtu\.be\/([\w-]+)/);
+    if (ytShort) return `https://www.youtube.com/embed/${ytShort[1]}`;
+    const vm = src.match(/vimeo\.com\/(\d+)/);
+    if (vm) return `https://player.vimeo.com/video/${vm[1]}`;
+    return src;
+  });
+}

package/template/src/app/ui/workflow.ts

@@ -0,0 +1,51 @@
+import {
+  AfterContentInit,
+  Component,
+  ContentChildren,
+  input,
+  QueryList,
+  signal,
+} from '@angular/core';
+
+@Component({
+  selector: 'ngmd-step',
+  template: `
+    <div class="flex gap-4 pb-8 relative ngmd-step">
+      <div
+        class="flex-shrink-0 w-10 h-10 rounded-full border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-950 flex items-center justify-center font-semibold text-sm relative z-10"
+      >
+        {{ index() + 1 }}
+      </div>
+      <div class="flex-1 min-w-0">
+        @if (title()) {
+          <h3 class="text-lg font-semibold mt-1.5 mb-2 text-zinc-900 dark:text-zinc-100">{{ title() }}</h3>
+        }
+        <div class="text-zinc-700 dark:text-zinc-300 leading-relaxed [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+          <ng-content></ng-content>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NgmdStep {
+  readonly title = input<string>('');
+  readonly index = signal(0);
+}
+
+@Component({
+  selector: 'ngmd-workflow',
+  template: `
+    <div
+      class="my-8 [&_.ngmd-step:not(:last-child)]:before:content-[''] [&_.ngmd-step:not(:last-child)]:before:absolute [&_.ngmd-step:not(:last-child)]:before:left-5 [&_.ngmd-step:not(:last-child)]:before:top-11 [&_.ngmd-step:not(:last-child)]:before:bottom-0 [&_.ngmd-step:not(:last-child)]:before:w-px [&_.ngmd-step:not(:last-child)]:before:bg-zinc-200 dark:[&_.ngmd-step:not(:last-child)]:before:bg-zinc-800"
+    >
+      <ng-content></ng-content>
+    </div>
+  `,
+})
+export class NgmdWorkflow implements AfterContentInit {
+  @ContentChildren(NgmdStep) private readonly steps!: QueryList<NgmdStep>;
+
+  ngAfterContentInit(): void {
+    this.steps.forEach((step, i) => step.index.set(i));
+  }
+}

package/template/src/content/welcome.md

@@ -0,0 +1,19 @@
+---
+title: Welcome
+---
+
+# Welcome
+
+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.
+
+## Add nav
+
+Edit the `nav` array in `src/ngmd.config.ts`. Sidebar, command palette, breadcrumb, and prev/next footer all read from there.
+
+## Authoring components
+
+NgMd ships a small chrome 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.

package/template/src/main.server.ts

@@ -0,0 +1,7 @@
+import '@angular/platform-server/init';
+import { render } from '@analogjs/router/server';
+
+import { App } from './app/app';
+import { config } from './app/app.config.server';
+
+export default render(App, config);

package/template/src/main.ts

@@ -0,0 +1,6 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+
+bootstrapApplication(App, appConfig);

package/template/src/marked-extensions/index.ts

@@ -0,0 +1,47 @@
+import type { MarkedExtension } from 'marked';
+import { ngmdVideoExtension } from './ngmd-video';
+import { ngmdImageExtension } from './ngmd-image';
+import { ngmdKeywordsExtension } from './ngmd-keywords';
+
+/**
+ * Marked extensions are split into two arrays.
+ *
+ * `ngmdRuntimeExtensions` — safe to register on the browser-side marked
+ * instance via `app.config.ts > provideAppInitializer`. Only token-level
+ * extensions with no Node deps (currently `<ngmd-video>` and `<ngmd-image>`).
+ *
+ * `ngmdBuildExtensions` — used at build time by `vite.config.ts >
+ * markedOptions.extensions`. Adds the build-only extensions that touch
+ * `node:fs` (code-import) or load a shiki highlighter (code-group), which
+ * would crash if pulled into the client bundle.
+ *
+ * Chrome (cards, tabs, callouts, alerts, pill rows, workflows, hero, code
+ * blocks) lives as Angular components under `src/app/ui/`, not here.
+ */
+export const ngmdRuntimeExtensions: MarkedExtension[] = [
+  {
+    extensions: [ngmdVideoExtension, ngmdImageExtension],
+  },
+  ngmdKeywordsExtension,
+];
+
+// Build-time-only extensions are imported lazily below so the runtime bundle
+// never resolves their `node:fs` / `shiki` imports. The async getter is
+// called by `vite.config.ts` (Node context) only.
+export async function getBuildExtensions(): Promise<MarkedExtension[]> {
+  const [
+    { ngmdCodeImportExtension },
+    { ngmdCodeGroupExtension },
+    { ngmdCodeHighlightExtension },
+  ] = await Promise.all([
+    import('./ngmd-code-import'),
+    import('./ngmd-code-group'),
+    import('./ngmd-code-highlight'),
+  ]);
+  return [
+    ...ngmdRuntimeExtensions,
+    ngmdCodeImportExtension,
+    ngmdCodeGroupExtension,
+    ngmdCodeHighlightExtension,
+  ];
+}

package/template/src/marked-extensions/ngmd-code-group.ts

@@ -0,0 +1,126 @@
+import type { MarkedExtension } from 'marked';
+import { getHighlighter, LANGS, escapeHtml } from './shiki-shared';
+
+/**
+ * Adjacent fenced code blocks tagged with `group="..."` merge into a tabbed
+ * UI. Tab labels default to the language; pass `name="pnpm"` to override.
+ * Mark the initial tab with the `active` flag.
+ *
+ *   ```bash group="install" name="pnpm" active
+ *   pnpm create ngmd@latest my-docs
+ *   ```
+ *
+ *   ```bash group="install" name="npm"
+ *   npm create ngmd@latest my-docs
+ *   ```
+ *
+ * Implementation: preprocess runs before marked tokenizes. It finds
+ * consecutive group fences, pre-renders each body through a cached shiki
+ * highlighter, and emits a single self-contained HTML wrapper. By the time
+ * marked sees it, it's a finished `<div>` block with `<pre>` children — no
+ * fenced-code re-parsing, no tokenizer race with marked-shiki, no marked
+ * HTML-block quirks.
+ */
+
+let groupCounter = 0;
+
+const FENCE_WITH_GROUP_RE =
+  /^```([\w-]+)?[\t ]+([^\n]*?\bgroup="([^"]+)"[^\n]*)\n([\s\S]*?)\n```$/gm;
+
+interface Fence {
+  start: number;
+  end: number;
+  lang: string;
+  attrs: string;
+  group: string;
+  body: string;
+}
+
+function getAttr(attrs: string, name: string): string | undefined {
+  return new RegExp(`${name}="([^"]*)"`).exec(attrs)?.[1];
+}
+
+function hasFlag(attrs: string, name: string): boolean {
+  return new RegExp(`(^|\\s)${name}(\\s|$)`).test(attrs);
+}
+
+async function renderCode(body: string, lang: string): Promise<string> {
+  const safeLang = LANGS.includes(lang) ? lang : 'text';
+  const highlighter = await getHighlighter();
+  return highlighter.codeToHtml(body, { lang: safeLang, theme: 'github-dark' });
+}
+
+export const ngmdCodeGroupExtension: MarkedExtension = {
+  hooks: {
+    async preprocess(markdown: string): Promise<string> {
+      const fences: Fence[] = [];
+      const re = new RegExp(
+        FENCE_WITH_GROUP_RE.source,
+        FENCE_WITH_GROUP_RE.flags,
+      );
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(markdown)) !== null) {
+        fences.push({
+          start: m.index,
+          end: m.index + m[0].length,
+          lang: m[1] ?? '',
+          attrs: m[2],
+          group: m[3],
+          body: m[4],
+        });
+      }
+      if (fences.length === 0) return markdown;
+
+      // Cluster consecutive same-group fences (whitespace-only between).
+      const clusters: Fence[][] = [];
+      let current: Fence[] = [];
+      for (const f of fences) {
+        if (
+          current.length > 0 &&
+          current[0].group === f.group &&
+          /^\s*$/.test(markdown.slice(current.at(-1)!.end, f.start))
+        ) {
+          current.push(f);
+        } else {
+          if (current.length > 0) clusters.push(current);
+          current = [f];
+        }
+      }
+      if (current.length > 0) clusters.push(current);
+
+      // Replace from end to start so indices stay valid.
+      let result = markdown;
+      for (let i = clusters.length - 1; i >= 0; i--) {
+        const c = clusters[i];
+        if (c.length < 2) continue;
+
+        const groupId = `cg-${++groupCounter}`;
+        let activeIdx = c.findIndex((f) => hasFlag(f.attrs, 'active'));
+        if (activeIdx === -1) activeIdx = 0;
+
+        const tabs = c
+          .map((f, idx) => {
+            const name = getAttr(f.attrs, 'name') ?? (f.lang || `tab ${idx + 1}`);
+            return `<button type="button" class="ngmd-code-group__tab" data-target="${groupId}-${idx}" data-active="${idx === activeIdx}">${escapeHtml(name)}</button>`;
+          })
+          .join('');
+
+        const panels = (
+          await Promise.all(
+            c.map(async (f, idx) => {
+              const html = await renderCode(f.body, f.lang);
+              return `<div class="ngmd-code-group__panel" data-id="${groupId}-${idx}" data-active="${idx === activeIdx}">${html}</div>`;
+            }),
+          )
+        ).join('');
+
+        const wrapper = `\n\n<div class="ngmd-code-group" data-group="${groupId}"><div class="ngmd-code-group__tabs">${tabs}</div>${panels}</div>\n\n`;
+
+        result =
+          result.slice(0, c[0].start) + wrapper + result.slice(c.at(-1)!.end);
+      }
+
+      return result;
+    },
+  },
+};

package/template/src/marked-extensions/ngmd-code-highlight.ts

@@ -0,0 +1,102 @@
+import type { MarkedExtension } from 'marked';
+import { getHighlighter, LANGS } from './shiki-shared';
+
+/**
+ * Fenced code blocks tagged with `{1,3-5}` get the matching lines visually
+ * highlighted. Comma-separated ranges, GitHub-style: `{1}`, `{3-5}`, `{1,3-5,8}`.
+ *
+ *   ```ts {3-5}
+ *   import { Component } from '@angular/core';
+ *
+ *   @Component({
+ *     selector: 'app-hello',
+ *     template: '<h1>Hello</h1>',
+ *   })
+ *   export class Hello {}
+ *   ```
+ *
+ * Implementation: preprocess detects the meta, pre-renders the fence via a
+ * cached shiki highlighter, then post-processes the rendered HTML to add
+ * `class="highlighted"` to matching `<span class="line">` elements. CSS in
+ * styles.css tints those lines.
+ *
+ * Scope: skips fences with `group="..."` (handled by ngmd-code-group) or
+ * `file="..."` (handled by ngmd-code-import). One fence, one treatment.
+ */
+
+// Capture: lang, line ranges in {}, body. Skips fences whose info string
+// contains `group=` or `file=` so those routes own the fence.
+const FENCE_RE =
+  /^```([\w-]+)?[\t ]+\{([0-9,\-\s]+)\}[\t ]*\n([\s\S]*?)\n```$/gm;
+
+function parseRanges(spec: string): Set<number> {
+  const lines = new Set<number>();
+  for (const part of spec.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const m = part.match(/^(\d+)(?:-(\d+))?$/);
+    if (!m) continue;
+    const start = parseInt(m[1], 10);
+    const end = m[2] ? parseInt(m[2], 10) : start;
+    for (let i = start; i <= end; i++) lines.add(i);
+  }
+  return lines;
+}
+
+/**
+ * Walks the shiki output's `<span class="line">` elements, adds the
+ * `highlighted` class to lines whose 1-indexed position is in `set`.
+ */
+function applyHighlights(html: string, set: Set<number>): string {
+  let lineNum = 0;
+  return html.replace(/<span class="line"/g, () => {
+    lineNum++;
+    return set.has(lineNum)
+      ? '<span class="line highlighted"'
+      : '<span class="line"';
+  });
+}
+
+export const ngmdCodeHighlightExtension: MarkedExtension = {
+  hooks: {
+    async preprocess(markdown: string): Promise<string> {
+      // Quick negative check before scanning.
+      if (!/^```[\w-]*[\t ]+\{[0-9,\-\s]+\}/m.test(markdown)) return markdown;
+
+      const matches: { start: number; end: number; lang: string; spec: string; body: string }[] = [];
+      const re = new RegExp(FENCE_RE.source, FENCE_RE.flags);
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(markdown)) !== null) {
+        // Skip if the fence also carries `group=` or `file=` (other ext owns).
+        const infoLineEnd = markdown.indexOf('\n', m.index);
+        const infoLine = markdown.slice(m.index, infoLineEnd);
+        if (/\b(?:group|file)="/.test(infoLine)) continue;
+        matches.push({
+          start: m.index,
+          end: m.index + m[0].length,
+          lang: m[1] ?? '',
+          spec: m[2],
+          body: m[3],
+        });
+      }
+      if (matches.length === 0) return markdown;
+
+      const highlighter = await getHighlighter();
+      const renders = await Promise.all(
+        matches.map(async (mt) => {
+          const safeLang = LANGS.includes(mt.lang) ? mt.lang : 'text';
+          const raw = highlighter.codeToHtml(mt.body, {
+            lang: safeLang,
+            theme: 'github-dark',
+          });
+          return applyHighlights(raw, parseRanges(mt.spec));
+        }),
+      );
+
+      let result = markdown;
+      for (let i = matches.length - 1; i >= 0; i--) {
+        const mt = matches[i];
+        result = result.slice(0, mt.start) + `\n\n${renders[i]}\n\n` + result.slice(mt.end);
+      }
+      return result;
+    },
+  },
+};