From 02857edd18d69b3f08c201cf2e2278f3875c8f39 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:23:10 +0200
Subject: [PATCH 01/15] docs: design spec for configurable GitlabReadme TOC
 placement

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 ...6-29-gitlab-readme-toc-placement-design.md | 171 ++++++++++++++++++
 1 file changed, 171 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-29-gitlab-readme-toc-placement-design.md

diff --git a/docs/superpowers/specs/2026-06-29-gitlab-readme-toc-placement-design.md b/docs/superpowers/specs/2026-06-29-gitlab-readme-toc-placement-design.md
new file mode 100644
index 0000000..902d00d
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-29-gitlab-readme-toc-placement-design.md
@@ -0,0 +1,171 @@
+# Design: configurable TOC placement for `<GitlabReadme>`
+
+## Summary
+
+Add a `toc` attribute to `<GitlabReadme>` that controls where the README's table
+of contents renders:
+
+- **hide** the TOC,
+- show it **inline** (today's behavior), or
+- show it in the **right page sidebar**, like a normal Docusaurus page.
+
+All work happens at build time in the existing remark pipeline. The rendered
+README HTML and the pure React component are unchanged; the sidebar is populated
+by augmenting the page's native `toc` export that Docusaurus already generates.
+
+## Background
+
+Today an inline TOC appears only when the README contains the GitLab `[[_TOC_]]`
+marker. `renderMarkdown` → `rehypeGitlabToc` ([src/gitlab/toc.ts](../../../src/gitlab/toc.ts))
+replaces that marker with a `<nav class="gitlab-md-toc">` built from the README's
+`h2`–`h5` headings, and assigns heading ids. Crucially, `rehypeGitlabToc` is a
+**no-op unless the `[[_TOC_]]` placeholder is present**, so heading ids are only
+assigned in that case.
+
+The README is rendered to an HTML **string**, injected as a `data` prop, and
+rendered via `dangerouslySetInnerHTML` ([src/components/GitlabReadme.tsx](../../../src/components/GitlabReadme.tsx)).
+Docusaurus' native right-sidebar TOC is built by its own remark plugin scanning
+the **page's** mdast heading nodes — it never sees headings inside our opaque HTML
+string.
+
+Relevant Docusaurus 3.10 behavior (verified in
+`@docusaurus/mdx-loader/lib/remark/toc`):
+
+- The toc plugin **respects an explicit `export const toc`** and does not override
+  it; otherwise it generates `export const toc` from the page's heading nodes
+  (after its `headings` plugin assigns slug ids).
+- Our `remarkGitlab` is wired as a normal `remarkPlugins` entry, which runs
+  **after** Docusaurus' toc plugin. So when we run, `export const toc` already
+  exists (page headings only), and the page's heading nodes already carry ids at
+  `node.data.hProperties.id`.
+
+## Public API
+
+A new optional attribute on `<GitlabReadme>`:
+
+```mdx
+<GitlabReadme project="x/y" toc="sidebar" />
+```
+
+| value         | behavior |
+|---------------|----------|
+| *(omitted)*   | **auto** — today's behavior: inline `<nav>` rendered **iff** the README contains `[[_TOC_]]`; heading ids assigned only then. |
+| `"inline"`    | always render the inline `<nav>` built from headings, even without the marker (at the marker's position if present, else above the first heading). |
+| `"sidebar"`   | no inline nav; README headings are merged into Docusaurus' native right-hand TOC in document order. |
+| `"hidden"`    | no inline nav anywhere; `[[_TOC_]]` marker stripped if present. |
+
+Invalid values throw, honoring the plugin's `strict` mode (build error in
+production, `Fallback` in dev). Values must be static literals — already enforced
+by [src/remark/attributes.ts](../../../src/remark/attributes.ts).
+
+## Heading ids — the cross-cutting requirement
+
+`sidebar` and `inline`-without-marker both need heading ids even when no
+`[[_TOC_]]` marker is present. So:
+
+- The TOC **mode** is threaded into rendering.
+- **Id assignment is decoupled from nav rendering**: ids are assigned whenever a
+  TOC is needed (`inline`, `sidebar`, and `auto`-with-marker).
+- The same github-slugger ids are the single source of truth for both the rendered
+  HTML anchors and the sidebar entries, so sidebar links always match the rendered
+  headings.
+
+## Data flow
+
+```
+fetchReadme(attrs)                      // reads attrs.toc → mode
+  └─ renderMarkdown(md, { tocMode, collect })
+        └─ rehypeGitlabToc({ mode, collect })  // assigns ids; emits/strips nav; pushes entries into collect
+  → ReadmeData { ref, html, toc?: TocEntry[] }  // toc[] returned for sidebar mode
+```
+
+Changes:
+
+- `rehypeGitlabToc` gains an options arg `{ mode, collect? }`. `collect` is a
+  mutable array the caller passes in to receive `{ level, id, text }[]` (rehype
+  plugins can't "return" a value).
+- `renderMarkdown` gains a `tocMode` option and forwards it; default `"auto"`
+  preserves current callers (release notes, file markdown, project description).
+- `ReadmeData` ([src/gitlab/types.ts](../../../src/gitlab/types.ts)) gains optional
+  `toc?: TocEntry[]`.
+- The `fetchReadme` memo cache key gains the mode:
+  `readme:${project}:${ref}:${mode}` (output now varies by mode).
+
+### `rehypeGitlabToc` mode matrix
+
+| mode      | assign ids | inline `<nav>` | marker handling                         | populate `collect` |
+|-----------|------------|----------------|-----------------------------------------|--------------------|
+| `auto`    | iff marker | iff marker     | replace marker with nav (today)         | no                 |
+| `inline`  | yes        | always         | at marker if present, else above first heading | no          |
+| `sidebar` | yes        | no             | strip marker if present                 | yes                |
+| `hidden`  | yes\*      | no             | strip marker if present                 | no                 |
+
+\* `hidden` still assigns ids so deep links / in-page anchors keep working; cheap
+and avoids surprises.
+
+## Sidebar merge (in [src/remark/index.ts](../../../src/remark/index.ts))
+
+For each `<GitlabReadme toc="sidebar">`:
+
+1. During the existing job loop, stash `{ node, entries }` from the returned
+   `ReadmeData.toc`.
+2. After `Promise.all`, run one pass over the tree:
+   - Find the `mdxjsEsm` node declaring `export const toc` that Docusaurus
+     generated. If absent (page with zero headings of its own), create one
+     mirroring Docusaurus' export shape.
+   - Determine the component's document position by the **id of the page heading
+     immediately preceding it** (from a document-order walk; page heading ids come
+     from `node.data.hProperties.id`).
+   - **Splice** the README entries into the existing `toc` array (not a rebuild —
+     we preserve Docusaurus' computed entries and never recompute page-heading
+     HTML values):
+     - Locate the preceding entry by id via DFS of the nested toc tree.
+     - Insert the README block right after it: nest README entries **under** that
+       entry when the README's min heading level is deeper than the preceding
+       entry's level; otherwise insert as following siblings in the same list.
+     - Component before all headings → prepend at root.
+     - Multiple sidebar components on one page are processed in document order;
+       each keys off its own preceding-heading id.
+   - New `ObjectExpression` nodes are produced with `valueToEstree` (already a
+     dependency, used in [src/remark/inject.ts](../../../src/remark/inject.ts)).
+
+The React component renders the README HTML as before; Docusaurus' theme renders
+the sidebar from the augmented export. **No HTML change, no component change, no
+user config change.**
+
+## Error handling
+
+- Invalid `toc` value → `fetchReadme` throws → existing `strict`/`Fallback` path.
+- Missing `export const toc` node → create one matching Docusaurus' shape so README
+  entries still reach the sidebar.
+
+## Testing (TDD)
+
+- `src/gitlab/toc.test.ts`: each mode — ids assigned vs not, nav present/absent/
+  stripped, `collect` populated correctly, nesting by level.
+- `src/gitlab/markdown.test.ts`: `tocMode` forwarding; **XSS regression stays
+  green**.
+- `src/gitlab/fetchers.test.ts`: `fetchReadme` returns `toc[]` for sidebar mode;
+  mode included in cache key (different modes don't collide in cache).
+- `src/remark/index.test.ts`: fake mdast with an existing `export const toc` +
+  page headings + `<GitlabReadme toc="sidebar">`; assert the spliced export incl.
+  document-order position, nesting, and the no-existing-export case.
+- Component test (`src/components/GitlabReadme.test.tsx`): behavior unchanged.
+- e2e (`test/e2e/build.test.ts`, slow/explicit): a docs page with `toc="sidebar"`
+  builds and the right sidebar contains the README headings.
+
+## Known limitations (documented, out of scope)
+
+- **Id collisions**: README slugs are generated in a separate pipeline from the
+  page's headings, so a README `## Installation` and a page `## Installation`
+  could collide. Accepted for now; a future `tocPrefix`/namespacing option is out
+  of scope.
+- **TOC slices**: a page using both `<GitlabReadme>` *and* an imported MDX partial
+  that exports `toc` is an unsupported edge case; we splice into the array but
+  don't reconcile partial slice spreads.
+
+## Documentation
+
+- README: document the `toc` attribute and the three placements.
+- `examples/site/docs/components/readme.mdx`: add a `toc=` example.
+- `examples/gitlab` docs: demonstrate `toc="sidebar"` on a live page.

From a69bd4a7c4d9759eaa63639284cd675be4ea0bae Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:36:54 +0200
Subject: [PATCH 02/15] docs: implementation plan for configurable GitlabReadme
 TOC placement

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 .../2026-06-29-gitlab-readme-toc-placement.md | 1102 +++++++++++++++++
 1 file changed, 1102 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-29-gitlab-readme-toc-placement.md

diff --git a/docs/superpowers/plans/2026-06-29-gitlab-readme-toc-placement.md b/docs/superpowers/plans/2026-06-29-gitlab-readme-toc-placement.md
new file mode 100644
index 0000000..40774c9
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-29-gitlab-readme-toc-placement.md
@@ -0,0 +1,1102 @@
+# GitlabReadme TOC Placement Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `toc` attribute to `<GitlabReadme>` that hides the table of contents, renders it inline (today's behavior), or merges the README's headings into Docusaurus' native right-hand sidebar TOC in document order.
+
+**Architecture:** All work is build-time, in the existing remark pipeline. `renderMarkdown`/`rehypeGitlabToc` learn a TOC mode (`auto`/`inline`/`sidebar`/`hidden`) that controls heading-id assignment and inline `<nav>` emission. For `sidebar` mode the fetcher returns the README's heading entries, and the remark transformer merges them into the page's existing `export const toc` (which Docusaurus' default `toc` plugin generates *before* our plugin runs). The rendered README HTML and the React component are unchanged.
+
+**Tech Stack:** TypeScript (ESM), unified/remark/rehype, hast, `github-slugger`, `estree-util-value-to-estree`, Vitest, Docusaurus 3.
+
+---
+
+## Spec
+
+Design: [docs/superpowers/specs/2026-06-29-gitlab-readme-toc-placement-design.md](../specs/2026-06-29-gitlab-readme-toc-placement-design.md)
+
+## Verified facts (do not re-derive)
+
+- Docusaurus 3.10 `@docusaurus/mdx-loader`: default `headings` and `toc` remark plugins run **before** user `remarkPlugins`, so when our `remarkGitlab` runs, `export const toc` already exists and `heading` mdast nodes carry ids at `node.data.id` and `node.data.hProperties.id`.
+- Docusaurus' `toc` plugin **respects** an explicit `export const toc` and does not overwrite it.
+- The `export const toc` node is an mdast `mdxjsEsm` node whose `data.estree` holds the `ExportNamedDeclaration`; the MDX compiler uses `data.estree` (not the node's `value` string), so mutating `data.estree` in place is sufficient.
+
+## File structure
+
+| File | Change | Responsibility |
+|---|---|---|
+| `src/gitlab/toc.ts` | modify | `rehypeGitlabToc({ mode, collect })`: id assignment + inline nav per mode; export `TocMode`, `TocEntry`. |
+| `src/gitlab/markdown.ts` | modify | Thread `tocMode`/`collectToc` into `rehypeGitlabToc`. |
+| `src/gitlab/types.ts` | modify | `ReadmeData.toc?: TocEntry[]`. |
+| `src/gitlab/fetchers.ts` | modify | `fetchReadme` reads/validates `attrs.toc`, passes mode, returns `toc`, mode in cache key. |
+| `src/remark/toc-merge.ts` | create | Pure TOC-item logic: `TocItem`, `buildTocItems`, `insertReadmeToc`. |
+| `src/remark/toc-export.ts` | create | estree/tree bridge: find/create the `toc` export, read/write items, document-order position, `mergeReadmeTocs`. |
+| `src/remark/index.ts` | modify | Collect sidebar readmes and run `mergeReadmeTocs`. |
+| `test/e2e/fixtures.ts` | modify | Stub README gains h2 headings. |
+| `examples/site/docs/intro.mdx` | modify | Use `toc="sidebar"`. |
+| `examples/site/docs/components/readme.mdx`, `README.md` | modify | Document the `toc` attribute. |
+
+---
+
+## Task 1: TOC rendering modes (`toc.ts` + `markdown.ts`)
+
+**Files:**
+- Modify: `src/gitlab/toc.ts`
+- Modify: `src/gitlab/markdown.ts`
+- Test: `src/gitlab/toc.test.ts`, `src/gitlab/markdown.test.ts`
+
+- [ ] **Step 1: Write failing tests for the new modes**
+
+Append these tests inside the `describe("rehypeGitlabToc", …)` block in `src/gitlab/toc.test.ts`:
+
+```ts
+it("sidebar mode: assigns ids, emits no inline nav, strips the marker", async () => {
+  const md = "[[_TOC_]]\n\n## Install\n\n### Steps\n";
+  const html = await renderMarkdown(md, { tocMode: "sidebar" });
+  expect(html).toContain('<h2 id="install">');
+  expect(html).toContain('<h3 id="steps">');
+  expect(html).not.toContain("gitlab-md-toc");
+  expect(html).not.toContain("GITLAB_MD_TOC_PLACEHOLDER");
+});
+
+it("sidebar mode: assigns ids even without a marker", async () => {
+  const html = await renderMarkdown("## Install\n\n### Steps\n", { tocMode: "sidebar" });
+  expect(html).toContain('<h2 id="install">');
+  expect(html).toContain('<h3 id="steps">');
+  expect(html).not.toContain("gitlab-md-toc");
+});
+
+it("sidebar mode: collects heading entries into the provided array", async () => {
+  const collectToc: { level: number; id: string; text: string }[] = [];
+  await renderMarkdown("## Install\n\n### Steps\n", { tocMode: "sidebar", collectToc });
+  expect(collectToc).toEqual([
+    { level: 2, id: "install", text: "Install" },
+    { level: 3, id: "steps", text: "Steps" },
+  ]);
+});
+
+it("hidden mode: assigns ids but renders no nav and strips the marker", async () => {
+  const html = await renderMarkdown("[[_TOC_]]\n\n## Install\n", { tocMode: "hidden" });
+  expect(html).toContain('<h2 id="install">');
+  expect(html).not.toContain("gitlab-md-toc");
+  expect(html).not.toContain("GITLAB_MD_TOC_PLACEHOLDER");
+});
+
+it("inline mode: renders the nav above the first heading when no marker is present", async () => {
+  const html = await renderMarkdown("intro text\n\n## Install\n\n### Steps\n", { tocMode: "inline" });
+  expect(html).toContain('<nav class="gitlab-md-toc">');
+  expect(html).toContain('<a href="#install">Install</a>');
+  expect(html).toContain('<h2 id="install">');
+  // nav comes before the first heading
+  expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="install">'));
+});
+
+it("inline mode: replaces the marker in place when present", async () => {
+  const html = await renderMarkdown("## A\n\n[[_TOC_]]\n\n## B\n", { tocMode: "inline" });
+  expect(html).toContain('<nav class="gitlab-md-toc">');
+  // nav sits between the two headings (where the marker was)
+  expect(html.indexOf("gitlab-md-toc")).toBeGreaterThan(html.indexOf('<h2 id="a">'));
+  expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="b">'));
+});
+```
+
+- [ ] **Step 2: Run the new tests, verify they fail**
+
+Run: `npx vitest run src/gitlab/toc.test.ts`
+Expected: FAIL — `renderMarkdown` does not accept `tocMode`/`collectToc`, sidebar/hidden/inline behavior absent.
+
+- [ ] **Step 3: Refactor `rehypeGitlabToc` to be mode-aware**
+
+Replace the top of `src/gitlab/toc.ts` (the imports through the end of `rehypeGitlabToc`) with:
+
+```ts
+import GithubSlugger from "github-slugger";
+import type { Root, Element, RootContent } from "hast";
+import { toString } from "hast-util-to-string";
+import { visit, EXIT } from "unist-util-visit";
+
+/**
+ * Token we substitute for a standalone `[[_TOC_]]` line BEFORE markdown parsing.
+ * Underscores inside a word are not emphasis, so this survives the pipeline
+ * intact as plain paragraph text.
+ */
+export const TOC_PLACEHOLDER = "GITLAB_MD_TOC_PLACEHOLDER";
+
+/** Where the README's table of contents is rendered. */
+export type TocMode = "auto" | "inline" | "sidebar" | "hidden";
+
+const HEADING_LEVELS: Record<string, number> = { h2: 2, h3: 3, h4: 4, h5: 5 };
+
+export interface TocEntry {
+  level: number;
+  id: string;
+  text: string;
+}
+
+export interface RehypeGitlabTocOptions {
+  /** Defaults to "auto" (today's marker-driven behavior). */
+  mode?: TocMode;
+  /** When set in "sidebar" mode, collected heading entries are pushed here. */
+  collect?: TocEntry[];
+}
+
+/**
+ * Rehype plugin. Must run AFTER rehype-sanitize so the ids/anchors it generates
+ * are not clobbered by the sanitize schema.
+ *
+ * - auto: today's behavior — no-op unless a `[[_TOC_]]` placeholder is present;
+ *   then assign heading ids and replace the marker with an inline nav.
+ * - inline: always assign ids and render the nav (at the marker if present,
+ *   else above the first heading).
+ * - sidebar: assign ids, strip the marker, push entries into `collect`, no nav.
+ * - hidden: assign ids, strip the marker, no nav.
+ */
+export function rehypeGitlabToc(options: RehypeGitlabTocOptions = {}) {
+  const mode: TocMode = options.mode ?? "auto";
+  return (tree: Root) => {
+    const placeholders: { parent: Root | Element; index: number }[] = [];
+    visit(tree, "element", (node, index, parent) => {
+      if (
+        node.tagName === "p" &&
+        parent &&
+        typeof index === "number" &&
+        toString(node).trim() === TOC_PLACEHOLDER
+      ) {
+        placeholders.push({ parent: parent as Root | Element, index });
+      }
+    });
+
+    const hasMarker = placeholders.length > 0;
+
+    // Auto mode keeps today's behavior: do nothing unless the marker is present.
+    if (mode === "auto" && !hasMarker) return;
+
+    // Assign ids to h2-h5 and collect entries (needed by every active mode).
+    const slugger = new GithubSlugger();
+    const entries: TocEntry[] = [];
+    visit(tree, "element", (node: Element) => {
+      const level = HEADING_LEVELS[node.tagName];
+      if (!level) return;
+      const text = toString(node).trim();
+      node.properties ??= {};
+      const existing = node.properties.id;
+      let id: string;
+      if (typeof existing === "string" && existing.length > 0) {
+        id = existing;
+        slugger.slug(text); // keep dedupe counter in sync
+      } else {
+        id = slugger.slug(text);
+        node.properties.id = id;
+      }
+      entries.push({ level, id, text });
+    });
+
+    if (mode === "sidebar" && options.collect) {
+      options.collect.push(...entries);
+    }
+
+    // Sidebar/hidden render no inline nav; strip the marker if present.
+    if (mode === "sidebar" || mode === "hidden") {
+      for (const { parent, index } of placeholders.reverse()) {
+        parent.children.splice(index, 1);
+      }
+      return;
+    }
+
+    const nav = buildToc(entries);
+
+    // auto-with-marker and inline-with-marker: replace the marker with the nav.
+    if (hasMarker) {
+      for (const { parent, index } of placeholders.reverse()) {
+        if (nav) parent.children.splice(index, 1, structuredClone(nav) as RootContent);
+        else parent.children.splice(index, 1);
+      }
+      return;
+    }
+
+    // inline without a marker: insert the nav above the first heading.
+    if (nav) {
+      let firstHeading: { parent: Root | Element; index: number } | null = null;
+      visit(tree, "element", (n: Element, idx, parent) => {
+        if (HEADING_LEVELS[n.tagName] && parent && typeof idx === "number") {
+          firstHeading = { parent: parent as Root | Element, index: idx };
+          return EXIT;
+        }
+        return undefined;
+      });
+      if (firstHeading) {
+        const { parent, index } = firstHeading;
+        parent.children.splice(index, 0, structuredClone(nav) as RootContent);
+      }
+    }
+  };
+}
+```
+
+Leave the existing `buildToc` function below it unchanged.
+
+- [ ] **Step 4: Thread `tocMode`/`collectToc` through `renderMarkdown`**
+
+In `src/gitlab/markdown.ts`, update the `toc` import and `RenderOptions`, and pass options to the plugin.
+
+Change the import line:
+
+```ts
+import { rehypeGitlabToc, TOC_PLACEHOLDER, type TocMode, type TocEntry } from "./toc.js";
+```
+
+Extend `RenderOptions`:
+
+```ts
+export interface RenderOptions {
+  transformImageSrc?: (src: string) => Promise<string>;
+  transformLinkHref?: (href: string) => Promise<string>;
+  tocMode?: TocMode;
+  collectToc?: TocEntry[];
+}
+```
+
+Change the plugin registration line from `.use(rehypeGitlabToc)` to:
+
+```ts
+    .use(rehypeGitlabToc, { mode: opts.tocMode ?? "auto", collect: opts.collectToc })
+```
+
+- [ ] **Step 5: Run tests, verify they pass**
+
+Run: `npx vitest run src/gitlab/toc.test.ts src/gitlab/markdown.test.ts`
+Expected: PASS — all existing tests (auto mode via `{}`) and the new mode tests pass, including the XSS regression in `markdown.test.ts`.
+
+- [ ] **Step 6: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/gitlab/toc.ts src/gitlab/markdown.ts src/gitlab/toc.test.ts
+git commit -m "feat: mode-aware TOC rendering in rehypeGitlabToc
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: `fetchReadme` reads the `toc` attribute
+
+**Files:**
+- Modify: `src/gitlab/types.ts`
+- Modify: `src/gitlab/fetchers.ts`
+- Test: `src/gitlab/fetchers.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Replace the `describe("fetchReadme", …)` block in `src/gitlab/fetchers.test.ts` by adding these tests inside it (keep the two existing ones):
+
+```ts
+  it("sidebar mode returns toc entries and assigns heading ids", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n\n### Steps\n"),
+    };
+    const data = await fetchReadme(ctx(client), { project: "g/r", toc: "sidebar" });
+    expect(data.toc).toEqual([
+      { level: 2, id: "install", text: "Install" },
+      { level: 3, id: "steps", text: "Steps" },
+    ]);
+    expect(data.html).toContain('<h2 id="install">');
+  });
+
+  it("does not attach toc entries when toc is not 'sidebar'", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    const data = await fetchReadme(ctx(client), { project: "g/r", toc: "inline" });
+    expect(data.toc).toBeUndefined();
+    expect(data.html).toContain("gitlab-md-toc");
+  });
+
+  it("rejects an invalid toc value", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    await expect(fetchReadme(ctx(client), { project: "g/r", toc: "left" })).rejects.toThrow(
+      /"toc" must be one of/,
+    );
+  });
+
+  it("keys the cache by toc mode so different modes do not collide", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    const c = ctx(client);
+    const sidebar = await fetchReadme(c, { project: "g/r", toc: "sidebar" });
+    const inline = await fetchReadme(c, { project: "g/r", toc: "inline" });
+    expect(sidebar.toc).toBeDefined();
+    expect(inline.toc).toBeUndefined();
+    expect(inline.html).toContain("gitlab-md-toc");
+  });
+```
+
+- [ ] **Step 2: Run the new tests, verify they fail**
+
+Run: `npx vitest run src/gitlab/fetchers.test.ts`
+Expected: FAIL — `fetchReadme` ignores `toc`, never returns `toc`, never throws on bad values.
+
+- [ ] **Step 3: Add `toc` to `ReadmeData`**
+
+In `src/gitlab/types.ts`, add a type-only import at the top:
+
+```ts
+import type { TocEntry } from "./toc.js";
+```
+
+and extend the interface:
+
+```ts
+export interface ReadmeData {
+  ref: string;
+  html: string;
+  toc?: TocEntry[];
+}
+```
+
+- [ ] **Step 4: Update `fetchReadme`**
+
+In `src/gitlab/fetchers.ts`, add to the imports near the top (after the `renderMarkdown` import):
+
+```ts
+import type { TocEntry, TocMode } from "./toc";
+```
+
+Add this helper above `fetchReadme`:
+
+```ts
+function readTocMode(value: unknown): TocMode {
+  if (value === undefined) return "auto";
+  if (value === "hidden" || value === "inline" || value === "sidebar") return value;
+  throw new Error(
+    `@ebuildy/docusaurus-plugin-gitlab: <GitlabReadme> "toc" must be one of ` +
+      `"hidden", "inline", "sidebar"; got ${JSON.stringify(value)}.`,
+  );
+}
+```
+
+Replace the body of `fetchReadme` with:
+
+```ts
+export async function fetchReadme(ctx: GitLabContext, attrs: Attrs): Promise<ReadmeData> {
+  const project = String(attrs.project);
+  const explicitRef = attrs.ref as string | undefined;
+  const tocMode = readTocMode(attrs.toc);
+  return memo(ctx, `readme:${project}:${explicitRef ?? "default"}:${tocMode}`, async () => {
+    const ref =
+      explicitRef ?? (await ctx.client.getProject(attrs.project as string | number)).default_branch;
+    const md = await ctx.client.getFileRaw(attrs.project as string | number, "README.md", ref);
+    const collectToc: TocEntry[] = [];
+    const html = await renderMarkdown(md, {
+      tocMode,
+      collectToc,
+      transformImageSrc: (src) => ctx.assets.localize(src, ref, project),
+    });
+    const result: ReadmeData = { ref, html };
+    if (tocMode === "sidebar") result.toc = collectToc;
+    return result;
+  });
+}
+```
+
+- [ ] **Step 5: Run tests, verify they pass**
+
+Run: `npx vitest run src/gitlab/fetchers.test.ts`
+Expected: PASS.
+
+- [ ] **Step 6: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/gitlab/types.ts src/gitlab/fetchers.ts src/gitlab/fetchers.test.ts
+git commit -m "feat: fetchReadme reads the toc attribute and returns sidebar entries
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: Pure TOC-item merge logic (`toc-merge.ts`)
+
+**Files:**
+- Create: `src/remark/toc-merge.ts`
+- Test: `src/remark/toc-merge.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/remark/toc-merge.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { buildTocItems, insertReadmeToc, type TocItem } from "./toc-merge";
+
+describe("buildTocItems", () => {
+  it("returns [] for no entries", () => {
+    expect(buildTocItems([])).toEqual([]);
+  });
+
+  it("nests deeper headings under the preceding shallower one", () => {
+    const items = buildTocItems([
+      { level: 2, id: "a", text: "A" },
+      { level: 3, id: "b", text: "B" },
+      { level: 2, id: "c", text: "C" },
+    ]);
+    expect(items).toEqual([
+      { value: "A", id: "a", level: 2, children: [{ value: "B", id: "b", level: 3, children: [] }] },
+      { value: "C", id: "c", level: 2, children: [] },
+    ]);
+  });
+});
+
+describe("insertReadmeToc", () => {
+  const page: TocItem[] = [
+    { value: "Intro", id: "intro", level: 2, children: [] },
+    { value: "Outro", id: "outro", level: 2, children: [] },
+  ];
+  const readme: TocItem[] = [{ value: "Install", id: "install", level: 2, children: [] }];
+
+  it("prepends README items when there is no preceding heading", () => {
+    const out = insertReadmeToc(page, null, readme);
+    expect(out.map((i) => i.id)).toEqual(["install", "intro", "outro"]);
+  });
+
+  it("inserts README items right after the preceding sibling heading", () => {
+    const out = insertReadmeToc(page, "intro", readme);
+    expect(out.map((i) => i.id)).toEqual(["intro", "install", "outro"]);
+  });
+
+  it("nests README items under the preceding heading when README is deeper", () => {
+    const out = insertReadmeToc(page, "intro", [
+      { value: "Deep", id: "deep", level: 3, children: [] },
+    ]);
+    expect(out[0].children.map((c) => c.id)).toEqual(["deep"]);
+  });
+
+  it("appends at root when the preceding id is not found", () => {
+    const out = insertReadmeToc(page, "missing", readme);
+    expect(out.map((i) => i.id)).toEqual(["intro", "outro", "install"]);
+  });
+
+  it("does not mutate the input array", () => {
+    insertReadmeToc(page, "intro", readme);
+    expect(page.map((i) => i.id)).toEqual(["intro", "outro"]);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test, verify it fails**
+
+Run: `npx vitest run src/remark/toc-merge.test.ts`
+Expected: FAIL — module `./toc-merge` does not exist.
+
+- [ ] **Step 3: Implement `toc-merge.ts`**
+
+Create `src/remark/toc-merge.ts`:
+
+```ts
+import type { TocEntry } from "../gitlab/toc.js";
+
+/** A single right-sidebar TOC entry, matching Docusaurus' `toc` export shape. */
+export interface TocItem {
+  value: string;
+  id: string;
+  level: number;
+  children: TocItem[];
+}
+
+/** Nest flat heading entries into a level-based tree (README's own min level = root). */
+export function buildTocItems(entries: TocEntry[]): TocItem[] {
+  if (entries.length === 0) return [];
+  const root: TocItem[] = [];
+  const minLevel = Math.min(...entries.map((e) => e.level));
+  const stack: { level: number; list: TocItem[] }[] = [{ level: minLevel, list: root }];
+  for (const entry of entries) {
+    const item: TocItem = { value: entry.text, id: entry.id, level: entry.level, children: [] };
+    while (stack.length > 1 && stack[stack.length - 1].level > entry.level) stack.pop();
+    let top = stack[stack.length - 1];
+    if (entry.level > top.level) {
+      const last = top.list[top.list.length - 1];
+      const childList = last ? last.children : top.list;
+      stack.push({ level: entry.level, list: childList });
+      top = stack[stack.length - 1];
+    }
+    top.list.push(item);
+  }
+  return root;
+}
+
+/**
+ * Insert `readmeItems` into a copy of `items` at the position following the
+ * page heading with id `precedingId`:
+ *  - precedingId === null  → prepend (component sits before all page headings)
+ *  - README is deeper than the preceding heading → nest under it
+ *  - otherwise → insert as following siblings
+ *  - preceding id not found → append at root
+ * Pure: never mutates the inputs.
+ */
+export function insertReadmeToc(
+  items: TocItem[],
+  precedingId: string | null,
+  readmeItems: TocItem[],
+): TocItem[] {
+  if (readmeItems.length === 0) return items;
+  const block = structuredClone(readmeItems);
+  if (precedingId === null) return [...block, ...structuredClone(items)];
+
+  const copy = structuredClone(items);
+  const readmeMinLevel = Math.min(...readmeItems.map((i) => i.level));
+
+  const recur = (list: TocItem[]): boolean => {
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].id === precedingId) {
+        if (readmeMinLevel > list[i].level) list[i].children.push(...block);
+        else list.splice(i + 1, 0, ...block);
+        return true;
+      }
+      if (recur(list[i].children)) return true;
+    }
+    return false;
+  };
+
+  if (!recur(copy)) return [...copy, ...block];
+  return copy;
+}
+```
+
+- [ ] **Step 4: Run the test, verify it passes**
+
+Run: `npx vitest run src/remark/toc-merge.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/remark/toc-merge.ts src/remark/toc-merge.test.ts
+git commit -m "feat: pure TOC-item nesting and merge helpers
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: estree/tree bridge (`toc-export.ts`)
+
+**Files:**
+- Create: `src/remark/toc-export.ts`
+- Test: `src/remark/toc-export.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/remark/toc-export.test.ts`:
+
+```ts
+import { valueToEstree } from "estree-util-value-to-estree";
+import { describe, it, expect } from "vitest";
+import {
+  findTocExport,
+  makeTocExportNode,
+  precedingHeadingId,
+  readTocItems,
+  writeTocItems,
+  TocSliceError,
+  mergeReadmeTocs,
+} from "./toc-export";
+import type { TocItem } from "./toc-merge";
+
+const items: TocItem[] = [
+  { value: "Intro", id: "intro", level: 2, children: [{ value: "Sub", id: "sub", level: 3, children: [] }] },
+];
+
+describe("readTocItems / writeTocItems", () => {
+  it("round-trips toc items through estree", () => {
+    expect(readTocItems(writeTocItems(items))).toEqual(items);
+  });
+
+  it("throws TocSliceError on a spread element (TOC slice)", () => {
+    const arr = { type: "ArrayExpression", elements: [{ type: "SpreadElement" }] };
+    expect(() => readTocItems(arr)).toThrow(TocSliceError);
+  });
+});
+
+describe("findTocExport / makeTocExportNode", () => {
+  it("creates and then finds a toc export node", () => {
+    const node = makeTocExportNode(items);
+    const tree = { type: "root", children: [node] };
+    const found = findTocExport(tree);
+    expect(found).not.toBeNull();
+    expect(readTocItems(found!.declarator.init)).toEqual(items);
+  });
+
+  it("returns null when there is no toc export", () => {
+    expect(findTocExport({ type: "root", children: [] })).toBeNull();
+  });
+});
+
+describe("precedingHeadingId", () => {
+  it("returns the id of the heading immediately before the target node", () => {
+    const target = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = {
+      type: "root",
+      children: [
+        { type: "heading", data: { id: "first", hProperties: { id: "first" } } },
+        { type: "paragraph" },
+        target,
+        { type: "heading", data: { id: "later", hProperties: { id: "later" } } },
+      ],
+    };
+    expect(precedingHeadingId(tree, target)).toBe("first");
+  });
+
+  it("returns null when no heading precedes the target", () => {
+    const target = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = { type: "root", children: [target] };
+    expect(precedingHeadingId(tree, target)).toBeNull();
+  });
+});
+
+describe("mergeReadmeTocs", () => {
+  it("merges README entries into the existing toc export at the component position", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tocNode = makeTocExportNode([{ value: "Intro", id: "intro", level: 2, children: [] }]);
+    const tree = {
+      type: "root",
+      children: [
+        tocNode,
+        { type: "heading", data: { id: "intro", hProperties: { id: "intro" } } },
+        readmeNode,
+      ],
+    };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i) => i.id)).toEqual(["intro", "install"]);
+  });
+
+  it("creates a toc export when none exists", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = { type: "root", children: [readmeNode] };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i) => i.id)).toEqual(["install"]);
+  });
+
+  it("leaves the export untouched when it contains a TOC slice", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tocNode = makeTocExportNode([]);
+    // Simulate a slice: replace elements with a spread.
+    tocNode.data.estree.body[0].declaration.declarations[0].init = valueToEstree([]);
+    tocNode.data.estree.body[0].declaration.declarations[0].init.elements = [{ type: "SpreadElement" }];
+    const tree = { type: "root", children: [tocNode, readmeNode] };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(found.declarator.init.elements).toEqual([{ type: "SpreadElement" }]);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test, verify it fails**
+
+Run: `npx vitest run src/remark/toc-export.test.ts`
+Expected: FAIL — module `./toc-export` does not exist.
+
+- [ ] **Step 3: Implement `toc-export.ts`**
+
+Create `src/remark/toc-export.ts`:
+
+```ts
+import { valueToEstree } from "estree-util-value-to-estree";
+import { visit, EXIT } from "unist-util-visit";
+import type { TocEntry } from "../gitlab/toc.js";
+import { buildTocItems, insertReadmeToc, type TocItem } from "./toc-merge.js";
+
+/** Thrown when the page `toc` export contains a TOC slice (spread) we can't round-trip. */
+export class TocSliceError extends Error {}
+
+/** Find the `export const toc = [...]` mdxjsEsm node Docusaurus generated. */
+export function findTocExport(tree: any): { node: any; declarator: any } | null {
+  for (const child of tree.children ?? []) {
+    if (child.type !== "mdxjsEsm") continue;
+    const body = child.data?.estree?.body ?? [];
+    for (const stmt of body) {
+      if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "VariableDeclaration") {
+        for (const d of stmt.declaration.declarations) {
+          if (d.id?.type === "Identifier" && d.id.name === "toc" && d.init?.type === "ArrayExpression") {
+            return { node: child, declarator: d };
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/** Read an estree ArrayExpression of toc items back into plain TocItem objects. */
+export function readTocItems(arrayExpr: any): TocItem[] {
+  return (arrayExpr.elements ?? []).map(readItem);
+}
+
+function readItem(el: any): TocItem {
+  if (!el || el.type !== "ObjectExpression") throw new TocSliceError();
+  const item: TocItem = { value: "", id: "", level: 0, children: [] };
+  for (const prop of el.properties) {
+    if (prop.type !== "Property") throw new TocSliceError();
+    const key = prop.key.type === "Identifier" ? prop.key.name : prop.key.value;
+    if (key === "value") item.value = String(prop.value.value);
+    else if (key === "id") item.id = String(prop.value.value);
+    else if (key === "level") item.level = Number(prop.value.value);
+    else if (key === "children") item.children = (prop.value.elements ?? []).map(readItem);
+  }
+  return item;
+}
+
+/** Serialize TocItem objects to an estree ArrayExpression. */
+export function writeTocItems(items: TocItem[]): any {
+  return valueToEstree(items, { preserveReferences: false });
+}
+
+/** Build a fresh `export const toc = [...]` mdxjsEsm node. */
+export function makeTocExportNode(items: TocItem[]): any {
+  const estree = {
+    type: "Program",
+    sourceType: "module",
+    body: [
+      {
+        type: "ExportNamedDeclaration",
+        specifiers: [],
+        source: null,
+        declaration: {
+          type: "VariableDeclaration",
+          kind: "const",
+          declarations: [
+            {
+              type: "VariableDeclarator",
+              id: { type: "Identifier", name: "toc" },
+              init: writeTocItems(items),
+            },
+          ],
+        },
+      },
+    ],
+  };
+  return { type: "mdxjsEsm", value: "", data: { estree } };
+}
+
+/** Id of the page heading immediately preceding `target` in document order, or null. */
+export function precedingHeadingId(tree: any, target: any): string | null {
+  let last: string | null = null;
+  visit(tree, (node: any) => {
+    if (node === target) return EXIT;
+    if (node.type === "heading") {
+      const id = node.data?.id ?? node.data?.hProperties?.id;
+      if (typeof id === "string") last = id;
+    }
+    return undefined;
+  });
+  return last;
+}
+
+/**
+ * Merge each sidebar README's headings into the page's `toc` export, in document
+ * order. Creates the export if absent. If the export contains a TOC slice
+ * (unsupported edge case), leaves it untouched.
+ */
+export function mergeReadmeTocs(
+  tree: any,
+  readmes: { node: any; entries: TocEntry[] }[],
+): void {
+  if (readmes.length === 0) return;
+
+  let target = findTocExport(tree);
+  if (!target) {
+    tree.children.push(makeTocExportNode([]));
+    target = findTocExport(tree)!;
+  }
+
+  let items: TocItem[];
+  try {
+    items = readTocItems(target.declarator.init);
+  } catch (err) {
+    if (err instanceof TocSliceError) return; // page uses TOC slices: unsupported
+    throw err;
+  }
+
+  for (const { node, entries } of readmes) {
+    const precedingId = precedingHeadingId(tree, node);
+    items = insertReadmeToc(items, precedingId, buildTocItems(entries));
+  }
+
+  target.declarator.init = writeTocItems(items);
+}
+```
+
+- [ ] **Step 4: Run the test, verify it passes**
+
+Run: `npx vitest run src/remark/toc-export.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Typecheck**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/remark/toc-export.ts src/remark/toc-export.test.ts
+git commit -m "feat: estree bridge to merge README headings into the page toc export
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Wire the merge into the remark transformer
+
+**Files:**
+- Modify: `src/remark/index.ts`
+- Test: `src/remark/index.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+In `src/remark/index.test.ts`, add a helper to read a toc export and tests. First add this import at the top:
+
+```ts
+import { findTocExport, readTocItems } from "./toc-export";
+```
+
+Then add these tests inside `describe("remarkGitlab", …)`:
+
+```ts
+  it("merges sidebar README headings into the page toc export", async () => {
+    const { fetchReadme } = await import("../gitlab/fetchers.js");
+    (fetchReadme as any).mockResolvedValue({
+      ref: "main",
+      html: "<h2 id=\"install\">Install</h2>",
+      toc: [{ level: 2, id: "install", text: "Install" }],
+    });
+    const src = [
+      'export const toc = [{ value: "Intro", id: "intro", level: 2, children: [] }];',
+      "",
+      '<GitlabReadme project="g/r" toc="sidebar" />',
+    ].join("\n");
+    const tree = await transform(src, { host: "https://gitlab.com", strict: true });
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i: any) => i.id)).toContain("install");
+  });
+
+  it("does not touch the toc export for non-sidebar readmes", async () => {
+    const { fetchReadme } = await import("../gitlab/fetchers.js");
+    (fetchReadme as any).mockResolvedValue({ ref: "main", html: "<p>x</p>" });
+    const src = [
+      'export const toc = [{ value: "Intro", id: "intro", level: 2, children: [] }];',
+      "",
+      '<GitlabReadme project="g/r" toc="inline" />',
+    ].join("\n");
+    const tree = await transform(src, { host: "https://gitlab.com", strict: true });
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i: any) => i.id)).toEqual(["intro"]);
+  });
+```
+
+- [ ] **Step 2: Run the new tests, verify they fail**
+
+Run: `npx vitest run src/remark/index.test.ts`
+Expected: FAIL — the transformer does not merge README headings into the toc export.
+
+- [ ] **Step 3: Wire `mergeReadmeTocs` into the transformer**
+
+In `src/remark/index.ts`, add the import (next to the other `./` imports):
+
+```ts
+import { mergeReadmeTocs } from "./toc-export.js";
+```
+
+Inside the returned `transformer`, declare a collector before the `await Promise.all(...)` (right after `const jobs ...`/`visit(...)` block builds `jobs`):
+
+```ts
+    const sidebarReadmes: { node: any; entries: any[] }[] = [];
+```
+
+In the job body, immediately after the existing `injectProp(node, "data", data);` line, add:
+
+```ts
+          if (node.name === "GitlabReadme" && Array.isArray((data as any)?.toc)) {
+            sidebarReadmes.push({ node, entries: (data as any).toc });
+          }
+```
+
+After the `await Promise.all(...)` call (at the end of the transformer), add:
+
+```ts
+    mergeReadmeTocs(tree, sidebarReadmes);
+```
+
+- [ ] **Step 4: Run tests, verify they pass**
+
+Run: `npx vitest run src/remark/index.test.ts`
+Expected: PASS (existing tests still pass; new merge tests pass).
+
+- [ ] **Step 5: Full unit suite + typecheck**
+
+Run: `npx vitest run && npm run typecheck`
+Expected: all pass, no type errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/remark/index.ts src/remark/index.test.ts
+git commit -m "feat: merge sidebar README headings into the page toc during transform
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: e2e coverage + example site
+
+**Files:**
+- Modify: `test/e2e/fixtures.ts`
+- Modify: `examples/site/docs/intro.mdx`
+- Modify: `test/e2e/build.test.ts`
+
+- [ ] **Step 1: Give the stub README real headings**
+
+In `test/e2e/fixtures.ts`, change the README response (the `/repository/files/README.md/raw` branch) from:
+
+```ts
+      return send("# Hello\n\nReadme body.\n\n![logo](./logo.png)", "text/plain");
+```
+
+to:
+
+```ts
+      return send(
+        "# Hello\n\nReadme body.\n\n## Install\n\nsetup\n\n## Usage\n\ngo\n\n![logo](./logo.png)",
+        "text/plain",
+      );
+```
+
+- [ ] **Step 2: Use sidebar mode on the index page**
+
+In `examples/site/docs/intro.mdx`, change:
+
+```mdx
+<GitlabReadme project="group/repo" />
+```
+
+to:
+
+```mdx
+<GitlabReadme project="group/repo" toc="sidebar" />
+```
+
+- [ ] **Step 3: Add a failing e2e assertion**
+
+In `test/e2e/build.test.ts`, add this test inside the `describe("e2e: docusaurus build", …)` block:
+
+```ts
+  it("merges sidebar README headings into the page's right-hand TOC", () => {
+    const html = readFileSync(join(siteDir, "build", "index.html"), "utf8");
+    // README headings appear as Docusaurus TOC links, not as an inline gitlab nav.
+    expect(html).toContain("table-of-contents");
+    expect(html).toContain('href="#install"');
+    expect(html).toContain('href="#usage"');
+    expect(html).not.toContain("gitlab-md-toc");
+    // README heading ids are present in the rendered body for the anchors to resolve.
+    expect(html).toContain('id="install"');
+  });
+```
+
+- [ ] **Step 4: Run the e2e build test**
+
+Run: `npx vitest run test/e2e/build.test.ts`
+Expected: PASS (slow, ~1 min). Existing e2e assertions ("Readme body", localized assets) still pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/e2e/fixtures.ts test/e2e/build.test.ts examples/site/docs/intro.mdx
+git commit -m "test: e2e coverage for GitlabReadme toc=sidebar
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 7: Documentation
+
+**Files:**
+- Modify: `examples/site/docs/components/readme.mdx`
+- Modify: `README.md`
+
+- [ ] **Step 1: Document the attribute in the component doc page**
+
+In `examples/site/docs/components/readme.mdx`, add a `toc` row to the Props table (after the `ref` row):
+
+```md
+| `toc` | `"hidden" \| "inline" \| "sidebar"` | _auto_ | Where to render the table of contents. Omitted = today's behavior (inline only if the README has a `[[_TOC_]]` marker). |
+```
+
+Replace the "Table of contents" section at the bottom with:
+
+```md
+## Table of contents
+
+By default a `[[_TOC_]]` marker in the README is expanded into an inline table of
+contents linking to the project's headings. The `toc` prop overrides this:
+
+- `toc="inline"` — always render the inline TOC, even without a `[[_TOC_]]` marker.
+- `toc="sidebar"` — render the README's headings in the page's right-hand sidebar,
+  like a normal Docusaurus page (merged with the page's own headings in document
+  order). No inline TOC is rendered.
+- `toc="hidden"` — never render a TOC; any `[[_TOC_]]` marker is stripped.
+
+```mdx
+<GitlabReadme project="group/repo" toc="sidebar" />
+```
+```
+
+- [ ] **Step 2: Document the attribute in the root README**
+
+In `README.md`, find the `<GitlabReadme>` section/usage and add a sentence plus example documenting the `toc` prop with its three values (`hidden`, `inline`, `sidebar`) and the default (auto / marker-driven). Match the surrounding documentation style. Example to include:
+
+```mdx
+<GitlabReadme project="group/repo" toc="sidebar" />
+```
+
+- [ ] **Step 3: Verify docs build (optional but recommended)**
+
+Run: `npx vitest run test/e2e/build.test.ts`
+Expected: PASS — the example site (which includes `readme.mdx`) still builds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md examples/site/docs/components/readme.mdx
+git commit -m "docs: document the GitlabReadme toc attribute
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Final verification
+
+- [ ] Run the full unit suite: `npx vitest run` — all pass.
+- [ ] Run typecheck: `npm run typecheck` — no errors.
+- [ ] Run the build: `npm run build` — compiles clean to `dist/`.
+- [ ] Run e2e: `npx vitest run test/e2e/build.test.ts` — passes.
+- [ ] Confirm the XSS regression test in `src/gitlab/markdown.test.ts` is green.

From c657863ce46fc2f0b04b4870516461a2308454b4 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:40:48 +0200
Subject: [PATCH 03/15] feat: mode-aware TOC rendering in rehypeGitlabToc

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/gitlab/markdown.ts |  6 ++--
 src/gitlab/toc.test.ts | 47 ++++++++++++++++++++++++++
 src/gitlab/toc.ts      | 77 ++++++++++++++++++++++++++++++++++--------
 3 files changed, 114 insertions(+), 16 deletions(-)

diff --git a/src/gitlab/markdown.ts b/src/gitlab/markdown.ts
index ba030f4..0de9565 100644
--- a/src/gitlab/markdown.ts
+++ b/src/gitlab/markdown.ts
@@ -8,11 +8,13 @@ import remarkRehype from "remark-rehype";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { rehypeGitlabAlerts } from "./alerts.js";
-import { rehypeGitlabToc, TOC_PLACEHOLDER } from "./toc.js";
+import { rehypeGitlabToc, TOC_PLACEHOLDER, type TocMode, type TocEntry } from "./toc.js";
 
 export interface RenderOptions {
   transformImageSrc?: (src: string) => Promise<string>;
   transformLinkHref?: (href: string) => Promise<string>;
+  tocMode?: TocMode;
+  collectToc?: TocEntry[];
 }
 
 // Matches a standalone `[[_TOC_]]` line (allowing leading/trailing spaces/tabs).
@@ -40,7 +42,7 @@ export async function renderMarkdown(md: string, opts: RenderOptions): Promise<s
     .use(remarkRehype, { allowDangerousHtml: true })
     .use(rehypeRaw)
     .use(rehypeSanitize)
-    .use(rehypeGitlabToc)
+    .use(rehypeGitlabToc, { mode: opts.tocMode ?? "auto", collect: opts.collectToc })
     .use(rehypeGitlabAlerts)
     .use(collect)
     .use(rehypeStringify);
diff --git a/src/gitlab/toc.test.ts b/src/gitlab/toc.test.ts
index 2b7e2b0..859f6f1 100644
--- a/src/gitlab/toc.test.ts
+++ b/src/gitlab/toc.test.ts
@@ -78,4 +78,51 @@ describe("rehypeGitlabToc", () => {
     // TOC link text is the heading's plain text, anchored to its slug.
     expect(html).toContain('<a href="#danger">Danger</a>');
   });
+
+  it("sidebar mode: assigns ids, emits no inline nav, strips the marker", async () => {
+    const md = "[[_TOC_]]\n\n## Install\n\n### Steps\n";
+    const html = await renderMarkdown(md, { tocMode: "sidebar" });
+    expect(html).toContain('<h2 id="install">');
+    expect(html).toContain('<h3 id="steps">');
+    expect(html).not.toContain("gitlab-md-toc");
+    expect(html).not.toContain("GITLAB_MD_TOC_PLACEHOLDER");
+  });
+
+  it("sidebar mode: assigns ids even without a marker", async () => {
+    const html = await renderMarkdown("## Install\n\n### Steps\n", { tocMode: "sidebar" });
+    expect(html).toContain('<h2 id="install">');
+    expect(html).toContain('<h3 id="steps">');
+    expect(html).not.toContain("gitlab-md-toc");
+  });
+
+  it("sidebar mode: collects heading entries into the provided array", async () => {
+    const collectToc: { level: number; id: string; text: string }[] = [];
+    await renderMarkdown("## Install\n\n### Steps\n", { tocMode: "sidebar", collectToc });
+    expect(collectToc).toEqual([
+      { level: 2, id: "install", text: "Install" },
+      { level: 3, id: "steps", text: "Steps" },
+    ]);
+  });
+
+  it("hidden mode: assigns ids but renders no nav and strips the marker", async () => {
+    const html = await renderMarkdown("[[_TOC_]]\n\n## Install\n", { tocMode: "hidden" });
+    expect(html).toContain('<h2 id="install">');
+    expect(html).not.toContain("gitlab-md-toc");
+    expect(html).not.toContain("GITLAB_MD_TOC_PLACEHOLDER");
+  });
+
+  it("inline mode: renders the nav above the first heading when no marker is present", async () => {
+    const html = await renderMarkdown("intro text\n\n## Install\n\n### Steps\n", { tocMode: "inline" });
+    expect(html).toContain('<nav class="gitlab-md-toc">');
+    expect(html).toContain('<a href="#install">Install</a>');
+    expect(html).toContain('<h2 id="install">');
+    expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="install">'));
+  });
+
+  it("inline mode: replaces the marker in place when present", async () => {
+    const html = await renderMarkdown("## A\n\n[[_TOC_]]\n\n## B\n", { tocMode: "inline" });
+    expect(html).toContain('<nav class="gitlab-md-toc">');
+    expect(html.indexOf("gitlab-md-toc")).toBeGreaterThan(html.indexOf('<h2 id="a">'));
+    expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="b">'));
+  });
 });
