create-ngmd 0.0.1

package/template/src/styles.css

@@ -0,0 +1,347 @@
+@import 'tailwindcss';
+
+/* View Transitions API tuning. Angular's withViewTransitions() crossfades
+ * route changes via these pseudo-elements. Shorten the default ~250ms to
+ * 150ms so it stays snappy. */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 150ms;
+  animation-timing-function: ease;
+}
+@plugin '@tailwindcss/typography';
+
+@variant dark (&:where(.dark, .dark *));
+
+@layer base {
+  :root {
+    /* Surface */
+    --bg: #ffffff;
+    --bg-muted: #f4f4f5;
+    --fg: #0a0a0a;
+    --muted: #71717a;
+    --border: #e4e4e7;
+    --border-strong: #d4d4d8;
+
+    /* Brand (used by accent-aware components) */
+    --primary: #18181b;
+    --primary-fg: #fafafa;
+    --accent: #d946ef;
+    --accent-fg: #ffffff;
+    --accent-soft: rgba(217, 70, 239, 0.12);
+    --accent-gradient: linear-gradient(
+      to right,
+      #f43f5e 0%,
+      #d946ef 50%,
+      #a855f7 100%
+    );
+
+    /* Geometry */
+    --radius-sm: 0.25rem;
+    --radius: 0.5rem;
+    --radius-lg: 0.75rem;
+    --radius-xl: 1rem;
+
+    /* Typography */
+    --font-sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+      sans-serif;
+    --font-display: 'Geist Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+    --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+
+    font-family: var(--font-sans);
+    color-scheme: light;
+  }
+
+  .dark {
+    --bg: #0a0a0a;
+    --bg-muted: #18181b;
+    --fg: #fafafa;
+    --muted: #a1a1aa;
+    --border: #27272a;
+    --border-strong: #3f3f46;
+
+    --primary: #fafafa;
+    --primary-fg: #18181b;
+    --accent: #e879f9;
+    --accent-fg: #18181b;
+    --accent-soft: rgba(232, 121, 249, 0.15);
+
+    color-scheme: dark;
+  }
+
+  html,
+  body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--fg);
+    min-height: 100vh;
+  }
+
+  a {
+    text-decoration: inherit;
+  }
+}
+
+@layer components {
+  analog-markdown,
+  analog-markdown-route {
+    display: block;
+    color: var(--fg);
+    line-height: 1.7;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+  }
+
+  analog-markdown-route {
+    max-width: 48rem;
+    margin-inline: auto;
+    padding: 2rem;
+  }
+
+  analog-markdown h1,
+  analog-markdown-route h1 {
+    font-size: 2.25rem;
+    font-weight: 700;
+    line-height: 1.2;
+    margin-block: 0 1rem;
+    letter-spacing: -0.02em;
+    scroll-margin-top: 6rem;
+  }
+
+  analog-markdown h2,
+  analog-markdown-route h2 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    line-height: 1.3;
+    margin-block: 2.5rem 1rem;
+    padding-block-end: 0.5rem;
+    border-block-end: 1px solid var(--border);
+    letter-spacing: -0.01em;
+    scroll-margin-top: 6rem;
+  }
+
+  analog-markdown h3,
+  analog-markdown-route h3 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-block: 2rem 0.75rem;
+    scroll-margin-top: 6rem;
+  }
+
+  analog-markdown p,
+  analog-markdown-route p {
+    margin-block: 1rem;
+  }
+
+  analog-markdown ul,
+  analog-markdown-route ul,
+  analog-markdown ol,
+  analog-markdown-route ol {
+    margin-block: 1rem;
+    padding-inline-start: 1.5rem;
+  }
+
+  analog-markdown ul,
+  analog-markdown-route ul {
+    list-style: disc;
+  }
+
+  analog-markdown ol,
+  analog-markdown-route ol {
+    list-style: decimal;
+  }
+
+  analog-markdown li,
+  analog-markdown-route li {
+    margin-block: 0.25rem;
+  }
+
+  analog-markdown a,
+  analog-markdown-route a {
+    color: inherit;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    transition: color 0.15s ease;
+  }
+
+  analog-markdown a:hover,
+  analog-markdown-route a:hover {
+    color: var(--accent);
+  }
+
+  analog-markdown a:focus-visible,
+  analog-markdown-route a:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+    border-radius: 2px;
+  }
+
+  analog-markdown code:not(pre code),
+  analog-markdown-route code:not(pre code) {
+    background: color-mix(in srgb, var(--border) 60%, transparent);
+    padding: 0.15em 0.4em;
+    border-radius: 0.25rem;
+    font-size: 0.875em;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+
+  analog-markdown pre,
+  analog-markdown-route pre {
+    margin-block: 1.5rem;
+    padding: 1rem 1.25rem;
+    border-radius: 0.5rem;
+    overflow-x: auto;
+    font-size: 0.875rem;
+    line-height: 1.6;
+  }
+
+  analog-markdown pre code,
+  analog-markdown-route pre code {
+    background: transparent;
+    padding: 0;
+  }
+
+  analog-markdown blockquote,
+  analog-markdown-route blockquote {
+    border-inline-start: 3px solid var(--border);
+    padding-inline-start: 1rem;
+    margin-inline: 0;
+    color: var(--muted);
+    font-style: italic;
+  }
+
+  .ngmd-video {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 9;
+    margin-block: 1.5rem;
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+    background: var(--bg-muted);
+  }
+  .ngmd-video iframe {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    border: 0;
+  }
+
+  .ngmd-image {
+    margin-block: 1.5rem;
+    margin-inline: 0;
+  }
+  .ngmd-image img {
+    width: 100%;
+    height: auto;
+    border-radius: var(--radius);
+    border: 1px solid var(--border);
+  }
+  .ngmd-image figcaption {
+    margin-top: 0.5rem;
+    text-align: center;
+    font-size: 0.875rem;
+    color: var(--muted);
+  }
+
+  .ngmd-code-group {
+    margin-block: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+    background: var(--bg);
+  }
+  .ngmd-code-group__tabs {
+    display: flex;
+    flex-wrap: wrap;
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-muted);
+  }
+  .ngmd-code-group__tab {
+    appearance: none;
+    background: transparent;
+    border: 0;
+    border-bottom: 2px solid transparent;
+    padding: 0.625rem 1rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    cursor: pointer;
+    color: var(--muted);
+    font-family: var(--font-mono);
+    transition: color 0.15s ease, border-color 0.15s ease;
+  }
+  .ngmd-code-group__tab:hover {
+    color: var(--fg);
+  }
+  .ngmd-code-group__tab[data-active="true"] {
+    color: var(--accent);
+    border-bottom-color: var(--accent);
+  }
+  .ngmd-code-group__panel {
+    display: none;
+  }
+  .ngmd-code-group__panel[data-active="true"] {
+    display: block;
+  }
+  .ngmd-code-group__panel pre {
+    margin: 0;
+    border-radius: 0;
+    border: 0;
+  }
+
+  /* Shiki dual-theme: github-light by default, github-dark under `.dark`.
+   * Shiki emits both --shiki-light and --shiki-dark CSS vars on every span
+   * but never picks a default color, so we have to wire both branches. */
+  /* Scoped to `.shiki-themes` (only present on dual-theme output, never on
+   * single-theme build-time output) so we don't override the inline colours
+   * shiki emits for the build-time `.md` code blocks. */
+  .shiki-themes,
+  .shiki-themes span {
+    color: var(--shiki-light);
+    background-color: var(--shiki-light-bg);
+  }
+  .dark .shiki-themes,
+  .dark .shiki-themes span {
+    color: var(--shiki-dark) !important;
+    background-color: var(--shiki-dark-bg) !important;
+  }
+
+  /* Highlighted lines (from `{1,3-5}` meta on a fenced block).
+   * Shiki wraps each line in `<span class="line">`; the ngmd-code-highlight
+   * marked extension adds `highlighted` to lines in the spec. We render a
+   * full-bleed tinted background plus a left-edge accent stripe. */
+  .shiki .line.highlighted {
+    display: inline-block;
+    width: 100%;
+    background-color: rgba(217, 70, 239, 0.12);
+    box-shadow: inset 2px 0 var(--accent);
+  }
+
+  /* `<div class="ngmd-code-import">` wraps a file= imported code block with
+   * a header bar that links the file path to its GitHub source. */
+  .ngmd-code-import {
+    margin-block: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+    background: var(--bg);
+  }
+  .ngmd-code-import__header {
+    display: block;
+    padding: 0.5rem 1rem;
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-muted);
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    color: var(--muted);
+    text-decoration: none;
+    transition: color 0.15s ease;
+  }
+  .ngmd-code-import__header:hover {
+    color: var(--accent);
+  }
+  .ngmd-code-import pre {
+    margin: 0;
+    border: 0;
+    border-radius: 0;
+  }
+}

