Implement the following plan:

Footnotes and Sidenotes for MDX Content

Two components: Footnotes (inline ^[text] syntax, superscript numbers with hover tooltips) and Sidenotes (block <Sidenote> component, persistent margin content on wide screens).

Authoring syntax

Some paragraph text with a footnote^[This appears as a tooltip on hover.] and
the sentence continues with another^[Second footnote here.].

<Sidenote>
This aside appears in the right margin on wide screens, or as an inline
callout on narrower screens. Can contain **formatting** and [links](/somewhere).
</Sidenote>

The next paragraph continues normally.

• Footnotes: Pandoc-style inline ^[plain text] syntax, parsed by a custom remark plugin. Auto-numbered. For rich content (bold, links), use <Footnote> JSX directly as a fallback.
• Sidenotes: Block-level <Sidenote> MDX component placed between paragraphs. No numbering.

Remark plugin for inline footnotes

apps/web/lib/remark-inline-footnotes.ts (new file)

A remark plugin that transforms ^[content] in text nodes into <Footnote> JSX elements during the MDX compilation pipeline.

import { visit } from "unist-util-visit";

export function remarkInlineFootnotes() {
  return (tree: any) => {
    visit(tree, "text", (node: any, index: number | undefined, parent: any) => {
      if (!parent || index === undefined) return;

      const value: string = node.value;
      const nodes: any[] = [];
      let lastIndex = 0;
      let searchStart = 0;

      while (searchStart < value.length) {
        const start = value.indexOf("^[", searchStart);
        if (start === -1) break;

        // Find matching ] with bracket depth tracking
        let depth = 1;
        let pos = start + 2;
        while (pos < value.length && depth > 0) {
          if (value[pos] === "[") depth++;
          if (value[pos] === "]") depth--;
          pos++;
        }
        if (depth !== 0) { searchStart = start + 2; continue; }

        const content = value.slice(start + 2, pos - 1);

        // Text before the footnote
        if (start > lastIndex) {
          nodes.push({ type: "text", value: value.slice(lastIndex, start) });
        }

        // Footnote as MDX JSX inline element
        nodes.push({
          type: "mdxJsxTextElement",
          name: "Footnote",
          attributes: [],
          children: [{ type: "text", value: content }],
          data: { _mdxExplicitJsx: true },
        });

        lastIndex = pos;
        searchStart = pos;
      }

      if (nodes.length > 0) {
        if (lastIndex < value.length) {
          nodes.push({ type: "text", value: value.slice(lastIndex) });
        }
        parent.children.splice(index, 1, ...nodes);
      }
    });
  };
}

The plugin walks every text node, finds ^[...] patterns (with bracket-depth matching for nested brackets), and replaces them with mdxJsxTextElement nodes referencing the Footnote component. The MDX compiler resolves Footnote from the component map registered in mdx-components.tsx.

Wire into apps/web/next.config.ts

import { remarkInlineFootnotes } from "./lib/remark-inline-footnotes";

const withMDX = createMDX({
  options: {
    remarkPlugins: [
      "remark-gfm",
      "remark-frontmatter",
      "remark-mdx-frontmatter",
      remarkInlineFootnotes,   // <-- add
    ],
    rehypePlugins: ["rehype-slug", ["rehype-autolink-headings", { behavior: "wrap", content: [] }]],
  },
});

Dependency

Add unist-util-visit as an explicit dev dependency in apps/web/package.json (already available transitively via rehype-slug and @mdx-js/mdx).

Footnote component

Client component — needs hover/focus state and auto-numbering context.

Auto-numbering: FootnoteProvider

apps/web/components/mdx/footnote-provider.tsx (new, client component):

A context provider wraps prose content in both layout components. Provides an incrementing counter so each <Footnote> gets a sequential number. Counter resets to 0 at each render start — SSR and hydration produce the same sequence since React renders children in DOM order synchronously.

Footnote rendering

apps/web/components/mdx/footnote.tsx (new, client component):

• Reads its index from FootnoteProvider context via useState(() => getNextIndex())
• Renders a superscript number as a <button> with cursor-help
• Desktop: onMouseEnter/onMouseLeave show/hide tooltip
• Mobile/touch: onClick toggles tooltip
• Tooltip: absolutely positioned above the number, uses bg-popover/border-border theme tokens, z-50, w-64
• Accessibility: aria-describedby links button to tooltip, role="tooltip" on the popup

Sidenote component

Server component — no interactivity. CSS handles responsive behavior.

apps/web/components/mdx/sidenote.tsx (new):

Renders <aside className="sidenote ..."> with:

• Narrow screens / meeting pages: styled as inline callout (accent left border, muted text, smaller font)
• Wide screens on blog: CSS floats it into the right margin (see below)

