handoff-app 1.1.2 → 1.1.3-1

package/Changelog.md

@@ -6,6 +6,87 @@ 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.
+
+### Bug Fixes
+
+- **New components not detected in dev mode** — `npm run start` now watches
+  the parent component directories (from `config.entries.components`) for
+  newly created components. Previously, only components known at startup had
+  their files watched; adding a new component directory required restarting
+  the dev server. A new `watchComponentDirectories` watcher detects when a
+  config file (`.json` / `.js` / `.cjs`) appears in a new subdirectory,
+  reloads the runtime config, restarts the component and configuration
+  watchers, and processes the new component automatically.
+
+- **Heading anchor IDs truncated** — The markdown heading anchor generator
+  was only reading the first child node (`children[0]`) instead of the full
+  heading text, producing single-character or partial IDs (e.g. `id="u"`
+  instead of `id="using-icons-in-templates"`). A new `extractText` helper
+  recursively walks all children to build the complete anchor slug.
+
+- **Fenced code blocks without a language unstyled** — Bare ```` ``` ````
+  blocks (no language identifier) now receive the same styled treatment as
+  language-tagged blocks: toolbar, copy button, and themed background.
+  Inline code is unaffected.
+
+- **Code blocks pushing page width** — Added `min-w-0` and `max-w-full` on
+  the code block wrapper and the grid content column to prevent wide code
+  from stretching the layout and pushing the TOC off-screen.
+
+- **Frontmatter menu duplicated by auto-scan** — When a markdown page
+  defines its sidebar menu via frontmatter `menu`, the automatic directory
+  scanner no longer appends duplicate entries. Auto-scanning now only runs
+  as a fallback when no frontmatter menu is present.
+
+- **`.prose` max-width too narrow** — Overrode Tailwind Typography's default
+  `max-width: 65ch` on `.prose` to `100%` so markdown content fills the
+  available container width.
+
+### 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.
+- Added `system/tokens/**` paths to `knownPaths` to prevent catch-all route
+  conflicts with dedicated token pages.
+
 ## \[1.1.2] - 2026-03-26
 
 This release improves integration with downstream platforms (for example HubSpot) by letting

package/dist/app-builder/build.js

@@ -175,10 +175,12 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         debounce: false,
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
+        componentDirectoriesWatcher: null,
     };
     (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
     (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
     (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
+    (0, watchers_1.watchComponentDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });

package/dist/app-builder/watchers.d.ts

@@ -6,6 +6,7 @@ export interface WatcherState {
     debounce: boolean;
     runtimeComponentsWatcher: chokidar.FSWatcher | null;
     runtimeConfigurationWatcher: chokidar.FSWatcher | null;
+    componentDirectoriesWatcher: chokidar.FSWatcher | null;
 }
 /**
  * Watches the working public directory for changes and updates the app.
@@ -34,7 +35,7 @@ export declare const mapEntryTypeToSegment: (type: keyof ComponentListObject["en
  *
  * @returns A Map of paths to watch and their entry types
  */
-export declare const getRuntimeComponentsPathsToWatch: (handoff: Handoff) => Map<string, "template" | "js" | "scss">;
+export declare const getRuntimeComponentsPathsToWatch: (handoff: Handoff) => Map<string, "js" | "scss" | "template">;
 /**
  * Watches runtime components for changes.
  */
