create-ngmd 0.0.1 → 0.0.2

package/README.md

@@ -1,7 +1,11 @@
 # create-ngmd
 
+[![npm version](https://img.shields.io/npm/v/create-ngmd.svg)](https://www.npmjs.com/package/create-ngmd)
+
 Scaffold a new [NgMd](https://github.com/erkamyaman/ngmd) docs project.
 
+Live demo: [ngmd.netlify.app](https://ngmd.netlify.app)
+
 ```bash
 pnpm create ngmd@latest my-docs
 # or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ngmd",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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/package.json

@@ -49,6 +49,7 @@
     "marked-highlight": "^2.2.1",
     "marked-mangle": "^1.1.10",
     "marked-shiki": "^1.2.1",
+    "motion": "^12.40.0",
     "postcss": "^8.5.3",
     "prismjs": "^1.29.0",
     "rxjs": "~7.8.0",

package/template/src/app/app.ts

@@ -14,6 +14,7 @@ import {
 } from 'lucide-angular';
 import { ThemeService } from './theme';
 import { LayoutMode } from './layout-mode.service';
+import siteConfig from '../ngmd.config';
 import { CommandPalette } from './components/command-palette';
 import { Sidebar } from './components/sidebar';
 import { Breadcrumb } from './components/breadcrumb';
@@ -114,7 +115,7 @@ import { MediaEnhancer } from './components/media-enhancer';
           </button>
           <span class="h-4 w-px bg-zinc-300/60 dark:bg-zinc-700/60"></span>
           <a
-            href="https://github.com"
+            [href]="githubUrl"
             target="_blank"
             rel="noopener noreferrer"
             class="rounded p-1.5 hover:bg-zinc-100 dark:hover:bg-zinc-900"
@@ -224,6 +225,8 @@ export class App implements OnInit {
   readonly moonIcon = Moon;
   readonly autoIcon = SunMoon;
 
+  readonly githubUrl = siteConfig.site.githubUrl;
+
   readonly drawerOpen = signal(false);
 
   private readonly url = toSignal(

package/template/src/app/components/page-footer.ts

@@ -7,7 +7,7 @@ import { pageMeta } from 'virtual:ngmd/page-meta';
 import { navItems } from '../../ngmd.config';
 
 /**
- * Bottom-of-page chrome shown under every docs route: previous/next sibling
+ * Bottom-of-page frame shown under every docs route: previous/next sibling
  * pages derived from `ngmd.config.ts`, an "Edit on GitHub" link, and the
  * page's last-updated date (commit cs from `git log`, baked at build time
  * via the page-meta vite plugin).

package/template/src/app/components/toc.ts

@@ -70,6 +70,12 @@ export class Toc implements AfterViewInit {
     const el = document.getElementById(id);
     if (el) {
       el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      // Force-activate the clicked id. The IntersectionObserver uses a
+      // `rootMargin: '0px 0px -70% 0px'` so only the top 30% of viewport
+      // counts as "in view"; the LAST heading can't reach that region if
+      // there isn't enough content below it, leaving scroll-spy stuck on
+      // an earlier heading. Setting active directly here bypasses that.
+      this.active.set(id);
       // index.html has <base href="/">, so a relative `#frag` resolves to
       // `/#frag` and strips the path. Pass the full path explicitly.
       history.replaceState(
@@ -82,9 +88,13 @@ export class Toc implements AfterViewInit {
 
   private scanWithRetry(attempt = 0): void {
     if (typeof document === 'undefined' || attempt > 20) return;
+    // Prefer the markdown wrappers for content-driven pages; fall back to
+    // `main article` for TS-driven pages (components.page.ts, etc.) that
+    // render Angular templates directly without analog-markdown.
     const content =
       document.querySelector('main analog-markdown') ??
-      document.querySelector('main analog-markdown-route');
+      document.querySelector('main analog-markdown-route') ??
+      document.querySelector('main article');
     if (!content || content.querySelectorAll('h2, h3').length === 0) {
       setTimeout(() => this.scanWithRetry(attempt + 1), 50);
       return;
@@ -127,5 +137,23 @@ export class Toc implements AfterViewInit {
       { rootMargin: '0px 0px -70% 0px', threshold: 0 },
     );
     nodes.forEach((node) => this.observer!.observe(node));
+
+    // Bottom-of-page guard: when the user scrolls within ~100px of the
+    // bottom of the document, force-activate the last heading. The
+    // IntersectionObserver alone can't reach this state because the last
+    // heading never enters the top 30% of the viewport if there's not
+    // enough content below it.
+    const last = nodes[nodes.length - 1];
+    const onScroll = () => {
+      const scrolled = window.innerHeight + window.scrollY;
+      const fullHeight = document.documentElement.scrollHeight;
+      if (scrolled >= fullHeight - 100) {
+        this.active.set(last.id);
+      }
+    };
+    window.addEventListener('scroll', onScroll, { passive: true });
+    this.destroyRef.onDestroy(() =>
+      window.removeEventListener('scroll', onScroll),
+    );
   }
 }

package/template/src/app/layout-mode.service.ts

@@ -1,8 +1,8 @@
 import { Injectable, signal } from '@angular/core';
 
 /**
- * Pages that want to render without the docs chrome (sidebar, breadcrumb, TOC)
- * can flip this signal in their constructor. The app shell reads it.
+ * Pages that want to render without the docs site frame (sidebar, breadcrumb,
+ * TOC) can flip this signal in their constructor. The app shell reads it.
  */
 @Injectable({ providedIn: 'root' })
 export class LayoutMode {

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

@@ -21,7 +21,7 @@ import { NgmdTab, NgmdTabs } from './tabs';
 import { NgmdVideo } from './video';
 
 /**
- * Spread into a page's `imports` to get every chrome component in one go:
+ * Spread into a page's `imports` to get every authoring component in one go:
  *   `imports: [...NgmdUi]`. For lighter pages, import only what you use.
  *
  * Not declared `as const`: Angular's standalone-component compiler needs

package/template/src/content/welcome.md

@@ -16,4 +16,4 @@ Edit the `nav` array in `src/ngmd.config.ts`. Sidebar, command palette, breadcru
 
 ## 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.
+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.

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

@@ -22,8 +22,11 @@ interface NgmdKeywordToken extends Tokens.Generic {
   url: string;
 }
 
-const KEYWORD_RE = /^\*([A-Z][a-zA-Z0-9]+)\b/;
-const HINT_RE = /\*[A-Z]/;
+// `(?!\*)` after the leading `*` prevents matching the second `*` of a
+// `**bold**` pair. `(?!\*)` after the keyword prevents matching the inside
+// of `**Keyword**` (which would leave one stray `*` and one stray `**`).
+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 {

package/template/src/styles.css

@@ -8,6 +8,50 @@
   animation-duration: 150ms;
   animation-timing-function: ease;
 }
+
+/* Hero title animation. The gradient span slowly shifts horizontally so the
+ * fuchsia core appears to pulse through the text. Whole h1 fades up on
+ * first paint. Honours prefers-reduced-motion. */
+@keyframes ngmd-hero-fade-in {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes ngmd-hero-gradient-flow {
+  from { background-position: 200% 50%; }
+  to { background-position: -100% 50%; }
+}
+
+.ngmd-hero-fade {
+  animation: ngmd-hero-fade-in 600ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+/* Hide hero words and the gradient line at first paint so SSR HTML doesn't
+ * flash before motion takes over. Motion sets opacity:1 + translateY(0)
+ * via inline styles, which override these defaults. */
+.ngmd-hero-anim {
+  opacity: 0;
+  transform: translateY(0.5em);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ngmd-hero-anim {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.ngmd-hero-gradient {
+  background-size: 300% auto;
+  animation: ngmd-hero-gradient-flow 5s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ngmd-hero-fade,
+  .ngmd-hero-gradient {
+    animation: none;
+  }
+}
 @plugin '@tailwindcss/typography';
 
 @variant dark (&:where(.dark, .dark *));