diff --git a/src/gitlab/toc.ts b/src/gitlab/toc.ts
index 0863c27..2cabed4 100644
--- a/src/gitlab/toc.ts
+++ b/src/gitlab/toc.ts
@@ -1,30 +1,46 @@
 import GithubSlugger from "github-slugger";
 import type { Root, Element, RootContent } from "hast";
 import { toString } from "hast-util-to-string";
-import { visit } from "unist-util-visit";
+import { visit, EXIT } from "unist-util-visit";
 
 /**
  * Token we substitute for a standalone `[[_TOC_]]` line BEFORE markdown parsing.
  * Underscores inside a word are not emphasis, so this survives the pipeline
- * intact as plain paragraph text — unlike `[[_TOC_]]`, whose underscores would
- * be parsed into `<em>`.
+ * intact as plain paragraph text.
  */
 export const TOC_PLACEHOLDER = "GITLAB_MD_TOC_PLACEHOLDER";
 
+/** Where the README's table of contents is rendered. */
+export type TocMode = "auto" | "inline" | "sidebar" | "hidden";
+
 const HEADING_LEVELS: Record<string, number> = { h2: 2, h3: 3, h4: 4, h5: 5 };
 
-interface TocEntry {
+export interface TocEntry {
   level: number;
   id: string;
   text: string;
 }
 
+export interface RehypeGitlabTocOptions {
+  /** Defaults to "auto" (today's marker-driven behavior). */
+  mode?: TocMode;
+  /** When set in "sidebar" mode, collected heading entries are pushed here. */
+  collect?: TocEntry[];
+}
+
 /**
  * Rehype plugin. Must run AFTER rehype-sanitize so the ids/anchors it generates
- * are not clobbered by the sanitize schema. No-op unless a placeholder paragraph
- * is present (keeps heading-id injection scoped to documents that use the marker).
+ * are not clobbered by the sanitize schema.
+ *
+ * - auto: today's behavior — no-op unless a `[[_TOC_]]` placeholder is present;
+ *   then assign heading ids and replace the marker with an inline nav.
+ * - inline: always assign ids and render the nav (at the marker if present,
+ *   else above the first heading).
+ * - sidebar: assign ids, strip the marker, push entries into `collect`, no nav.
+ * - hidden: assign ids, strip the marker, no nav.
  */
-export function rehypeGitlabToc() {
+export function rehypeGitlabToc(options: RehypeGitlabTocOptions = {}) {
+  const mode: TocMode = options.mode ?? "auto";
   return (tree: Root) => {
     const placeholders: { parent: Root | Element; index: number }[] = [];
     visit(tree, "element", (node, index, parent) => {
@@ -37,8 +53,13 @@ export function rehypeGitlabToc() {
         placeholders.push({ parent: parent as Root | Element, index });
       }
     });
-    if (placeholders.length === 0) return;
 
+    const hasMarker = placeholders.length > 0;
+
+    // Auto mode keeps today's behavior: do nothing unless the marker is present.
+    if (mode === "auto" && !hasMarker) return;
+
+    // Assign ids to h2-h5 and collect entries (needed by every active mode).
     const slugger = new GithubSlugger();
     const entries: TocEntry[] = [];
     visit(tree, "element", (node: Element) => {
@@ -58,15 +79,43 @@ export function rehypeGitlabToc() {
       entries.push({ level, id, text });
     });
 
-    const nav = buildToc(entries);
+    if (mode === "sidebar" && options.collect) {
+      options.collect.push(...entries);
+    }
 
-    // Splice back-to-front so earlier indices stay valid.
-    for (const { parent, index } of placeholders.reverse()) {
-      if (nav) {
-        parent.children.splice(index, 1, structuredClone(nav) as RootContent);
-      } else {
+    // Sidebar/hidden render no inline nav; strip the marker if present.
+    if (mode === "sidebar" || mode === "hidden") {
+      for (const { parent, index } of placeholders.reverse()) {
         parent.children.splice(index, 1);
       }
+      return;
+    }
+
+    const nav = buildToc(entries);
+
+    // auto-with-marker and inline-with-marker: replace the marker with the nav.
+    if (hasMarker) {
+      for (const { parent, index } of placeholders.reverse()) {
+        if (nav) parent.children.splice(index, 1, structuredClone(nav) as RootContent);
+        else parent.children.splice(index, 1);
+      }
+      return;
+    }
+
+    // inline without a marker: insert the nav above the first heading.
+    if (nav) {
+      let firstHeading: { parent: Root | Element; index: number } | null = null;
+      visit(tree, "element", (n: Element, idx, parent) => {
+        if (HEADING_LEVELS[n.tagName] && parent && typeof idx === "number") {
+          firstHeading = { parent: parent as Root | Element, index: idx };
+          return EXIT;
+        }
+        return undefined;
+      });
+      if (firstHeading !== null) {
+        const target: { parent: Root | Element; index: number } = firstHeading;
+        target.parent.children.splice(target.index, 0, structuredClone(nav) as RootContent);
+      }
     }
   };
 }

From bf4a9913c37f280ac962f58ad89f6e5749752fa3 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:48:55 +0200
Subject: [PATCH 04/15] refactor: anchor inline TOC to first top-level heading

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/gitlab/toc.test.ts |  8 ++++++++
 src/gitlab/toc.ts      | 26 ++++++++++++++------------
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/gitlab/toc.test.ts b/src/gitlab/toc.test.ts
index 859f6f1..feb2e3e 100644
--- a/src/gitlab/toc.test.ts
+++ b/src/gitlab/toc.test.ts
@@ -119,6 +119,14 @@ describe("rehypeGitlabToc", () => {
     expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="install">'));
   });
 
+  it("inline mode: anchors the nav to the first top-level heading, not one inside a blockquote", async () => {
+    const html = await renderMarkdown("> ## Quoted\n\nintro\n\n## Real\n", { tocMode: "inline" });
+    // The nav must not be injected inside the blockquote.
+    const blockquote = html.slice(html.indexOf("<blockquote>"), html.indexOf("</blockquote>"));
+    expect(blockquote).not.toContain("gitlab-md-toc");
+    expect(html.indexOf("gitlab-md-toc")).toBeLessThan(html.indexOf('<h2 id="real">'));
+  });
+
   it("inline mode: replaces the marker in place when present", async () => {
     const html = await renderMarkdown("## A\n\n[[_TOC_]]\n\n## B\n", { tocMode: "inline" });
     expect(html).toContain('<nav class="gitlab-md-toc">');
diff --git a/src/gitlab/toc.ts b/src/gitlab/toc.ts
index 2cabed4..9faa7e6 100644
--- a/src/gitlab/toc.ts
+++ b/src/gitlab/toc.ts
@@ -1,7 +1,7 @@
 import GithubSlugger from "github-slugger";
 import type { Root, Element, RootContent } from "hast";
 import { toString } from "hast-util-to-string";
-import { visit, EXIT } from "unist-util-visit";
+import { visit } from "unist-util-visit";
 
 /**
  * Token we substitute for a standalone `[[_TOC_]]` line BEFORE markdown parsing.
@@ -15,6 +15,16 @@ export type TocMode = "auto" | "inline" | "sidebar" | "hidden";
 
 const HEADING_LEVELS: Record<string, number> = { h2: 2, h3: 3, h4: 4, h5: 5 };
 
+function findFirstHeadingPosition(tree: Root): { parent: Root; index: number } | null {
+  for (let index = 0; index < tree.children.length; index++) {
+    const child = tree.children[index];
+    if (child.type === "element" && HEADING_LEVELS[child.tagName]) {
+      return { parent: tree, index };
+    }
+  }
+  return null;
+}
+
 export interface TocEntry {
   level: number;
   id: string;
@@ -102,18 +112,10 @@ export function rehypeGitlabToc(options: RehypeGitlabTocOptions = {}) {
       return;
     }
 
-    // inline without a marker: insert the nav above the first heading.
+    // inline without a marker: insert the nav above the first top-level heading.
     if (nav) {
-      let firstHeading: { parent: Root | Element; index: number } | null = null;
-      visit(tree, "element", (n: Element, idx, parent) => {
-        if (HEADING_LEVELS[n.tagName] && parent && typeof idx === "number") {
-          firstHeading = { parent: parent as Root | Element, index: idx };
-          return EXIT;
-        }
-        return undefined;
-      });
-      if (firstHeading !== null) {
-        const target: { parent: Root | Element; index: number } = firstHeading;
+      const target = findFirstHeadingPosition(tree);
+      if (target) {
         target.parent.children.splice(target.index, 0, structuredClone(nav) as RootContent);
       }
     }

From 5dc8a6ba5dbb4b02ee52b0a57efab8d662b94b25 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:51:30 +0200
Subject: [PATCH 05/15] feat: fetchReadme reads the toc attribute and returns
 sidebar entries

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/gitlab/fetchers.test.ts | 46 +++++++++++++++++++++++++++++++++++++
 src/gitlab/fetchers.ts      | 20 ++++++++++++++--
 src/gitlab/types.ts         |  3 +++
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/src/gitlab/fetchers.test.ts b/src/gitlab/fetchers.test.ts
index 390e3c4..8692afb 100644
--- a/src/gitlab/fetchers.test.ts
+++ b/src/gitlab/fetchers.test.ts
@@ -117,6 +117,52 @@ describe("fetchReadme", () => {
     expect(client.getProject).not.toHaveBeenCalled();
     expect(client.getFileRaw).toHaveBeenCalledWith("g/r", "README.md", "v2");
   });
+
+  it("sidebar mode returns toc entries and assigns heading ids", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n\n### Steps\n"),
+    };
+    const data = await fetchReadme(ctx(client), { project: "g/r", toc: "sidebar" });
+    expect(data.toc).toEqual([
+      { level: 2, id: "install", text: "Install" },
+      { level: 3, id: "steps", text: "Steps" },
+    ]);
+    expect(data.html).toContain('<h2 id="install">');
+  });
+
+  it("does not attach toc entries when toc is not 'sidebar'", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    const data = await fetchReadme(ctx(client), { project: "g/r", toc: "inline" });
+    expect(data.toc).toBeUndefined();
+    expect(data.html).toContain("gitlab-md-toc");
+  });
+
+  it("rejects an invalid toc value", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    await expect(fetchReadme(ctx(client), { project: "g/r", toc: "left" })).rejects.toThrow(
+      /"toc" must be one of/,
+    );
+  });
+
+  it("keys the cache by toc mode so different modes do not collide", async () => {
+    const client: any = {
+      getProject: vi.fn(async () => ({ default_branch: "main" })),
+      getFileRaw: vi.fn(async () => "## Install\n"),
+    };
+    const c = ctx(client);
+    const sidebar = await fetchReadme(c, { project: "g/r", toc: "sidebar" });
+    const inline = await fetchReadme(c, { project: "g/r", toc: "inline" });
+    expect(sidebar.toc).toBeDefined();
+    expect(inline.toc).toBeUndefined();
+    expect(inline.html).toContain("gitlab-md-toc");
+  });
 });
 
 describe("fetchFile", () => {
diff --git a/src/gitlab/fetchers.ts b/src/gitlab/fetchers.ts
index c20e3fc..b24cf1c 100644
--- a/src/gitlab/fetchers.ts
+++ b/src/gitlab/fetchers.ts
@@ -2,6 +2,7 @@ import type { AssetManager } from "./assets";
 import type { FileCache } from "./cache";
 import type { GitLabClient } from "./client";
 import { renderMarkdown } from "./markdown";
+import type { TocEntry, TocMode } from "./toc";
 import type {
   FileData,
   IssueData,
@@ -92,17 +93,32 @@ export async function fetchIssues(ctx: GitLabContext, attrs: Attrs): Promise<Iss
   });
 }
 
+function readTocMode(value: unknown): TocMode {
+  if (value === undefined) return "auto";
+  if (value === "hidden" || value === "inline" || value === "sidebar") return value;
+  throw new Error(
+    `@ebuildy/docusaurus-plugin-gitlab: <GitlabReadme> "toc" must be one of ` +
+      `"hidden", "inline", "sidebar"; got ${JSON.stringify(value)}.`,
+  );
+}
+
 export async function fetchReadme(ctx: GitLabContext, attrs: Attrs): Promise<ReadmeData> {
   const project = String(attrs.project);
   const explicitRef = attrs.ref as string | undefined;
-  return memo(ctx, `readme:${project}:${explicitRef ?? "default"}`, async () => {
+  const tocMode = readTocMode(attrs.toc);
+  return memo(ctx, `readme:${project}:${explicitRef ?? "default"}:${tocMode}`, async () => {
     const ref =
       explicitRef ?? (await ctx.client.getProject(attrs.project as string | number)).default_branch;
     const md = await ctx.client.getFileRaw(attrs.project as string | number, "README.md", ref);
+    const collectToc: TocEntry[] = [];
     const html = await renderMarkdown(md, {
+      tocMode,
+      collectToc,
       transformImageSrc: (src) => ctx.assets.localize(src, ref, project),
     });
-    return { ref, html } satisfies ReadmeData;
+    const result: ReadmeData = { ref, html };
+    if (tocMode === "sidebar") result.toc = collectToc;
+    return result;
   });
 }
 
diff --git a/src/gitlab/types.ts b/src/gitlab/types.ts
index a977fd7..fdbcd99 100644
--- a/src/gitlab/types.ts
+++ b/src/gitlab/types.ts
@@ -1,3 +1,5 @@
+import type { TocEntry } from "./toc.js";
+
 export type ProjectRef = string | number;
 
 export interface ProjectInfoData {
@@ -41,6 +43,7 @@ export interface IssueData {
 export interface ReadmeData {
   ref: string;
   html: string;
+  toc?: TocEntry[];
 }
 
 export interface FileMarkdownData {

From d39ac8d7ed9c331fa334a66a52a49a98bbdc758c Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:56:20 +0200
Subject: [PATCH 06/15] refactor: align toc import extension and tighten
 cache-key test

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/gitlab/fetchers.test.ts | 1 +
 src/gitlab/fetchers.ts      | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/gitlab/fetchers.test.ts b/src/gitlab/fetchers.test.ts
index 8692afb..d6a9a66 100644
--- a/src/gitlab/fetchers.test.ts
+++ b/src/gitlab/fetchers.test.ts
@@ -162,6 +162,7 @@ describe("fetchReadme", () => {
     expect(sidebar.toc).toBeDefined();
     expect(inline.toc).toBeUndefined();
     expect(inline.html).toContain("gitlab-md-toc");
+    expect(client.getFileRaw).toHaveBeenCalledTimes(2);
   });
 });
 
diff --git a/src/gitlab/fetchers.ts b/src/gitlab/fetchers.ts
index b24cf1c..8a43658 100644
--- a/src/gitlab/fetchers.ts
+++ b/src/gitlab/fetchers.ts
@@ -2,7 +2,7 @@ import type { AssetManager } from "./assets";
 import type { FileCache } from "./cache";
 import type { GitLabClient } from "./client";
 import { renderMarkdown } from "./markdown";
-import type { TocEntry, TocMode } from "./toc";
+import type { TocEntry, TocMode } from "./toc.js";
 import type {
   FileData,
   IssueData,

From 89985144a15967b0f2d8a683586c31fd19c79e71 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 18:57:53 +0200
Subject: [PATCH 07/15] feat: pure TOC-item nesting and merge helpers

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/remark/toc-merge.test.ts | 55 +++++++++++++++++++++++++++++
 src/remark/toc-merge.ts      | 67 ++++++++++++++++++++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 src/remark/toc-merge.test.ts
 create mode 100644 src/remark/toc-merge.ts

diff --git a/src/remark/toc-merge.test.ts b/src/remark/toc-merge.test.ts
new file mode 100644
index 0000000..c11af33
--- /dev/null
+++ b/src/remark/toc-merge.test.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { buildTocItems, insertReadmeToc, type TocItem } from "./toc-merge";
+
+describe("buildTocItems", () => {
+  it("returns [] for no entries", () => {
+    expect(buildTocItems([])).toEqual([]);
+  });
+
+  it("nests deeper headings under the preceding shallower one", () => {
+    const items = buildTocItems([
+      { level: 2, id: "a", text: "A" },
+      { level: 3, id: "b", text: "B" },
+      { level: 2, id: "c", text: "C" },
+    ]);
+    expect(items).toEqual([
+      { value: "A", id: "a", level: 2, children: [{ value: "B", id: "b", level: 3, children: [] }] },
+      { value: "C", id: "c", level: 2, children: [] },
+    ]);
+  });
+});
+
+describe("insertReadmeToc", () => {
+  const page: TocItem[] = [
+    { value: "Intro", id: "intro", level: 2, children: [] },
+    { value: "Outro", id: "outro", level: 2, children: [] },
+  ];
+  const readme: TocItem[] = [{ value: "Install", id: "install", level: 2, children: [] }];
+
+  it("prepends README items when there is no preceding heading", () => {
+    const out = insertReadmeToc(page, null, readme);
+    expect(out.map((i) => i.id)).toEqual(["install", "intro", "outro"]);
+  });
+
+  it("inserts README items right after the preceding sibling heading", () => {
+    const out = insertReadmeToc(page, "intro", readme);
+    expect(out.map((i) => i.id)).toEqual(["intro", "install", "outro"]);
+  });
+
+  it("nests README items under the preceding heading when README is deeper", () => {
+    const out = insertReadmeToc(page, "intro", [
+      { value: "Deep", id: "deep", level: 3, children: [] },
+    ]);
+    expect(out[0].children.map((c) => c.id)).toEqual(["deep"]);
+  });
+
+  it("appends at root when the preceding id is not found", () => {
+    const out = insertReadmeToc(page, "missing", readme);
+    expect(out.map((i) => i.id)).toEqual(["intro", "outro", "install"]);
+  });
+
+  it("does not mutate the input array", () => {
+    insertReadmeToc(page, "intro", readme);
+    expect(page.map((i) => i.id)).toEqual(["intro", "outro"]);
+  });
+});
diff --git a/src/remark/toc-merge.ts b/src/remark/toc-merge.ts
new file mode 100644
index 0000000..26973a5
--- /dev/null
+++ b/src/remark/toc-merge.ts
@@ -0,0 +1,67 @@
+import type { TocEntry } from "../gitlab/toc.js";
+
+/** A single right-sidebar TOC entry, matching Docusaurus' `toc` export shape. */
+export interface TocItem {
+  value: string;
+  id: string;
+  level: number;
+  children: TocItem[];
+}
+
+/** Nest flat heading entries into a level-based tree (README's own min level = root). */
+export function buildTocItems(entries: TocEntry[]): TocItem[] {
+  if (entries.length === 0) return [];
+  const root: TocItem[] = [];
+  const minLevel = Math.min(...entries.map((e) => e.level));
+  const stack: { level: number; list: TocItem[] }[] = [{ level: minLevel, list: root }];
+  for (const entry of entries) {
+    const item: TocItem = { value: entry.text, id: entry.id, level: entry.level, children: [] };
+    while (stack.length > 1 && stack[stack.length - 1].level > entry.level) stack.pop();
+    let top = stack[stack.length - 1];
+    if (entry.level > top.level) {
+      const last = top.list[top.list.length - 1];
+      const childList = last ? last.children : top.list;
+      stack.push({ level: entry.level, list: childList });
+      top = stack[stack.length - 1];
+    }
+    top.list.push(item);
+  }
+  return root;
+}
+
+/**
+ * Insert `readmeItems` into a copy of `items` at the position following the
+ * page heading with id `precedingId`:
+ *  - precedingId === null  → prepend (component sits before all page headings)
+ *  - README is deeper than the preceding heading → nest under it
+ *  - otherwise → insert as following siblings
+ *  - preceding id not found → append at root
+ * Pure: never mutates the inputs.
+ */
+export function insertReadmeToc(
+  items: TocItem[],
+  precedingId: string | null,
+  readmeItems: TocItem[],
+): TocItem[] {
+  if (readmeItems.length === 0) return items;
+  const block = structuredClone(readmeItems);
+  if (precedingId === null) return [...block, ...structuredClone(items)];
+
+  const copy = structuredClone(items);
+  const readmeMinLevel = Math.min(...readmeItems.map((i) => i.level));
+
+  const recur = (list: TocItem[]): boolean => {
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].id === precedingId) {
+        if (readmeMinLevel > list[i].level) list[i].children.push(...block);
+        else list.splice(i + 1, 0, ...block);
+        return true;
+      }
+      if (recur(list[i].children)) return true;
+    }
+    return false;
+  };
+
+  if (!recur(copy)) return [...copy, ...block];
+  return copy;
+}

From fc4424cbb675028d00dbfe834e1d20bea688a099 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:02:55 +0200
Subject: [PATCH 08/15] feat: estree bridge to merge README headings into the
 page toc export

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/remark/toc-export.test.ts | 100 +++++++++++++++++++++++++++
 src/remark/toc-export.ts      | 123 ++++++++++++++++++++++++++++++++++
 2 files changed, 223 insertions(+)
 create mode 100644 src/remark/toc-export.test.ts
 create mode 100644 src/remark/toc-export.ts

diff --git a/src/remark/toc-export.test.ts b/src/remark/toc-export.test.ts
new file mode 100644
index 0000000..ccbf561
--- /dev/null
+++ b/src/remark/toc-export.test.ts
@@ -0,0 +1,100 @@
+import { valueToEstree } from "estree-util-value-to-estree";
+import { describe, it, expect } from "vitest";
+import {
+  findTocExport,
+  makeTocExportNode,
+  precedingHeadingId,
+  readTocItems,
+  writeTocItems,
+  TocSliceError,
+  mergeReadmeTocs,
+} from "./toc-export";
+import type { TocItem } from "./toc-merge";
+
+const items: TocItem[] = [
+  { value: "Intro", id: "intro", level: 2, children: [{ value: "Sub", id: "sub", level: 3, children: [] }] },
+];
+
+describe("readTocItems / writeTocItems", () => {
+  it("round-trips toc items through estree", () => {
+    expect(readTocItems(writeTocItems(items))).toEqual(items);
+  });
+
+  it("throws TocSliceError on a spread element (TOC slice)", () => {
+    const arr = { type: "ArrayExpression", elements: [{ type: "SpreadElement" }] };
+    expect(() => readTocItems(arr)).toThrow(TocSliceError);
+  });
+});
+
+describe("findTocExport / makeTocExportNode", () => {
+  it("creates and then finds a toc export node", () => {
+    const node = makeTocExportNode(items);
+    const tree = { type: "root", children: [node] };
+    const found = findTocExport(tree);
+    expect(found).not.toBeNull();
+    expect(readTocItems(found!.declarator.init)).toEqual(items);
+  });
+
+  it("returns null when there is no toc export", () => {
+    expect(findTocExport({ type: "root", children: [] })).toBeNull();
+  });
+});
+
+describe("precedingHeadingId", () => {
+  it("returns the id of the heading immediately before the target node", () => {
+    const target = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = {
+      type: "root",
+      children: [
+        { type: "heading", data: { id: "first", hProperties: { id: "first" } } },
+        { type: "paragraph" },
+        target,
+        { type: "heading", data: { id: "later", hProperties: { id: "later" } } },
+      ],
+    };
+    expect(precedingHeadingId(tree, target)).toBe("first");
+  });
+
+  it("returns null when no heading precedes the target", () => {
+    const target = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = { type: "root", children: [target] };
+    expect(precedingHeadingId(tree, target)).toBeNull();
+  });
+});
+
+describe("mergeReadmeTocs", () => {
+  it("merges README entries into the existing toc export at the component position", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tocNode = makeTocExportNode([{ value: "Intro", id: "intro", level: 2, children: [] }]);
+    const tree = {
+      type: "root",
+      children: [
+        tocNode,
+        { type: "heading", data: { id: "intro", hProperties: { id: "intro" } } },
+        readmeNode,
+      ],
+    };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i) => i.id)).toEqual(["intro", "install"]);
+  });
+
+  it("creates a toc export when none exists", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tree = { type: "root", children: [readmeNode] };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i) => i.id)).toEqual(["install"]);
+  });
+
+  it("leaves the export untouched when it contains a TOC slice", () => {
+    const readmeNode = { type: "mdxJsxFlowElement", name: "GitlabReadme" };
+    const tocNode = makeTocExportNode([]);
+    tocNode.data.estree.body[0].declaration.declarations[0].init = valueToEstree([]);
+    tocNode.data.estree.body[0].declaration.declarations[0].init.elements = [{ type: "SpreadElement" }];
+    const tree = { type: "root", children: [tocNode, readmeNode] };
+    mergeReadmeTocs(tree, [{ node: readmeNode, entries: [{ level: 2, id: "install", text: "Install" }] }]);
+    const found = findTocExport(tree)!;
+    expect(found.declarator.init.elements).toEqual([{ type: "SpreadElement" }]);
+  });
+});
diff --git a/src/remark/toc-export.ts b/src/remark/toc-export.ts
new file mode 100644
index 0000000..ea35d5f
--- /dev/null
+++ b/src/remark/toc-export.ts
@@ -0,0 +1,123 @@
+import { valueToEstree } from "estree-util-value-to-estree";
+import { visit, EXIT } from "unist-util-visit";
+import type { TocEntry } from "../gitlab/toc.js";
+import { buildTocItems, insertReadmeToc, type TocItem } from "./toc-merge.js";
+
+/** Thrown when the page `toc` export contains a TOC slice (spread) we can't round-trip. */
+export class TocSliceError extends Error {}
+
+/** Find the `export const toc = [...]` mdxjsEsm node Docusaurus generated. */
+export function findTocExport(tree: any): { node: any; declarator: any } | null {
+  for (const child of tree.children ?? []) {
+    if (child.type !== "mdxjsEsm") continue;
+    const body = child.data?.estree?.body ?? [];
+    for (const stmt of body) {
+      if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "VariableDeclaration") {
+        for (const d of stmt.declaration.declarations) {
+          if (d.id?.type === "Identifier" && d.id.name === "toc" && d.init?.type === "ArrayExpression") {
+            return { node: child, declarator: d };
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/** Read an estree ArrayExpression of toc items back into plain TocItem objects. */
+export function readTocItems(arrayExpr: any): TocItem[] {
+  return (arrayExpr.elements ?? []).map(readItem);
+}
+
+function readItem(el: any): TocItem {
+  if (!el || el.type !== "ObjectExpression") throw new TocSliceError();
+  const item: TocItem = { value: "", id: "", level: 0, children: [] };
+  for (const prop of el.properties) {
+    if (prop.type !== "Property") throw new TocSliceError();
+    const key = prop.key.type === "Identifier" ? prop.key.name : prop.key.value;
+    if (key === "value") item.value = String(prop.value.value);
+    else if (key === "id") item.id = String(prop.value.value);
+    else if (key === "level") item.level = Number(prop.value.value);
+    else if (key === "children") item.children = (prop.value.elements ?? []).map(readItem);
+  }
+  return item;
+}
+
+/** Serialize TocItem objects to an estree ArrayExpression. */
+export function writeTocItems(items: TocItem[]): any {
+  return valueToEstree(items, { preserveReferences: false });
+}
+
+/** Build a fresh `export const toc = [...]` mdxjsEsm node. */
+export function makeTocExportNode(items: TocItem[]): any {
+  const estree = {
+    type: "Program",
+    sourceType: "module",
+    body: [
+      {
+        type: "ExportNamedDeclaration",
+        specifiers: [],
+        source: null,
+        declaration: {
+          type: "VariableDeclaration",
+          kind: "const",
+          declarations: [
+            {
+              type: "VariableDeclarator",
+              id: { type: "Identifier", name: "toc" },
+              init: writeTocItems(items),
+            },
+          ],
+        },
+      },
+    ],
+  };
+  return { type: "mdxjsEsm", value: "", data: { estree } };
+}
+
+/** Id of the page heading immediately preceding `target` in document order, or null. */
+export function precedingHeadingId(tree: any, target: any): string | null {
+  let last: string | null = null;
+  visit(tree, (node: any) => {
+    if (node === target) return EXIT;
+    if (node.type === "heading") {
+      const id = node.data?.id ?? node.data?.hProperties?.id;
+      if (typeof id === "string") last = id;
+    }
+    return undefined;
+  });
+  return last;
+}
+
+/**
+ * Merge each sidebar README's headings into the page's `toc` export, in document
+ * order. Creates the export if absent. If the export contains a TOC slice
+ * (unsupported edge case), leaves it untouched.
+ */
+export function mergeReadmeTocs(
+  tree: any,
+  readmes: { node: any; entries: TocEntry[] }[],
+): void {
+  if (readmes.length === 0) return;
+
+  let target = findTocExport(tree);
+  if (!target) {
+    tree.children.push(makeTocExportNode([]));
+    target = findTocExport(tree)!;
+  }
+
+  let items: TocItem[];
+  try {
+    items = readTocItems(target.declarator.init);
+  } catch (err) {
+    if (err instanceof TocSliceError) return; // page uses TOC slices: unsupported
+    throw err;
+  }
+
+  for (const { node, entries } of readmes) {
+    const precedingId = precedingHeadingId(tree, node);
+    items = insertReadmeToc(items, precedingId, buildTocItems(entries));
+  }
+
+  target.declarator.init = writeTocItems(items);
+}

From bdd16a6cefb115ee06da16a2a82f1c7808d8de53 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:06:24 +0200
Subject: [PATCH 09/15] refactor: bail out of toc round-trip on non-literal
 property values

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/remark/toc-export.test.ts | 15 +++++++++++++++
 src/remark/toc-export.ts      | 12 ++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/remark/toc-export.test.ts b/src/remark/toc-export.test.ts
index ccbf561..ea6e8bb 100644
--- a/src/remark/toc-export.test.ts
+++ b/src/remark/toc-export.test.ts
@@ -24,6 +24,21 @@ describe("readTocItems / writeTocItems", () => {
     const arr = { type: "ArrayExpression", elements: [{ type: "SpreadElement" }] };
     expect(() => readTocItems(arr)).toThrow(TocSliceError);
   });
+
+  it("throws TocSliceError when a property value is not a literal", () => {
+    const arr = {
+      type: "ArrayExpression",
+      elements: [
+        {
+          type: "ObjectExpression",
+          properties: [
+            { type: "Property", key: { type: "Literal", value: "id" }, value: { type: "Identifier", name: "x" } },
+          ],
+        },
+      ],
+    };
+    expect(() => readTocItems(arr)).toThrow(TocSliceError);
+  });
 });
 
 describe("findTocExport / makeTocExportNode", () => {
diff --git a/src/remark/toc-export.ts b/src/remark/toc-export.ts
index ea35d5f..067d861 100644
--- a/src/remark/toc-export.ts
+++ b/src/remark/toc-export.ts
@@ -35,10 +35,14 @@ function readItem(el: any): TocItem {
   for (const prop of el.properties) {
     if (prop.type !== "Property") throw new TocSliceError();
     const key = prop.key.type === "Identifier" ? prop.key.name : prop.key.value;
-    if (key === "value") item.value = String(prop.value.value);
-    else if (key === "id") item.id = String(prop.value.value);
-    else if (key === "level") item.level = Number(prop.value.value);
-    else if (key === "children") item.children = (prop.value.elements ?? []).map(readItem);
+    if (key === "children") {
+      item.children = (prop.value.elements ?? []).map(readItem);
+    } else if (key === "value" || key === "id" || key === "level") {
+      if (prop.value.type !== "Literal") throw new TocSliceError();
+      if (key === "value") item.value = String(prop.value.value);
+      else if (key === "id") item.id = String(prop.value.value);
+      else item.level = Number(prop.value.value);
+    }
   }
   return item;
 }

From 485bc1e6907df993a7496945d7d004593511eb1f Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:08:05 +0200
Subject: [PATCH 10/15] feat: merge sidebar README headings into the page toc
 during transform

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/remark/index.test.ts | 31 +++++++++++++++++++++++++++++++
 src/remark/index.ts      |  8 ++++++++
 2 files changed, 39 insertions(+)

diff --git a/src/remark/index.test.ts b/src/remark/index.test.ts
index 0754583..afa4ee9 100644
--- a/src/remark/index.test.ts
+++ b/src/remark/index.test.ts
@@ -2,6 +2,7 @@ import remarkMdx from "remark-mdx";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { describe, it, expect, vi } from "vitest";
+import { findTocExport, readTocItems } from "./toc-export";
 import remarkGitlab from "./index";
 
 vi.mock("../gitlab/fetchers.js", () => ({
@@ -57,4 +58,34 @@ describe("remarkGitlab", () => {
     const errAttr = node.attributes.find((a: any) => a.name === "error");
     expect(errAttr.value.value).toContain("api down");
   });
+
+  it("merges sidebar README headings into the page toc export", async () => {
+    const { fetchReadme } = await import("../gitlab/fetchers.js");
+    (fetchReadme as any).mockResolvedValue({
+      ref: "main",
+      html: '<h2 id="install">Install</h2>',
+      toc: [{ level: 2, id: "install", text: "Install" }],
+    });
+    const src = [
+      'export const toc = [{ value: "Intro", id: "intro", level: 2, children: [] }];',
+      "",
+      '<GitlabReadme project="g/r" toc="sidebar" />',
+    ].join("\n");
+    const tree = await transform(src, { host: "https://gitlab.com", strict: true });
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i: any) => i.id)).toContain("install");
+  });
+
+  it("does not touch the toc export for non-sidebar readmes", async () => {
+    const { fetchReadme } = await import("../gitlab/fetchers.js");
+    (fetchReadme as any).mockResolvedValue({ ref: "main", html: "<p>x</p>" });
+    const src = [
+      'export const toc = [{ value: "Intro", id: "intro", level: 2, children: [] }];',
+      "",
+      '<GitlabReadme project="g/r" toc="inline" />',
+    ].join("\n");
+    const tree = await transform(src, { host: "https://gitlab.com", strict: true });
+    const found = findTocExport(tree)!;
+    expect(readTocItems(found.declarator.init).map((i: any) => i.id)).toEqual(["intro"]);
+  });
 });
diff --git a/src/remark/index.ts b/src/remark/index.ts
index 00797b9..36d92a9 100644
--- a/src/remark/index.ts
+++ b/src/remark/index.ts
@@ -7,6 +7,7 @@ import { resolveOptions, type PluginOptions } from "../options.js";
 import { parseAttributes } from "./attributes.js";
 import { injectProp } from "./inject.js";
 import { COMPONENT_REGISTRY } from "./registry.js";
+import { mergeReadmeTocs } from "./toc-export.js";
 
 const CACHE_DIR = "node_modules/.cache/@ebuildy/docusaurus-plugin-gitlab";
 
@@ -40,6 +41,8 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
       }
     });
 
