handoff-app 1.1.2-0 → 1.1.3-0

package/Changelog.md

@@ -6,6 +6,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.1.3] - 2026-03-27
+
+This release reworks the markdown page rendering system with four improvements:
+n-level deep routing, automatic table-of-contents generation, standardized code
+block styling, and GitHub Flavored Markdown table support.
+
+### Features
+
+- **N-level deep markdown routing** — Replaced the fixed two-level routing
+  (`[level1]` / `[level1]/[level2]`) with a single `[...slug]` catch-all route
+  that supports markdown pages at any directory depth. A new recursive
+  `buildCatchAllStaticPaths` function walks `config/docs` and `pages`
+  directories to collect `.md` files at any nesting level. The sidebar menu now
+  also recursively scans directories to surface deeply nested pages.
+
+- **Automatic table of contents** — The existing but unused `PageTOC` component
+  is now wired into the catch-all markdown page. It scans rendered headings
+  (h1–h6) via a `MutationObserver` and populates the right-hand "On This Page"
+  anchor nav automatically. Fixed a timing bug where headings were scanned
+  before the markdown content was in the DOM, and fixed anchor IDs that were
+  incorrectly prefixed with `#` (producing `##id` in URLs).
+
+- **Standardized code block styling** — Markdown fenced code blocks now render
+  with a toolbar header matching the site's `CodeHighlight` component: a
+  language icon, filename or language label, and a copy-to-clipboard button. A
+  new `remarkCodeMeta` remark plugin preserves the fence info string so metadata
+  like `` ```bash filename="deploy.sh" `` is parsed and displayed. The Prism
+  theme respects dark mode via `next-themes`, and registered languages now
+  include bash, css, scss, jsx, tsx, typescript, yaml, handlebars, and more.
+
+- **Markdown table support** — Added `remark-gfm` to all `ReactMarkdown`
+  instances across the codebase (17 files). Pipe tables, strikethrough,
+  autolinks, and task lists now render correctly. Tables are styled via Tailwind
+  Typography's `.prose table` defaults.
+
+### Changed
+
+- Deleted `src/app/pages/[level1]/index.tsx` and
+  `src/app/pages/[level1]/[level2]/index.tsx` (replaced by `[...slug]`).
+- Removed `buildL1StaticPaths`, `buildL2StaticPaths`, and the `SubPageType`
+  interface from `src/app/components/util/index.ts`.
+- `ComponentGuidelines` now uses `MarkdownComponents` and the remark plugins
+  for consistent rendering.
+
 ## \[1.1.2] - 2026-03-26
 
 This release improves integration with downstream platforms (for example HubSpot) by letting

package/dist/cli.js

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-    return 'Handoff App - 1.1.2';
+    return 'Handoff App - 1.1.3';
 };
 /**
  * Define a CLI error

package/dist/transformers/utils/handlebars.js

@@ -17,7 +17,7 @@ const registerHandlebarsHelpers = (data, injectFieldWrappers, extend) => {
     handlebars_1.default.registerHelper('field', function (field, options) {
         if (injectFieldWrappers) {
             if (!field) {
-                // This deebuging isn't helpful in the context of the component library
+                // This debugging isn't helpful in the context of the component library
                 // Logger.error(`Missing field declaration for ${data.id}`);
                 return options.fn(this);
             }
@@ -44,12 +44,19 @@ const registerHandlebarsHelpers = (data, injectFieldWrappers, extend) => {
     handlebars_1.default.registerHelper('eq', function (a, b) {
         return a === b;
     });
-    extend === null || extend === void 0 ? void 0 : extend({
-        handlebars: handlebars_1.default,
-        componentId: data.id,
-        properties: data.properties,
-        injectFieldWrappers,
-    });
+    if (extend) {
+        try {
+            extend({
+                handlebars: handlebars_1.default,
+                componentId: data.id,
+                properties: data.properties,
+                injectFieldWrappers,
+            });
+        }
+        catch (err) {
+            logger_1.Logger.error(`registerHandlebarsHelpers hook failed for ${data.id}`, err);
+        }
+    }
 };
 exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.1.2-0",
+  "version": "1.1.3-0",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -109,6 +109,7 @@
     "react-scroll": "^1.8.9",
     "react-syntax-highlighter": "^16.1.0",
     "rehype-raw": "^7.0.0",
+    "remark-gfm": "^4.0.1",
     "sass": "^1.85.0",
     "tailwind-merge": "^2.5.5",
     "tailwindcss": "^4.1.14",

package/src/app/components/ComponentGuidelines.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
+import remarkGfm from 'remark-gfm';
+import { MarkdownComponents, remarkCodeMeta } from './Markdown/MarkdownComponents';
 
 export interface ComponentGuidelinesProps {
   content: string;
@@ -10,7 +12,7 @@ export const ComponentGuidelines: React.FC<ComponentGuidelinesProps> = ({ conten
   return (
     <>
       <div className="prose">
-        <ReactMarkdown rehypePlugins={[rehypeRaw]}>{content}</ReactMarkdown>
+        <ReactMarkdown components={MarkdownComponents} remarkPlugins={[remarkGfm, remarkCodeMeta]} rehypePlugins={[rehypeRaw]}>{content}</ReactMarkdown>
       </div>
     </>
   );

package/src/app/components/Markdown/MarkdownComponents.tsx

@@ -1,23 +1,56 @@
+import { useTheme } from 'next-themes';
 import React, { ReactElement } from 'react';
+import bash from 'react-syntax-highlighter/dist/esm/languages/prism/bash';
+import css from 'react-syntax-highlighter/dist/esm/languages/prism/css';
+import handlebars from 'react-syntax-highlighter/dist/esm/languages/prism/handlebars';
 import js from 'react-syntax-highlighter/dist/esm/languages/prism/javascript';
 import json from 'react-syntax-highlighter/dist/esm/languages/prism/json';
+import jsx from 'react-syntax-highlighter/dist/esm/languages/prism/jsx';
 import markdown from 'react-syntax-highlighter/dist/esm/languages/prism/markdown';
 import sass from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
-import tsx from 'react-syntax-highlighter/dist/esm/languages/prism/typescript';
+import tsx from 'react-syntax-highlighter/dist/esm/languages/prism/tsx';
+import typescript from 'react-syntax-highlighter/dist/esm/languages/prism/typescript';
 import html from 'react-syntax-highlighter/dist/esm/languages/prism/xml-doc';
+import yaml from 'react-syntax-highlighter/dist/esm/languages/prism/yaml';
 import SyntaxHighlighter from 'react-syntax-highlighter/dist/esm/prism-light';
-import { oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import { oneDark, oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import CopyCode from '../CopyCode';
+
+import {
+  Braces,
+  Code,
+  FileCode2,
+  FileText,
+  FileType,
+  Terminal,
+} from 'lucide-react';
+
+SyntaxHighlighter.registerLanguage('bash', bash);
+SyntaxHighlighter.registerLanguage('sh', bash);
+SyntaxHighlighter.registerLanguage('shell', bash);
+SyntaxHighlighter.registerLanguage('zsh', bash);
+SyntaxHighlighter.registerLanguage('css', css);
+SyntaxHighlighter.registerLanguage('handlebars', handlebars);
+SyntaxHighlighter.registerLanguage('hbs', handlebars);
+SyntaxHighlighter.registerLanguage('javascript', js);
 SyntaxHighlighter.registerLanguage('js', js);
 SyntaxHighlighter.registerLanguage('json', json);
+SyntaxHighlighter.registerLanguage('jsx', jsx);
 SyntaxHighlighter.registerLanguage('markdown', markdown);
+SyntaxHighlighter.registerLanguage('md', markdown);
 SyntaxHighlighter.registerLanguage('sass', sass);
+SyntaxHighlighter.registerLanguage('scss', sass);
 SyntaxHighlighter.registerLanguage('tsx', tsx);
+SyntaxHighlighter.registerLanguage('typescript', typescript);
+SyntaxHighlighter.registerLanguage('ts', typescript);
 SyntaxHighlighter.registerLanguage('html', html);
-/**
- * Custom renderer type that we support
- */
+SyntaxHighlighter.registerLanguage('xml', html);
+SyntaxHighlighter.registerLanguage('yaml', yaml);
+SyntaxHighlighter.registerLanguage('yml', yaml);
+
 export type CustomRenderers = {
   code: (props: any) => ReactElement;
+  pre: (props: any) => ReactElement;
   h1: (props: any) => ReactElement;
   h2: (props: any) => ReactElement;
   h3: (props: any) => ReactElement;
@@ -27,32 +60,27 @@ export type CustomRenderers = {
   paragraph: (props: { children: React.ReactNode }) => ReactElement;
 };
 
-/**
- * Build the headers in markdown
- * @param param0
- * @returns
- */
-const Headings = (element) => {
+function extractText(node: any): string {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(extractText).join('');
+  if (node?.props?.children) return extractText(node.props.children);
+  return '';
+}
+
+const Headings = (element: any) => {
   const { children, node } = element;
-  // Access actual (string) value of heading
   if (children[0]) {
-    const heading = children[0];
     const type = node.tagName || 'h6';
 
-    // If we have a heading, make it lower case
-    let anchor = heading.toString().toLowerCase();
-
-    // Clean anchor (replace special characters whitespaces).
-    // Alternatively, use encodeURIComponent() if you don't care about
-    // pretty anchor links
+    let anchor = extractText(children).toLowerCase();
     anchor = anchor.replace(/[^a-zA-Z0-9 ]/g, '');
     anchor = anchor.replace(/ /g, '-');
 
-    // Utility
     const container = (children: React.ReactNode): React.ReactNode => (
       <>
         {children}
-        <a id={anchor} href={`#${anchor}`} className="doc-link" onClick={(e) => console.log(e)}></a>
+        <a id={anchor} href={`#${anchor}`} className="doc-link"></a>
       </>
     );
 
