create-ngmd 0.0.1

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

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { MarkedExtension } from 'marked';
+import { getHighlighter, LANGS, escapeHtml } from './shiki-shared';
+import config from '../ngmd.config';
+
+/**
+ * Fenced code blocks can import their content from a source file by adding
+ * `file="..."` to the info string. Supports GitHub-style `#L5-L20` line
+ * ranges so docs reference the *real* code instead of a hand-typed copy
+ * that rots out of sync.
+ *
+ *   ```ts file="src/app/hello.ts"
+ *   ```
+ *
+ *   ```ts file="src/app/hello.ts#L5-L20"
+ *   ```
+ *
+ * Renders as a `<div class="ngmd-code-import">` wrapper with a header bar
+ * linking to the file on GitHub (via `ngmd.config.ts > site.githubUrl`).
+ * Lines marked `// ngmd-ignore-line` are stripped from the imported snippet.
+ *
+ * Pre-rendered through the shared shiki highlighter so the output is one
+ * self-contained HTML block — marked never sees the inner fence.
+ */
+
+const FENCE_RE =
+  /^```([\w-]+)?[\t ]+file="([^"]+)"[^\n]*\n(?:([\s\S]*?)\n)?```$/gm;
+const IGNORE_LINE_RE = /^.*\/\/\s*ngmd-ignore-line\s*$/;
+
+function loadFile(spec: string): { code: string; rangeFragment: string } {
+  const [path, range] = spec.split('#');
+  const full = resolve(process.cwd(), path);
+  let content = readFileSync(full, 'utf8');
+
+  let rangeFragment = '';
+  if (range) {
+    const m = range.match(/^L(\d+)(?:-L?(\d+))?$/);
+    if (m) {
+      const start = parseInt(m[1], 10);
+      const end = m[2] ? parseInt(m[2], 10) : start;
+      const lines = content.split('\n');
+      content = lines.slice(start - 1, end).join('\n');
+      rangeFragment = m[2] ? `#L${start}-L${end}` : `#L${start}`;
+    }
+  }
+
+  const filtered = content
+    .split('\n')
+    .filter((l) => !IGNORE_LINE_RE.test(l))
+    .join('\n');
+
+  return { code: filtered.replace(/\n+$/, ''), rangeFragment };
+}
+
+function githubBlobUrl(filePath: string, rangeFragment: string): string {
+  const repo = config.site.githubUrl.replace(/\.git$/, '');
+  return `${repo}/blob/main/${filePath}${rangeFragment}`;
+}
+
+export const ngmdCodeImportExtension: MarkedExtension = {
+  hooks: {
+    async preprocess(markdown: string): Promise<string> {
+      if (!/^```[\w-]*[\t ]+file="/m.test(markdown)) return markdown;
+
+      const matches: {
+        start: number;
+        end: number;
+        lang: string;
+        filePath: string;
+        rangeFragment: string;
+        code: string;
+      }[] = [];
+
+      const re = new RegExp(FENCE_RE.source, FENCE_RE.flags);
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(markdown)) !== null) {
+        const lang = m[1] ?? '';
+        const spec = m[2];
+        try {
+          const { code, rangeFragment } = loadFile(spec);
+          matches.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            lang,
+            filePath: spec.split('#')[0],
+            rangeFragment,
+            code,
+          });
+        } catch (e) {
+          const msg = (e as Error).message ?? String(e);
+          console.warn(`[ngmd-code-import] failed to load "${spec}": ${msg}`);
+        }
+      }
+      if (matches.length === 0) return markdown;
+
+      const highlighter = await getHighlighter();
+      const renders = matches.map((mt) => {
+        const safeLang = LANGS.includes(mt.lang) ? mt.lang : 'text';
+        const codeHtml = highlighter.codeToHtml(mt.code, {
+          lang: safeLang,
+          theme: 'github-dark',
+        });
+        const headerLabel = mt.filePath + (mt.rangeFragment || '');
+        const headerHtml = `<a class="ngmd-code-import__header" href="${escapeHtml(githubBlobUrl(mt.filePath, mt.rangeFragment))}" target="_blank" rel="noopener noreferrer">${escapeHtml(headerLabel)}</a>`;
+        return `<div class="ngmd-code-import">${headerHtml}${codeHtml}</div>`;
+      });
+
+      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;
+    },
+  },
+};

package/template/src/marked-extensions/ngmd-image.ts

@@ -0,0 +1,41 @@
+import type { Tokens } from 'marked';
+
+interface NgmdImageToken extends Tokens.Generic {
+  type: 'ngmd-image';
+  src: string;
+  alt: string;
+  caption?: string;
+  width?: string;
+}
+
+const tagRule = /^<ngmd-image([^>]*)\/>/s;
+const attrRule = (name: string) => new RegExp(`${name}="([^"]*)"`);
+
+export const ngmdImageExtension = {
+  name: 'ngmd-image',
+  level: 'block' as const,
+  start(src: string) {
+    return src.match(/^\s*<ngmd-image/m)?.index;
+  },
+  tokenizer(src: string): NgmdImageToken | undefined {
+    const match = tagRule.exec(src);
+    if (!match) return undefined;
+    const attrs = match[1].trim();
+    const srcMatch = attrRule('src').exec(attrs);
+    if (!srcMatch) return undefined;
+    return {
+      type: 'ngmd-image',
+      raw: match[0],
+      src: srcMatch[1],
+      alt: attrRule('alt').exec(attrs)?.[1] ?? '',
+      caption: attrRule('caption').exec(attrs)?.[1],
+      width: attrRule('width').exec(attrs)?.[1],
+    };
+  },
+  renderer(token: NgmdImageToken) {
+    const widthAttr = token.width ? token.width.replace(/"/g, '') : '';
+    const alt = token.alt.replace(/"/g, '&quot;');
+    const caption = token.caption ? token.caption.replace(/"/g, '&quot;') : '';
+    return `<div class="ngmd-image" data-image-src="${token.src}" data-image-alt="${alt}" data-image-caption="${caption}" data-image-width="${widthAttr}"></div>`;
+  },
+};

package/template/src/marked-extensions/ngmd-keywords.ts

@@ -0,0 +1,75 @@
+import type { MarkedExtension, Tokens } from 'marked';
+import config from '../ngmd.config';
+
+/**
+ * Inline keyword auto-linking. Any `*Keyword` token (where `Keyword` is
+ * defined in `ngmd.config.ts > keywords`) becomes a link.
+ *
+ *   *AnalogJS  →  <a href="https://analogjs.org">AnalogJS</a>
+ *   *NgMd      →  <a href="/welcome">NgMd</a>
+ *
+ * Unknown keywords log a one-line warning and fall through to the default
+ * inline tokenizer — they render as literal `*Keyword` text. External URLs
+ * get `target="_blank" rel="noopener noreferrer"` automatically.
+ *
+ * Lives in the inline tokenizer chain, so it never fires inside fenced code
+ * blocks or inline code (those are block-level and tokenized first).
+ */
+
+interface NgmdKeywordToken extends Tokens.Generic {
+  type: 'ngmdKeyword';
+  keyword: string;
+  url: string;
+}
+
+const KEYWORD_RE = /^\*([A-Z][a-zA-Z0-9]+)\b/;
+const HINT_RE = /\*[A-Z]/;
+const warned = new Set<string>();
+
+function lookup(keyword: string): string | undefined {
+  return config.keywords?.[keyword];
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/"/g, '&quot;');
+}
+
+export const ngmdKeywordsExtension: MarkedExtension = {
+  extensions: [
+    {
+      name: 'ngmdKeyword',
+      level: 'inline',
+      start(src: string) {
+        return src.match(HINT_RE)?.index;
+      },
+      tokenizer(src: string): NgmdKeywordToken | undefined {
+        const m = KEYWORD_RE.exec(src);
+        if (!m) return undefined;
+        const url = lookup(m[1]);
+        if (!url) {
+          if (!warned.has(m[1])) {
+            warned.add(m[1]);
+            console.warn(
+              `[ngmd-keywords] unknown keyword "${m[1]}" — add it to ngmd.config.ts > keywords or escape the asterisk.`,
+            );
+          }
+          return undefined;
+        }
+        return {
+          type: 'ngmdKeyword',
+          raw: m[0],
+          keyword: m[1],
+          url,
+        };
+      },
+      renderer(token: Tokens.Generic) {
+        const t = token as NgmdKeywordToken;
+        const isExternal = /^https?:\/\//.test(t.url);
+        const targetAttrs = isExternal
+          ? ' target="_blank" rel="noopener noreferrer"'
+          : '';
+        return `<a href="${escapeAttr(t.url)}"${targetAttrs}>${t.keyword}</a>`;
+      },
+    },
+  ],
+};

package/template/src/marked-extensions/ngmd-video.ts

@@ -0,0 +1,48 @@
+import type { Tokens } from 'marked';
+
+interface NgmdVideoToken extends Tokens.Generic {
+  type: 'ngmd-video';
+  src: string;
+  title?: string;
+}
+
+const tagRule = /^<ngmd-video([^>]*)\/>/s;
+const srcRule = /src="([^"]*)"/;
+const titleRule = /title="([^"]*)"/;
+
+function buildEmbedUrl(src: string): string {
+  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;
+}
+
+export const ngmdVideoExtension = {
+  name: 'ngmd-video',
+  level: 'block' as const,
+  start(src: string) {
+    return src.match(/^\s*<ngmd-video/m)?.index;
+  },
+  tokenizer(src: string): NgmdVideoToken | undefined {
+    const match = tagRule.exec(src);
+    if (!match) return undefined;
+    const attrs = match[1].trim();
+    const srcMatch = srcRule.exec(attrs);
+    if (!srcMatch) return undefined;
+    return {
+      type: 'ngmd-video',
+      raw: match[0],
+      src: srcMatch[1],
+      title: titleRule.exec(attrs)?.[1],
+    };
+  },
+  renderer(token: NgmdVideoToken) {
+    const url = buildEmbedUrl(token.src);
+    const title = (token.title ?? 'Video player').replace(/"/g, '&quot;');
+    return `<div class="ngmd-video" data-video-src="${url}" data-video-title="${title}"></div>`;
+  },
+};

package/template/src/marked-extensions/shiki-shared.ts

@@ -0,0 +1,42 @@
+import { createHighlighter, type Highlighter } from 'shiki';
+
+/**
+ * Shared shiki highlighter instance used by every build-time fence extension
+ * that pre-renders code (code-group, code-import, code-highlight). Loading
+ * the highlighter is expensive (parses tmGrammar files for every language),
+ * so we keep a single promise per process.
+ */
+
+let highlighterPromise: Promise<Highlighter> | null = null;
+
+export const LANGS = [
+  'bash',
+  'json',
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'html',
+  'css',
+  'md',
+  'angular-html',
+  'angular-ts',
+];
+
+export function getHighlighter(): Promise<Highlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: ['github-dark'],
+      langs: LANGS,
+    });
+  }
+  return highlighterPromise;
+}
+
+export function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/template/src/ngmd.config.ts