+    const sidebarReadmes: { node: any; entries: any[] }[] = [];
+
     await Promise.all(
       jobs.map(async ({ node }) => {
         const fetcher = COMPONENT_REGISTRY[node.name];
@@ -48,6 +51,9 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
         try {
           const data = await fetcher(ctx, attrs);
           injectProp(node, "data", data);
+          if (node.name === "GitlabReadme" && Array.isArray((data as any)?.toc)) {
+            sidebarReadmes.push({ node, entries: (data as any).toc });
+          }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           const where = node.position?.start
@@ -60,5 +66,7 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
         }
       }),
     );
+
+    mergeReadmeTocs(tree, sidebarReadmes);
   };
 }

From f39d3b192b483e6a7b6c36deefb519fdcd794a53 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:11:56 +0200
Subject: [PATCH 11/15] refactor: merge sidebar README TOCs in deterministic
 document order

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 src/remark/index.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/remark/index.ts b/src/remark/index.ts
index 36d92a9..7f0ee9a 100644
--- a/src/remark/index.ts
+++ b/src/remark/index.ts
@@ -41,10 +41,10 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
       }
     });
 
-    const sidebarReadmes: { node: any; entries: any[] }[] = [];
+    const sidebarReadmes: { node: any; entries: any[]; order: number }[] = [];
 
     await Promise.all(
-      jobs.map(async ({ node }) => {
+      jobs.map(async ({ node }, order) => {
         const fetcher = COMPONENT_REGISTRY[node.name];
         const filePath = file?.path ?? "unknown.mdx";
         const attrs = parseAttributes(node.attributes ?? [], filePath);
@@ -52,7 +52,7 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
           const data = await fetcher(ctx, attrs);
           injectProp(node, "data", data);
           if (node.name === "GitlabReadme" && Array.isArray((data as any)?.toc)) {
-            sidebarReadmes.push({ node, entries: (data as any).toc });
+            sidebarReadmes.push({ node, entries: (data as any).toc, order });
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
@@ -67,6 +67,9 @@ export default function remarkGitlab(rawOptions: PluginOptions) {
       }),
     );
 
+    // Feed READMEs to the merge in document order, not fetch-completion order,
+    // so the merged sidebar TOC is deterministic across builds.
+    sidebarReadmes.sort((a, b) => a.order - b.order);
     mergeReadmeTocs(tree, sidebarReadmes);
   };
 }

From 11bf44dc442c2f9c230baa962c27726eba840dbc Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:19:02 +0200
Subject: [PATCH 12/15] test: e2e coverage for GitlabReadme toc=sidebar

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 examples/site/docs/intro.mdx |  2 +-
 test/e2e/build.test.ts       | 11 +++++++++++
 test/e2e/fixtures.ts         |  5 ++++-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/examples/site/docs/intro.mdx b/examples/site/docs/intro.mdx
index a63395e..92a382f 100644
--- a/examples/site/docs/intro.mdx
+++ b/examples/site/docs/intro.mdx
@@ -6,7 +6,7 @@ slug: /
 
 <GitlabProjectInfo project="group/repo" />
 
-<GitlabReadme project="group/repo" />
+<GitlabReadme project="group/repo" toc="sidebar" />
 
 <GitlabReleases project="group/repo" limit={3} />
 
diff --git a/test/e2e/build.test.ts b/test/e2e/build.test.ts
index 7e2a5d1..e7b0212 100644
--- a/test/e2e/build.test.ts
+++ b/test/e2e/build.test.ts
@@ -60,4 +60,15 @@ describe("e2e: docusaurus build", () => {
     const html = readFileSync(join(siteDir, "build", "index.html"), "utf8");
     expect(html).toContain("/gitlab-assets/");
   });
+
+  it("merges sidebar README headings into the page's right-hand TOC", () => {
+    const html = readFileSync(join(siteDir, "build", "index.html"), "utf8");
+    // README headings appear as Docusaurus TOC links, not as an inline gitlab nav.
+    expect(html).toContain("table-of-contents");
+    expect(html).toContain('href="#install"');
+    expect(html).toContain('href="#usage"');
+    expect(html).not.toContain("gitlab-md-toc");
+    // README heading ids are present in the rendered body for the anchors to resolve.
+    expect(html).toContain('id="install"');
+  });
 });