@@ -69,22 +97,147 @@ const Headings = (element) => {
         return <h5 className="text-sm font-bold">{container(children)}</h5>;
       case 'h6':
         return <h6 className="text-xs font-bold">{container(children)}</h6>;
-
       default:
-        return (
-          <h6 className="text-xs font-bold">
-            {JSON.stringify(type)}: {container(children)}
-          </h6>
-        );
+        return <h6 className="text-xs font-bold">{container(children)}</h6>;
     }
   } else {
     return <h1>children</h1>;
   }
 };
 
+const LANGUAGE_ICONS: Record<string, React.FC<{ className?: string }>> = {
+  bash: Terminal,
+  sh: Terminal,
+  shell: Terminal,
+  zsh: Terminal,
+  js: FileCode2,
+  javascript: FileCode2,
+  ts: FileCode2,
+  typescript: FileCode2,
+  jsx: FileCode2,
+  tsx: FileCode2,
+  css: FileType,
+  scss: FileType,
+  sass: FileType,
+  html: FileCode2,
+  xml: FileCode2,
+  json: Braces,
+  yaml: FileText,
+  yml: FileText,
+  markdown: FileText,
+  md: FileText,
+  handlebars: Code,
+  hbs: Code,
+};
+
+const LANGUAGE_LABELS: Record<string, string> = {
+  bash: 'Bash',
+  sh: 'Shell',
+  shell: 'Shell',
+  zsh: 'Zsh',
+  js: 'JavaScript',
+  javascript: 'JavaScript',
+  ts: 'TypeScript',
+  typescript: 'TypeScript',
+  jsx: 'JSX',
+  tsx: 'TSX',
+  css: 'CSS',
+  scss: 'SCSS',
+  sass: 'SASS',
+  html: 'HTML',
+  xml: 'XML',
+  json: 'JSON',
+  yaml: 'YAML',
+  yml: 'YAML',
+  markdown: 'Markdown',
+  md: 'Markdown',
+  handlebars: 'Handlebars',
+  hbs: 'Handlebars',
+  text: 'Code',
+};
+
+function parseMeta(meta: string | undefined): Record<string, string> {
+  if (!meta) return {};
+  const result: Record<string, string> = {};
+  const regex = /(\w+)="([^"]+)"/g;
+  let match;
+  while ((match = regex.exec(meta)) !== null) {
+    result[match[1]] = match[2];
+  }
+  return result;
+}
+
+function MarkdownCodeBlock(props: any) {
+  const { className, children, node, 'data-meta': dataMeta, ...rest } = props;
+  const { resolvedTheme } = useTheme();
+  const isDark = resolvedTheme === 'dark';
+
+  const langMatch = /language-(\w+)/.exec(className || '');
+  const isBlock = String(children).includes('\n');
+
+  if (!langMatch && !isBlock) {
+    return <code className={className} {...rest}>{children}</code>;
+  }
+
+  const lang = langMatch ? langMatch[1] : 'text';
+  const meta = parseMeta(dataMeta);
+  const filename = meta.filename;
+  const codeString = String(children).replace(/\n$/, '');
+  const IconComponent = LANGUAGE_ICONS[lang] || Code;
+  const langLabel = LANGUAGE_LABELS[lang] || lang;
+
+  const theme = isDark ? { ...oneDark } : { ...oneLight };
+  theme['pre[class*="language-"]'] = {
+    ...theme['pre[class*="language-"]'],
+    overflow: 'auto',
+    margin: '0',
+    borderRadius: '0 0 0.5rem 0.5rem',
+    background: isDark ? '#1e1e1e' : '#fafafa',
+  };
+
+  return (
+    <div className="not-prose my-4 min-w-0 max-w-full overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+      <div className="flex items-center justify-between bg-gray-50 px-4 py-2 dark:bg-gray-800">
+        <div className="flex items-center gap-2 text-sm text-gray-600 dark:text-gray-400">
+          <IconComponent className="h-4 w-4" />
+          <span>{filename || langLabel}</span>
+        </div>
+        <CopyCode code={codeString} />
+      </div>
+      <SyntaxHighlighter
+        style={theme}
+        language={lang}
+        PreTag="div"
+        showLineNumbers={lang !== 'text'}
+        wrapLines={true}
+        useInlineStyles={true}
+      >
+        {codeString}
+      </SyntaxHighlighter>
+    </div>
+  );
+}
+
 /**
- * Build custom renderers for markdown
+ * Remark plugin that preserves the code fence meta string
+ * (the text after the language identifier) as a hast data attribute.
  */