package/template/src/test-setup.ts

@@ -0,0 +1,6 @@
+import '@angular/compiler';
+import '@analogjs/vitest-angular/setup-snapshots';
+import '@analogjs/vitest-angular/setup-serializers';
+import { setupTestBed } from '@analogjs/vitest-angular/setup-testbed';
+
+setupTestBed();

package/template/src/vite-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+declare module 'virtual:ngmd/page-meta' {
+  export interface PageMeta {
+    editUrl: string;
+    lastUpdated: string;
+  }
+  export const pageMeta: Record<string, PageMeta>;
+}

package/template/tsconfig.app.json

@@ -0,0 +1,14 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/app",
+    "types": []
+  },
+  "files": ["src/main.ts", "src/main.server.ts"],
+  "include": [
+    "src/**/*.d.ts",
+    "src/app/pages/**/*.page.ts",
+    "src/server/middleware/**/*.ts"
+  ]
+}

package/template/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./dist/out-tsc",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "sourceMap": true,
+    "declaration": false,
+    "downlevelIteration": true,
+    "experimentalDecorators": true,
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022", "dom"],
+    "useDefineForClassFields": false,
+    "skipLibCheck": true
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "references": [
+    { "path": "tsconfig.spec.json" }
+  ]
+}

package/template/tsconfig.spec.json