CSS for margin positioning

Add to apps/web/styles/globals.css:

/* Sidenote margin positioning — active when parent layout opts in */
@media (min-width: 1280px) {
  [data-sidenote-margin] .sidenote {
    float: right;
    clear: right;
    width: 14rem;
    margin-right: -16rem;
    margin-left: 1.5rem;
    margin-top: 0.25rem;
    margin-bottom: 0.5rem;
  }
}

• float: right + margin-right: -16rem pulls the aside out of the 70ch column into the right gutter
• clear: right prevents stacked sidenotes from overlapping
• Sidenote scrolls naturally with page content (not fixed)

Layout opt-in

• prose.tsx (blog): add data-sidenote-margin attribute → sidenotes float to right margin at XL+
• prose-with-toc.tsx (meetings): no change → sidenotes stay inline (right margin is occupied by TOC)

Registration and layout wiring

apps/web/mdx-components.tsx

Register both Footnote and Sidenote. Even though ^[...] syntax generates Footnote references automatically, the component must be in the MDX component map for resolution. Authors can also use <Footnote> directly for rich-content footnotes.

apps/web/components/prose.tsx

• Add data-sidenote-margin attribute to the <article>
• Wrap children in <FootnoteProvider>

apps/web/components/prose-with-toc.tsx

• Wrap children in <FootnoteProvider> (no sidenote data attribute)

Responsive behavior summary

Files to create

1. apps/web/lib/remark-inline-footnotes.ts — remark plugin parsing ^[...]
2. apps/web/components/mdx/footnote-provider.tsx — client component, auto-numbering context
3. apps/web/components/mdx/footnote.tsx — client component, superscript + tooltip
4. apps/web/components/mdx/sidenote.tsx — server component, aside with sidenote class

Files to modify

5. apps/web/next.config.ts — add remarkInlineFootnotes to remark plugins
6. apps/web/mdx-components.tsx — register Footnote and Sidenote
7. apps/web/components/prose.tsx — wrap in FootnoteProvider, add data-sidenote-margin
8. apps/web/components/prose-with-toc.tsx — wrap in FootnoteProvider
9. apps/web/styles/globals.css — add sidenote margin CSS
10. apps/web/package.json — add unist-util-visit dev dependency

Implementation order

1. Install unist-util-visit
2. Create remark plugin (remark-inline-footnotes.ts)
3. Create footnote-provider.tsx
4. Create footnote.tsx
5. Create sidenote.tsx
6. Add sidenote CSS to globals.css
7. Register components in mdx-components.tsx
8. Wire FootnoteProvider + data attribute into prose.tsx
9. Wire FootnoteProvider into prose-with-toc.tsx
10. Add plugin to next.config.ts

Verification

bun install                     # Install new dependency
bun run tsc                     # Type check
bun run lint                    # Lint

Manual testing — add test content to a blog post:

This is a test paragraph with a footnote^[This is the footnote content.] in it.

<Sidenote>
This is a sidenote that should float to the right margin on wide screens.
</Sidenote>

Another paragraph with two footnotes^[First note.] and^[Second note.] here.

Verify:

1. Footnote superscript numbers appear (1, 2, 3)
2. Hovering a number shows the tooltip
3. Tapping on mobile toggles the tooltip
4. Sidenote appears in right margin at XL+ browser width
5. Resize below XL — sidenote collapses to inline callout with left border
6. On a meeting page, sidenotes always render inline
7. Dark mode renders correctly for both

If you need specific details from before exiting plan mode (like exact code snippets, error messages, or content you generated), read the full transcript at: ~/.claude/projects/-Users-challen-www-usingandunderstanding-ai/03fe31dd-b702-4137-8eea-d09fd8889e55.jsonl

We're having this problem again: Error: loader ~/www/usingandunderstanding.ai/node_modules/.bun/@next+mdx@16.1.6+321d56e5e4b893af/node_modules/@next/mdx/mdx-js-loader.js for match "{*,next-mdx-rule}" does not have serializable options. Ensure that options passed are plain JavaScript objects and values. Also, let's not have test:e2e open the browser unless a --review flag is passed.

Your task

First, run git status, git diff, and git log --oneline -10 to understand the current state.

Then add and commit all modified files with a descriptive message. Break the changes into multiple commits if appropriate. If there are untracked files, ask if they should be added or added to the appropriate .gitignore file. The user may also want to take over at this point, so provide an abort option as well. Always check changes for unnecessary debugging statements or logging that might have been accidentally included. Prompt the user if you find any, and offer to remove each one by one. Do not use interactive git staging (git add -p) as it does not work.