diff --git a/test/e2e/fixtures.ts b/test/e2e/fixtures.ts
index 5fc38bb..59ec184 100644
--- a/test/e2e/fixtures.ts
+++ b/test/e2e/fixtures.ts
@@ -38,7 +38,10 @@ export async function startGitlabStub(): Promise<{ url: string; stop: () => Prom
       ]);
     }
     if (url.includes("/repository/files/README.md/raw")) {
-      return send("# Hello\n\nReadme body.\n\n![logo](./logo.png)", "text/plain");
+      return send(
+        "# Hello\n\nReadme body.\n\n## Install\n\nsetup\n\n## Usage\n\ngo\n\n![logo](./logo.png)",
+        "text/plain",
+      );
     }
     if (url.startsWith("/api/v4/projects/group%2Frepo")) {
       return send({

From 70dac6ec71c99f9b7cd0fbf59fff78602deea26f Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 19:23:17 +0200
Subject: [PATCH 13/15] docs: document the GitlabReadme toc attribute

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 README.md                                | 17 ++++++++++++++++-
 examples/site/docs/components/readme.mdx | 23 +++++++++++++++++++++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8704b9a..5dfa6e3 100644
--- a/README.md
+++ b/README.md
@@ -111,11 +111,26 @@ localized; links resolve back to GitLab.
 |---|---|---|---|
 | `project` | string \| number | — | **Required.** |
 | `ref` | string | default branch | Branch, tag, or commit SHA |
+| `toc` | `"hidden" \| "inline" \| "sidebar"` | _auto_ | Where to render the table of contents |
 
 > **Table of contents:** if the README contains a GitLab `[[_TOC_]]` marker on its
 > own line, it is replaced at build time with a generated table of contents linking
 > to the document's `h2`–`h5` headings (which receive slug `id`s). This also works
-> for markdown embedded via `<GitlabFile>` and for release notes.
+> for markdown embedded via `<GitlabFile>` and for release notes. The `toc` prop
+> overrides this default: `toc="inline"` always renders the inline TOC (even without
+> a marker); `toc="sidebar"` renders the README's headings in the page's native
+> right-hand sidebar instead (merged with the page's own headings) and suppresses
+> the inline TOC; `toc="hidden"` renders no TOC and strips any marker. Omitting `toc`
+> keeps today's marker-driven behavior.
+>
+> ```mdx
+> <GitlabReadme project="group/repo" toc="sidebar" />
+> ```
+>
+> Note: in `sidebar` mode the README is injected as pre-rendered HTML, so
+> Docusaurus' broken-anchor checker can't see its heading anchors — harmless at the
+> default `onBrokenAnchors: "warn"` (build succeeds, links work), but would fail a
+> build configured with `onBrokenAnchors: "throw"`.
 
 <!-- -->
 
diff --git a/examples/site/docs/components/readme.mdx b/examples/site/docs/components/readme.mdx
index 620e435..76cb420 100644
--- a/examples/site/docs/components/readme.mdx
+++ b/examples/site/docs/components/readme.mdx
@@ -23,6 +23,7 @@ frozen at build time); links resolve back to GitLab.
 |---|---|---|---|
 | `project` | `string \| number` | — | **Required.** Project path or numeric ID. |
 | `ref` | `string` | default branch | Branch, tag, or commit SHA to read the README from. |
+| `toc` | `"hidden" \| "inline" \| "sidebar"` | _auto_ | Where to render the table of contents. Omitted = today's behavior (inline only if the README has a `[[_TOC_]]` marker). |
 
 ## Notes
 
@@ -33,5 +34,23 @@ frozen at build time); links resolve back to GitLab.
 
 ## Table of contents
 
-A `[[_TOC_]]` marker in the README is expanded into a real table of contents
-linking to the project's headings.
+By default a `[[_TOC_]]` marker in the README is expanded into an inline table of
+contents linking to the project's headings. The `toc` prop overrides this:
+
+- `toc="inline"` — always render the inline TOC, even without a `[[_TOC_]]` marker.
+- `toc="sidebar"` — render the README's headings in the page's right-hand sidebar,
+  like a normal Docusaurus page (merged with the page's own headings in document
+  order). No inline TOC is rendered.
+- `toc="hidden"` — never render a TOC; any `[[_TOC_]]` marker is stripped.
+
+```mdx
+<GitlabReadme project="group/repo" toc="sidebar" />
+```
+
+:::note Sidebar mode and broken-anchor checks
+In `sidebar` mode the README is injected as pre-rendered HTML, so Docusaurus'
+built-in anchor checker can't see the README's heading anchors. With the default
+`onBrokenAnchors: "warn"` the build still succeeds and the links work; if your site
+sets `onBrokenAnchors: "throw"`, use `inline` or `hidden` mode instead, or relax the
+setting.
+:::

From 2e4ec517f30dac7705f8510bf0aa519cfee98edc Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 23:17:13 +0200
Subject: [PATCH 14/15] test: e2e coverage for document-order sidebar TOC
 interleaving

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 examples/site/docs/intro.mdx | 4 ++++
 test/e2e/build.test.ts       | 9 +++++++++
 2 files changed, 13 insertions(+)

diff --git a/examples/site/docs/intro.mdx b/examples/site/docs/intro.mdx
index 92a382f..90d01c5 100644
--- a/examples/site/docs/intro.mdx
+++ b/examples/site/docs/intro.mdx
@@ -6,6 +6,10 @@ slug: /
 
 <GitlabProjectInfo project="group/repo" />
 
+## Overview
+
+Some intro text.
+
 <GitlabReadme project="group/repo" toc="sidebar" />
 
 <GitlabReleases project="group/repo" limit={3} />
diff --git a/test/e2e/build.test.ts b/test/e2e/build.test.ts
index e7b0212..b018e3e 100644
--- a/test/e2e/build.test.ts
+++ b/test/e2e/build.test.ts
@@ -71,4 +71,13 @@ describe("e2e: docusaurus build", () => {
     // README heading ids are present in the rendered body for the anchors to resolve.
     expect(html).toContain('id="install"');
   });
+
+  it("interleaves sidebar README headings after the page's own heading in document order", () => {
+    const html = readFileSync(join(siteDir, "build", "index.html"), "utf8");
+    // The page's own heading and the README headings all appear in the right-hand TOC...
+    expect(html).toContain('href="#overview"');
+    expect(html).toContain('href="#install"');
+    // ...and the README headings come AFTER the page heading that precedes the component.
+    expect(html.indexOf('href="#overview"')).toBeLessThan(html.indexOf('href="#install"'));
+  });
 });

