UI refresh

Co-authored-by: Copilot <copilot@github.com>

Author: dwijbavisi

site/modules/md/components/BlockNodes.tsx

@@ -7,21 +7,64 @@ import type {
     ListNode,
     MathBlockNode,
     CodeBlockNode,
+    InlineNode,
 } from "../types";
-import { RenderInline } from "./InlineNodes";
+import { RenderInline, renderInlineNode } from "./InlineNodes";
+import { slugify, inlineToText } from "../utils";
+
+const Marker = ({ children }: { children: React.ReactNode }) => (
+    <span className="md-marker">{children}</span>
+);
+
+// Split inline nodes on <br> boundaries and render each segment as a > prefixed line.
+function renderBlockquoteLines(nodes: InlineNode[]): React.ReactNode {
+    const segments: InlineNode[][] = [];
+    let current: InlineNode[] = [];
+    for (const node of nodes) {
+        if (node.type === "br") {
+            segments.push(current);
+            current = [];
+        } else {
+            current.push(node);
+        }
+    }
+    segments.push(current);
+    return segments.map((seg, i) => (
+        <span key={i} className="bq-line">
+            <Marker>{">"}&#32;</Marker>
+            {seg.map((n, j) => renderInlineNode(n, j))}
+        </span>
+    ));
+}
+
+function renderBlockquoteChild(node: BlockNode, key: number): React.ReactNode {
+    if (node.type === "paragraph") {
+        return <p key={key}>{renderBlockquoteLines((node as ParagraphNode).children)}</p>;
+    }
+    // Non-paragraph blocks (headings, nested blockquotes, etc.) get a single > prefix
+    return (
+        <React.Fragment key={key}>
+            <Marker>{">"}&#32;</Marker>
+            {renderBlockNode(node, key)}
+        </React.Fragment>
+    );
+}
 
 export function renderBlockNode(node: BlockNode, key: string | number): React.ReactNode {
     switch (node.type) {
         case "heading": {
             const n = node as HeadingNode;
+            const marker = "#".repeat(n.level) + " ";
             const inner = <RenderInline nodes={n.children} />;
+            const id = slugify(inlineToText(n.children));
+            const anchor = <a href={`#${id}`} className="heading-anchor" aria-label="Link to section">§</a>;
             switch (n.level) {
-                case 1: return <h1 key={key}>{inner}</h1>;
-                case 2: return <h2 key={key}>{inner}</h2>;
-                case 3: return <h3 key={key}>{inner}</h3>;
-                case 4: return <h4 key={key}>{inner}</h4>;
-                case 5: return <h5 key={key}>{inner}</h5>;
-                case 6: return <h6 key={key}>{inner}</h6>;
+                case 1: return <h1 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h1>;
+                case 2: return <h2 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h2>;
+                case 3: return <h3 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h3>;
+                case 4: return <h4 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h4>;
+                case 5: return <h5 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h5>;
+                case 6: return <h6 key={key} id={id}><Marker>{marker}</Marker>{inner}{anchor}</h6>;
             }
             break;
         }
@@ -36,14 +79,15 @@ export function renderBlockNode(node: BlockNode, key: string | number): React.Re
         case "blockquote":
             return (
                 <blockquote key={key}>
-                    {(node as BlockquoteNode).children.map((c, i) => renderBlockNode(c, i))}
+                    {(node as BlockquoteNode).children.map((c, i) => renderBlockquoteChild(c, i))}
                 </blockquote>
             );
 
         case "list": {
             const n = node as ListNode;
             const items = n.items.map((item, i) => (
                 <li key={i}>
+                    <span className="md-marker">{n.ordered ? `${i + 1}. ` : "- "}</span>
                     <RenderInline nodes={item.children} />
                 </li>
             ));

site/modules/md/components/InlineNodes.tsx

@@ -20,28 +20,40 @@ export function renderInlineNode(node: InlineNode, key: string | number): React.
         case "bold":
             return (
                 <strong key={key}>
+                    <span className="md-marker">**</span>
                     {(node as BoldNode).children.map((c, i) => renderInlineNode(c, i))}
+                    <span className="md-marker">**</span>
                 </strong>
             );
 
         case "italic":
             return (
                 <em key={key}>
+                    <span className="md-marker">*</span>
                     {(node as ItalicNode).children.map((c, i) => renderInlineNode(c, i))}
+                    <span className="md-marker">*</span>
                 </em>
             );
 
         case "link": {
             const n = node as LinkNode;
             return (
                 <a key={key} href={n.href}>
+                    <span className="md-marker">[</span>
                     {n.children.map((c, i) => renderInlineNode(c, i))}
+                    <span className="md-marker">]</span>
                 </a>
             );
         }
 
         case "inline-code":
-            return <code key={key}>{(node as InlineCodeNode).value}</code>;
+            return (
+                <code key={key}>
+                    <span className="md-marker">`</span>
+                    {(node as InlineCodeNode).value}
+                    <span className="md-marker">`</span>
+                </code>
+            );
 
         case "math-inline":
             return (

site/modules/md/parser.ts

@@ -308,6 +308,15 @@ function tokenizeBlocks(lines: string[]): RawBlock[] {
                     // Continuation line for the last item
                     rawItems[rawItems.length - 1].push(l.trim());
                     i++;
+                } else if (l.trim() === "") {
+                    // Blank line — look ahead: if next non-blank is another list item, skip it
+                    let j = i + 1;
+                    while (j < lines.length && lines[j].trim() === "") j++;
+                    if (j < lines.length && /^- /.test(lines[j])) {
+                        i = j; // skip blank(s), continue to next item
+                    } else {
+                        break;
+                    }
                 } else {
                     break;
                 }
@@ -329,6 +338,15 @@ function tokenizeBlocks(lines: string[]): RawBlock[] {
                 } else if (rawItems.length > 0 && l.trim() !== "" && !/^(- |\d+\. |#{1,6} |> |```|-{3,}|\$\$)/.test(l)) {
                     rawItems[rawItems.length - 1].push(l.trim());
                     i++;
+                } else if (l.trim() === "") {
+                    // Blank line — look ahead: if next non-blank is another ordered item, skip it
+                    let j = i + 1;
+                    while (j < lines.length && lines[j].trim() === "") j++;
+                    if (j < lines.length && /^\d+\. /.test(lines[j])) {
+                        i = j; // skip blank(s), continue to next item
+                    } else {
+                        break;
+                    }
                 } else {
                     break;
                 }

site/modules/md/utils.ts

@@ -0,0 +1,29 @@
+import type { InlineNode } from "./types";
+
+/**
+ * Convert a heading's plain text into a URL-safe id.
+ * e.g. "## The Fuel of Intent" → "the-fuel-of-intent"
+ */
+export function slugify(text: string): string {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+
+/**
+ * Recursively extract plain text from an array of InlineNodes.
+ */
+export function inlineToText(nodes: InlineNode[]): string {
+    return nodes
+        .map((n) => {
+            if (n.type === "text") return n.value;
+            if (n.type === "inline-code") return n.value;
+            if ("children" in n && Array.isArray((n as { children: InlineNode[] }).children)) {
+                return inlineToText((n as { children: InlineNode[] }).children);
+            }
+            return "";
+        })
+        .join("");
+}

site/scripts/build-static.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import esbuild from "esbuild";
 import React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { loadSiteData } from "../src/contentLoader";
@@ -53,15 +54,25 @@ async function run(): Promise<void> {
 
     log("Copying static assets...");
     await fs.copyFile(path.resolve(ROOT, "src/styles.css"), path.resolve(DIST, "styles.css"));
+
+    log("Building interaction.ts...");
+    await esbuild.build({
+        entryPoints: [path.resolve(ROOT, "src/interaction.ts")],
+        outfile: path.resolve(DIST, "interaction.js"),
+        bundle: true,
+        format: "iife",
+        platform: "browser",
+        minify: true,
+    });
+
     await copyIfExists(WWW_DIR, DIST);
 
     const latestArticles = siteData.articles.slice(0, 6);
-    const keyPages = siteData.pages.slice(0, 8);
 
     log("Rendering index...");
     await writeRoute(
         "/",
-        documentFromElement(React.createElement(IndexTemplate, { latestArticles, keyPages, introNodes }))
+        documentFromElement(React.createElement(IndexTemplate, { latestArticles, introNodes }))
     );
 
     log("Rendering article list...");

site/src/contentLoader.ts

@@ -4,6 +4,7 @@ import { parse } from "../modules/md/index";
 import type { BlockNode, BlockquoteNode, HeadingNode, InlineNode, LinkNode, ListNode, ParagraphNode, TextNode, BoldNode, ItalicNode, SupNode, SubNode } from "../modules/md/types";
 import { ContentItem, ContentKind, SiteData } from "./lib/types";
 import { relativeRouteHref } from "./lib/paths";
+import { extractToc } from "./lib/toc";
 
 const ARTICLE_ROOT = path.resolve(process.cwd(), "../content/articles");
 const PAGE_ROOT = path.resolve(process.cwd(), "../content/pages");
@@ -91,6 +92,18 @@ function toRoute(kind: ContentKind, slug: string): string {
     return `/${kind === "article" ? "articles" : "pages"}/${slug}/`;
 }
 
+function toCanonicalPath(slug: string): string {
+    const parts = slug.split("/");
+    const last = parts[parts.length - 1];
+    if (
+        last.toLowerCase() === "readme" ||
+        (parts.length >= 2 && last === parts[parts.length - 2])
+    ) {
+        return parts.slice(0, -1).join("/");
+    }
+    return slug;
+}
+
 // ─── Link Resolution ──────────────────────────────────────────────────────────
 
 /**
@@ -165,6 +178,7 @@ async function loadKind(kind: ContentKind, rootDir: string): Promise<ContentItem
         const fileText = await fs.readFile(filePath, "utf8");
         const { nodes, metadata } = parse(fileText);
         const slug = relativePath.replace(/\\/g, "/").replace(/\.md$/i, "");
+        const canonicalPath = toCanonicalPath(slug);
 
         const headings = nodes.filter((n) => n.type === "heading") as HeadingNode[];
         const title = inferTitle(headings, filePath);
@@ -175,13 +189,16 @@ async function loadKind(kind: ContentKind, rootDir: string): Promise<ContentItem
             kind,
             title,
             slug,
+            canonicalPath,
             route,
             sourcePath: relativePath.replace(/\\/g, "/"),
             summary: deriveSummary(nodes as ParagraphNode[]),
             date: inferDate(metadata.published, relativePath),
             author: metadata.author,
             conceivedDate: metadata.conceived,
             nodes: resolvedNodes,
+            toc: extractToc(resolvedNodes),
+            children: [],
         });
     }
 
@@ -192,6 +209,16 @@ async function loadKind(kind: ContentKind, rootDir: string): Promise<ContentItem
         return a.title.localeCompare(b.title);
     });
 
+    // Wire up direct children based on canonicalPath hierarchy
+    for (const item of items) {
+        item.children = items.filter((other) => {
+            if (other === item) return false;
+            if (!other.canonicalPath.startsWith(item.canonicalPath + "/")) return false;
+            const remainder = other.canonicalPath.slice(item.canonicalPath.length + 1);
+            return !remainder.includes("/");
+        });
+    }
+
     log(`Finished loading ${items.length} ${kind}(s).`);
     return items;
 }

site/src/interaction.ts

@@ -0,0 +1,50 @@
+/**
+ * Interaction controller — binds named behaviors to elements via `data-interaction`.
+ *
+ * Usage in HTML:
+ *   <details data-interaction="dismiss-outside">...</details>
+ *
+ * Usage in TypeScript (to add custom behaviors before DOMContentLoaded fires):
+ *   import { register } from "./interaction";
+ *   register("my-behavior", (el) => { ... });
+ */
+
+type Teardown = () => void;
+type BehaviorSetup = (el: Element) => Teardown | void;
+
+const _behaviors = new Map<string, BehaviorSetup>();
+
+/** Register a named behavior. The setup function is called for each element that declares it. */
+export function register(name: string, setup: BehaviorSetup): void {
+    _behaviors.set(name, setup);
+}
+
+/** Apply all registered behaviors to elements with `data-interaction` attributes. */
+export function init(): void {
+    document.querySelectorAll<HTMLElement>("[data-interaction]").forEach((el) => {
+        const names = (el.dataset.interaction ?? "").split(/\s+/).filter(Boolean);
+        for (const name of names) {
+            _behaviors.get(name)?.(el);
+        }
+    });
+}
+
+// ─── Built-in: dismiss-outside ────────────────────────────────────────────────
+// Closes a <details> element when the user clicks anywhere outside of it.
+
+register("dismiss-outside", (el) => {
+    if (!(el instanceof HTMLDetailsElement)) return;
+
+    const handler = (e: MouseEvent): void => {
+        if (el.open && !el.contains(e.target as Node)) {
+            el.open = false;
+        }
+    };
+
+    // Capture phase so we intercept before the click reaches children.
+    document.addEventListener("click", handler, true);
+});
+
+// ─── Auto-init ────────────────────────────────────────────────────────────────
+
+document.addEventListener("DOMContentLoaded", init);

site/src/lib/toc.ts

@@ -0,0 +1,26 @@
+import type { BlockNode, HeadingNode } from "../../modules/md/types";
+import { slugify, inlineToText } from "../../modules/md/utils";
+
+export interface TocItem {
+    id: string;
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+}
+
+export { slugify };
+
+/**
+ * Extract all headings from a parsed block list, up to level 3.
+ * Returns an empty array if there are fewer than 2 headings (not worth a ToC).
+ */
+export function extractToc(nodes: BlockNode[]): TocItem[] {
+    const items = nodes
+        .filter((n) => n.type === "heading" && (n as HeadingNode).level <= 3)
+        .map((n) => {
+            const h = n as HeadingNode;
+            const text = inlineToText(h.children);
+            return { id: slugify(text), level: h.level, text };
+        });
+
+    return items.length >= 2 ? items : [];
+}

site/src/lib/types.ts

@@ -1,18 +1,22 @@
 import type { BlockNode } from "../../modules/md/types";
+import type { TocItem } from "./toc";
 
 export type ContentKind = "article" | "page";
 
 export interface ContentItem {
     kind: ContentKind;
     title: string;
     slug: string;
+    canonicalPath: string;
     route: string;
     sourcePath: string;
     summary?: string;
     date?: string;
     author?: string;
     conceivedDate?: string;
     nodes: BlockNode[];
+    toc: TocItem[];
+    children: ContentItem[];
 }