comark-outline

A table of contents in the body of a page: ::toc becomes a nested list of links to the page's headings. A Comark plugin for HTML, Vue, React, and Svelte.

pnpm add comark comark-outline

import { createHtmlRenderer } from "@comark/html";
import toc, { components } from "comark-outline/html";

const render = createHtmlRenderer({ plugins: [toc()], components });

::toc{depth=3 title="On this page"}
::

::toc lists h2 headings down to depth (default 3), each under the closest heading above it, and links to the ids Comark gives them. [[toc]] isn't read, since Comark parses [[...]] as a span.

toc({ rail: true }) also adds an "On this page" outline beside the text, with a small script that marks the section being read and makes way for wide blocks. The docs give the page variables it reads and sets.

The plugin adds every problem to meta.issues: a depth outside 2 to 6, content inside the block, and a page with no headings to list. Each issue names its block and says how to fix it.

Renderers

| Renderer | Import | | --- | --- | | @comark/html | comark-outline/html: the styles are inlined | | @comark/vue | comark-outline/vue | | @comark/react | comark-outline/react | | @comark/svelte | comark-outline/svelte |

Each entry exports the parse plugin as default and the renderer's components. The Vue, React, and Svelte components add the styles when they mount; import comark-outline/style.css with your styles so a server-rendered page doesn't shift.

The styles follow shadcn/ui: they read its CSS variables, such as --background and --border, when the page has them, and use its neutral theme otherwise. Set the shared --comark-* tokens to theme every plugin at once; the rules sit in a comark CSS layer, so any plain rule of your own wins.