From 3307164455858fd6aa2864bbf29d339c4404a4a9 Mon Sep 17 00:00:00 2001
From: Thomas Decaux <ebuildy@gmail.com>
Date: Mon, 29 Jun 2026 23:19:31 +0200
Subject: [PATCH 15/15] chore: example

Signed-off-by: Thomas Decaux <ebuildy@gmail.com>
---
 CLAUDE.md                            | 13 +++++++++++
 examples/gitlab/docs/ai.mdx          |  3 +++
 examples/gitlab/docs/demo.mdx        |  1 +
 examples/gitlab/docusaurus.config.ts |  1 +
 examples/gitlab/package-lock.json    | 35 ++++++++++++++++++++++++----
 examples/gitlab/package.json         |  3 ++-
 6 files changed, 51 insertions(+), 5 deletions(-)
 create mode 100644 examples/gitlab/docs/ai.mdx
 create mode 100644 examples/gitlab/docs/demo.mdx

diff --git a/CLAUDE.md b/CLAUDE.md
index bbe231e..22e1793 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,6 +25,8 @@ static HTML. The browser never holds a token or calls the GitLab API.
   `moduleResolution: "Bundler"` / ESM setup. Match this in new files.
 - Keep components **pure**: they receive a `data` or `error` prop and render —
   no fetching, no hooks, no side effects.