@@ -43,3 +44,10 @@ export declare const watchRuntimeComponents: (handoff: Handoff, state: WatcherSt
  * Watches the runtime configuration for changes.
  */
 export declare const watchRuntimeConfiguration: (handoff: Handoff, state: WatcherState) => void;
+/**
+ * Watches the parent component directories from config.entries.components
+ * for new components being added. When a new config file (e.g. button.json)
+ * appears in a new subdirectory, reloads the runtime config and restarts
+ * the component/configuration watchers so the new component is picked up.
+ */
+export declare const watchComponentDirectories: (handoff: Handoff, state: WatcherState, chokidarConfig: chokidar.WatchOptions) => void;

package/dist/app-builder/watchers.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.getRuntimeComponentsPathsToWatch = exports.mapEntryTypeToSegment = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = void 0;
+exports.watchComponentDirectories = exports.watchRuntimeConfiguration = exports.watchRuntimeComponents = exports.getRuntimeComponentsPathsToWatch = exports.mapEntryTypeToSegment = exports.watchGlobalEntries = exports.watchPages = exports.watchAppSource = exports.watchPublicDirectory = void 0;
 const chokidar_1 = __importDefault(require("chokidar"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -277,13 +277,9 @@ const watchRuntimeConfiguration = (handoff, state) => {
                         state.debounce = true;
                         try {
                             file = path_1.default.dirname(file);
-                            // Reload the Handoff instance to pick up configuration changes
                             handoff.reload();
-                            // After reloading, persist the updated client configuration
                             yield (0, client_config_1.persistClientConfig)(handoff);
-                            // Restart the runtime components watcher to track potentially updated/added/removed components
                             (0, exports.watchRuntimeComponents)(handoff, state, (0, exports.getRuntimeComponentsPathsToWatch)(handoff));
-                            // Process components based on the updated configuration and file path
                             yield (0, builder_1.default)(handoff, path_1.default.basename(file));
                         }
                         catch (e) {
@@ -299,3 +295,61 @@ const watchRuntimeConfiguration = (handoff, state) => {
     }
 };
 exports.watchRuntimeConfiguration = watchRuntimeConfiguration;
+/**
+ * Watches the parent component directories from config.entries.components
+ * for new components being added. When a new config file (e.g. button.json)
+ * appears in a new subdirectory, reloads the runtime config and restarts
+ * the component/configuration watchers so the new component is picked up.
+ */
+const watchComponentDirectories = (handoff, state, chokidarConfig) => {
+    var _a, _b, _c, _d, _e;
+    if (state.componentDirectoriesWatcher) {
+        state.componentDirectoriesWatcher.close();
+    }
+    const componentPaths = (_b = (_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.components) !== null && _b !== void 0 ? _b : [];
+    if (componentPaths.length === 0)
+        return;
+    const dirsToWatch = [];
+    for (const componentPath of componentPaths) {
+        const resolved = path_1.default.resolve(handoff.workingPath, componentPath);
+        if (fs_extra_1.default.existsSync(resolved) && fs_extra_1.default.statSync(resolved).isDirectory()) {
+            dirsToWatch.push(resolved);
+        }
+    }
+    if (dirsToWatch.length === 0)
+        return;
+    const knownComponents = new Set(Object.keys((_e = (_d = (_c = handoff.runtimeConfig) === null || _c === void 0 ? void 0 : _c.entries) === null || _d === void 0 ? void 0 : _d.components) !== null && _e !== void 0 ? _e : {}));
+    state.componentDirectoriesWatcher = chokidar_1.default.watch(dirsToWatch, Object.assign(Object.assign({}, chokidarConfig), { depth: 1 }));
+    state.componentDirectoriesWatcher.on('add', (file) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const basename = path_1.default.basename(file);
+        const dirName = path_1.default.basename(path_1.default.dirname(file));
+        const isConfigFile = basename.endsWith('.json') || basename.endsWith('.js') || basename.endsWith('.cjs');
+        const isNewComponent = isConfigFile && basename.startsWith(dirName) && !knownComponents.has(dirName);
+        if (!isNewComponent)
+            return;
+        if (!state.debounce) {
+            state.debounce = true;
+            try {
+                logger_1.Logger.warn(`New component detected: ${dirName}. Reloading configuration...`);
+                handoff.reload();
+                knownComponents.add(dirName);
+                // Update known set with all current components
+                for (const id of Object.keys((_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {})) {
+                    knownComponents.add(id);
+                }
+                yield (0, client_config_1.persistClientConfig)(handoff);
+                (0, exports.watchRuntimeComponents)(handoff, state, (0, exports.getRuntimeComponentsPathsToWatch)(handoff));
+                (0, exports.watchRuntimeConfiguration)(handoff, state);
+                yield (0, builder_1.default)(handoff, dirName);
+            }
+            catch (e) {
+                logger_1.Logger.error('Error processing new component:', e);
+            }
+            finally {
+                state.debounce = false;
+            }
+        }
+    }));
+};
+exports.watchComponentDirectories = watchComponentDirectories;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.1.2",
+  "version": "1.1.3-1",
   "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;