@@ -0,0 +1,11 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "target": "es2022",
+    "types": ["node", "vitest/globals"]
+  },
+  "files": ["src/test-setup.ts"],
+  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,78 @@
+/// <reference types="vitest" />
+
+import { defineConfig, type Plugin } from 'vite';
+import analog from '@analogjs/platform';
+import tailwindcss from '@tailwindcss/vite';
+import { readFileSync } from 'node:fs';
+import { getBuildExtensions } from './src/marked-extensions';
+import { pageMetaPlugin } from './page-meta.plugin';
+import { internalLinkGuard } from './link-guard.plugin';
+import { sitemapPlugin } from './sitemap.plugin';
+import config from './src/ngmd.config';
+
+/**
+ * Build-time guard: errors when a markdown file in `src/content/` contains
+ * a raw HTML `<a href="http(s)://...">` without `target="_blank"`. Raw HTML
+ * anchors bypass the marked link renderer (which would add target=_blank
+ * automatically), so this catches external links that would silently open
+ * in the same tab.
+ *
+ * Lifted from the adev docs pipeline pattern.
+ */
+function externalLinkGuard(): Plugin {
+  return {
+    name: 'ngmd-external-link-guard',
+    enforce: 'pre',
+    transform(_code, id) {
+      if (!id.endsWith('.md')) return null;
+      const content = readFileSync(id.split('?')[0], 'utf8');
+      const anchorRe = /<a\b[^>]*href=["']https?:\/\/[^"']+["'][^>]*>/g;
+      const matches = content.match(anchorRe) ?? [];
+      for (const m of matches) {
+        if (!/target=["']_blank["']/.test(m)) {
+          this.error(
+            `[ngmd] External anchor in ${id} is missing target="_blank":\n  ${m}\n` +
+              `Add target="_blank" rel="noopener noreferrer" so external links open in a new tab.`,
+          );
+        }
+      }
+      return null;
+    },
+  };
+}
+
+export default defineConfig(async () => ({
+  build: {
+    target: ['es2020'],
+  },
+  resolve: {
+    mainFields: ['module'],
+  },
+  plugins: [
+    externalLinkGuard(),
+    internalLinkGuard(),
+    pageMetaPlugin({ repoUrl: config.site.githubUrl, branch: 'main' }),
+    sitemapPlugin({ siteUrl: config.site.url }),
+    analog({
+      content: {
+        highlighter: 'shiki',
+        markedOptions: {
+          extensions: await getBuildExtensions(),
+        },
+        shikiOptions: {
+          highlighter: {
+            additionalLangs: ['bash', 'md', 'json'],
+          },
+        },
+      },
+    }),
+    tailwindcss(),
+  ],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['src/test-setup.ts'],
+    include: ['**/*.spec.ts'],
+    reporters: ['default'],
+  },
+}));