+- When using a library or external softwre, always check the last version and
+  if the project has not been abandonned
 
 ## Commands
 
@@ -115,3 +117,14 @@ docusaurus build
   fetchers use mocked gitbeaker / fake clients; cache and assets use real temp
   dirs). Do not add MSW.
 - The design spec and implementation plan live in `docs/superpowers/`.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
diff --git a/examples/gitlab/docs/ai.mdx b/examples/gitlab/docs/ai.mdx
new file mode 100644
index 0000000..01c56b8
--- /dev/null
+++ b/examples/gitlab/docs/ai.mdx
@@ -0,0 +1,3 @@
+
+<GitlabReadme project="gitlab-org/ai/skills" />
+
diff --git a/examples/gitlab/docs/demo.mdx b/examples/gitlab/docs/demo.mdx
new file mode 100644
index 0000000..01c8d02
--- /dev/null
+++ b/examples/gitlab/docs/demo.mdx
@@ -0,0 +1 @@
+<GitlabReadme project="ebuildy/demo-docusaurus" toc="sidebar" />
\ No newline at end of file
diff --git a/examples/gitlab/docusaurus.config.ts b/examples/gitlab/docusaurus.config.ts
index ca92d7c..e3a8c59 100644
--- a/examples/gitlab/docusaurus.config.ts
+++ b/examples/gitlab/docusaurus.config.ts
@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import type { Config } from "@docusaurus/types";
 import { remarkGitlab } from "@ebuildy/docusaurus-plugin-gitlab";