+export function remarkCodeMeta() {
+  return (tree: any) => {
+    const walk = (node: any) => {
+      if (node.type === 'code' && node.meta) {
+        node.data = node.data || {};
+        node.data.hProperties = node.data.hProperties || {};
+        node.data.hProperties['data-meta'] = node.meta;
+      }
+      if (node.children) {
+        node.children.forEach(walk);
+      }
+    };
+    walk(tree);
+  };
+}
+
 export const MarkdownComponents: CustomRenderers = {
   h1: Headings,
   h2: Headings,
@@ -93,28 +246,8 @@ export const MarkdownComponents: CustomRenderers = {
   h5: Headings,
   h6: Headings,
   paragraph: ({ children }) => <p>{children}</p>,
-  code(props) {
-    const { className } = props;
-    const match = /language-(\w+)/.exec(className || '');
-    // This was designed to flatten out children arrays, but I think its not needed
-    // if (props.children[0]) {
-    //   props.children[0] = props.children[0].toString().trim();
-    // }
-    return match ? (
-      <SyntaxHighlighter
-        // @ts-ignore
-        style={oneLight}
-        language={match[1]}
-        PreTag="div"
-        showLineNumbers={true}
-        wrapLines={true}
-        useInlineStyles={true}
-        {...props}
-      ></SyntaxHighlighter>
-    ) : (
-      <code {...props} />
-    );
-  },
+  pre: ({ children }) => <>{children}</>,
+  code: MarkdownCodeBlock,
 };
 
 export default Headings;

package/src/app/components/Navigation/AnchorNav.tsx

@@ -18,45 +18,45 @@ interface TOCProps {
 export function PageTOC({ body, title }: TOCProps) {
   const [headers, setHeaders] = React.useState<{ id: string; title: string | null; level: number }[]>([]);
   const router = useRouter();
-  const getHeaders = () => {
-    if (body.current) {
-      const headers = Array.from(body.current.querySelectorAll('h1, h2, h3, h4, h5, h6')).map((node) => {
-        const id = anchorSlugify(node?.textContent?.toString() ?? '');
-        return {
-          id,
-          title: node.textContent,
-          level: parseInt(node.tagName[1]),
-        };
-      });
-      setHeaders(headers);
-    }
-  };
-  const headersCallback = React.useCallback(getHeaders, [body]);
+
+  const scanHeaders = React.useCallback(() => {
+    if (!body.current) return;
+    const found = Array.from(body.current.querySelectorAll('h1, h2, h3, h4, h5, h6')).map((node) => ({
+      id: anchorSlugify(node?.textContent?.toString() ?? ''),
+      title: node.textContent,
+      level: parseInt(node.tagName[1]),
+    }));
+    setHeaders(found);
+  }, [body]);
 
   useEffect(() => {
-    router.events.on('routeChangeComplete', () => {
-      headersCallback();
-    });
-    return () => {
-      router.events.off('routeChangeComplete', () => {
-        headersCallback();
-      });
-    };
-  }, [router, headersCallback]);
+    // Scan after paint to catch SSR-hydrated content
+    requestAnimationFrame(scanHeaders);
+
+    // Watch for dynamically inserted headings (client-rendered markdown)
+    const el = body.current;
+    if (!el) return;
+    const observer = new MutationObserver(scanHeaders);
+    observer.observe(el, { childList: true, subtree: true });
+    return () => observer.disconnect();
+  }, [body, scanHeaders]);
+
   useEffect(() => {
-    headersCallback();
-  }, [body, headersCallback]);
+    const handler = () => requestAnimationFrame(scanHeaders);
+    router.events.on('routeChangeComplete', handler);
+    return () => router.events.off('routeChangeComplete', handler);
+  }, [router, scanHeaders]);
   return (
     <AnchorNav
       title={title}
       groups={headers.reduce((acc, header) => {
         if (header.level === 1) {
-          acc.push({ [`#${header.id}`]: header.title ?? '' });
+          acc.push({ [header.id]: header.title ?? '' });
         } else {
           if (acc.length === 0) {
-            acc.push({ [`#${header.id}`]: header.title ?? '' });
+            acc.push({ [header.id]: header.title ?? '' });
           } else {
-            acc[acc.length - 1][`#${header.id}`] = header.title ?? '';
+            acc[acc.length - 1][header.id] = header.title ?? '';
           }
         }
         return acc;