@@ -0,0 +1,98 @@
+/**
+ * NgMd site configuration.
+ *
+ * Edit this file to customise navigation, site metadata, and external links.
+ * Sidebar, command palette, breadcrumb, and header all read from here.
+ */
+
+export interface NavItem {
+  label: string;
+  href: string;
+}
+
+export interface NavSection {
+  label: string;
+  items: NavItem[];
+}
+
+export interface SiteConfig {
+  /** Brand name shown in the header next to the logo. */
+  name: string;
+  /** One-liner description used in meta tags + social previews. */
+  description: string;
+  /** Short tagline shown after the brand in the homepage `<title>`. */
+  tagline?: string;
+  /** Public origin (no trailing slash). Used by sitemap.xml + robots.txt. */
+  url: string;
+  /** Repository URL. Powers the GitHub icon in the header. */
+  githubUrl: string;
+  /** Optional social / community links rendered in the header. */
+  links?: {
+    twitter?: string;
+    discord?: string;
+  };
+}
+
+export interface NgmdConfig {
+  site: SiteConfig;
+  /** Sidebar sections, in render order. */
+  nav: NavSection[];
+  /**
+   * Inline-link keywords. In any `.md` body, `*Keyword` resolves to a link
+   * pointing at the configured URL. Unknown keywords log a warning and fall
+   * back to literal `*Keyword` text. Change the URL here once, every doc
+   * follows.
+   */
+  keywords?: Record<string, string>;
+}
+
+const config: NgmdConfig = {
+  site: {
+    name: 'NgMd',
+    description:
+      'Modern Angular docs-site starter built on AnalogJS, Spartan UI, and Tailwind.',
+    tagline: 'Angular docs starter',
+    url: 'https://ngmd.netlify.app',
+    githubUrl: 'https://github.com/erkamyaman/ngmd',
+  },
+
+  keywords: {
+    NgMd: '/welcome',
+    AnalogJS: 'https://analogjs.org',
+    Angular: 'https://angular.dev',
+    Tailwind: 'https://tailwindcss.com',
+    Shiki: 'https://shiki.style',
+    Marked: 'https://marked.js.org',
+    Vite: 'https://vitejs.dev',
+    Spartan: 'https://www.spartan.ng',
+    VitePress: 'https://vitepress.dev',
+    Starlight: 'https://starlight.astro.build',
+    Docusaurus: 'https://docusaurus.io',
+    Nextra: 'https://nextra.site',
+  },
+
+  nav: [
+    {
+      label: 'Getting Started',
+      items: [{ label: 'Welcome', href: '/welcome' }],
+    },
+  ],
+};
+
+export default config;
+
+/** Flattened list of all nav items, useful for command palette / search. */
+export const navItems = config.nav.flatMap((section) =>
+  section.items.map((item) => ({
+    label: item.label,
+    href: item.href,
+    section: section.label,
+  })),
+);
+
+/** Map of last URL segment to its human label, useful for breadcrumb. */
+export const navLabels = Object.fromEntries(
+  config.nav.flatMap((section) =>
+    section.items.map((item) => [item.href.split('/').pop() ?? '', item.label]),
+  ),
+);

package/template/src/server/routes/api/v1/hello.ts

@@ -0,0 +1,3 @@
+import { defineEventHandler } from 'h3';
+
+export default defineEventHandler(() => ({ message: 'Hello World' }));