+import remarkGemoji from "remark-gemoji";
 
 const require = createRequire(import.meta.url);
 
diff --git a/examples/gitlab/package-lock.json b/examples/gitlab/package-lock.json
index 1ae2308..5022345 100644
--- a/examples/gitlab/package-lock.json
+++ b/examples/gitlab/package-lock.json
@@ -10,7 +10,8 @@
         "@docusaurus/preset-classic": "^3.5.0",
         "@ebuildy/docusaurus-plugin-gitlab": "file:../..",
         "react": "^18.3.0",
-        "react-dom": "^18.3.0"
+        "react-dom": "^18.3.0",
+        "remark-gemoji": "^8.0.0"
       },
       "devDependencies": {
         "@docusaurus/tsconfig": "^3.5.0",
@@ -25,8 +26,10 @@
         "@gitbeaker/core": "^43.8.0",
         "@gitbeaker/rest": "^43.8.0",
         "estree-util-value-to-estree": "^3.1.0",
+        "github-slugger": "^2.0.0",
         "hast-util-from-html": "^2.0.0",
         "hast-util-to-html": "^9.0.0",
+        "hast-util-to-string": "^3.0.1",
         "joi": "^17.13.0",
         "prism-react-renderer": "^2.4.1",
         "rehype-raw": "^7.0.0",
@@ -58,17 +61,16 @@
         "husky": "^9.1.7",
         "jsdom": "^29.1.1",
         "lint-staged": "^16.4.0",
-        "markdownlint-cli2": "^0.22.1",
+        "markdownlint-cli2": "^0.12.1",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
         "remark-mdx": "^3.1.1",
-        "tsup": "^8.0.0",
         "typescript": "~6.0.2",
         "typescript-eslint": "^8.62.0",
         "vitest": "^4.1.9"
       },
       "engines": {
-        "node": ">=20"
+        "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
       },
       "peerDependencies": {
         "react": ">=18",
@@ -8977,6 +8979,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/gemoji": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/gemoji/-/gemoji-8.1.0.tgz",
+      "integrity": "sha512-HA4Gx59dw2+tn+UAa7XEV4ufUKI4fH1KgcbenVA9YKSj1QJTT0xh5Mwv5HMFNN3l2OtUe3ZIfuRwSyZS5pLIWw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/gensync": {
       "version": "1.0.0-beta.2",
       "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
@@ -15928,6 +15940,21 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/remark-gemoji": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/remark-gemoji/-/remark-gemoji-8.0.0.tgz",
+      "integrity": "sha512-/fL9rc72FYwFGtOKcT+QeQdx9Q9t5v4N6KLXSDOTEgaedzK85I9judBqB2eqz+g4b0ERMejlwSOuPK+wket6aA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "gemoji": "^8.0.0",
+        "mdast-util-find-and-replace": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remark-gfm": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
diff --git a/examples/gitlab/package.json b/examples/gitlab/package.json
index 3831bc2..4aa6911 100644
--- a/examples/gitlab/package.json
+++ b/examples/gitlab/package.json
@@ -12,7 +12,8 @@
     "@docusaurus/preset-classic": "^3.5.0",
     "@ebuildy/docusaurus-plugin-gitlab": "file:../..",
     "react": "^18.3.0",
-    "react-dom": "^18.3.0"
+    "react-dom": "^18.3.0",
+    "remark-gemoji": "^8.0.0"
   },
   "devDependencies": {
     "@docusaurus/tsconfig": "^3.5.0",