It would be nice to render the slugified id attributes to custom heading nodes, to enable anchor links on the generated pages.

I have tried to achieve this using [email protected] but haven't yet found a way to do it without implementing a custom nodes.heading.transform from scratch.

After reviewing the library code and stepping through test cases in the debugger, it seems like the headings are collected, but the ids are never passed to custom heading nodes. This is probably because the collectHeadings() call happens separately from the Markdoc.transform(ast) call, where the actual output to be rendered is determined.

Proposed implementation

We could take inspiration from how @astrojs/markdoc have implemented id slug generation for headings.

First, they generate heading slugs while transforming the Markdoc AST:
https://github.com/withastro/astro/blob/d7d93e19fbfa52cf74dee40f5af6b7ea6a7503d2/packages/integrations/markdoc/src/heading-ids.ts

They then collect all headings later without parsing the AST a second time:
https://github.com/withastro/astro/blob/d7d93e19fbfa52cf74dee40f5af6b7ea6a7503d2/packages/integrations/markdoc/src/runtime.ts#L147

We could use getTextContent() for slugification: https://github.com/withastro/astro/blob/d7d93e19fbfa52cf74dee40f5af6b7ea6a7503d2/packages/integrations/markdoc/src/runtime.ts#L119C1-L132C2

Configuration: Generate ids automatically and let library users opt-in if they want to render them

Astro always generate ids for headings, and render them too.
https://docs.astro.build/en/guides/integrations-guide/markdoc/#custom-headings
They also export their headings node config so it can be partially overwritten to for example use the default id generation, but then use a custom component to render the headings:
https://github.com/withastro/astro/blob/d7d93e19fbfa52cf74dee40f5af6b7ea6a7503d2/packages/integrations/markdoc/src/config.ts#L36

For markdoc-svelte, I think it makes sense to make the default Markdoc configuration output as minimal HTML as possible. We could generate heading ids like Astro does, but I think it's better to let users of markdoc-svelte explicitly opt-in if they want to render the id attributes to their output HTML.

This opt-in could happen by adding a custom heading component that overwrites the default heading tag (a plain h1 html tag).

Status

I'm exploring a potential implementation and might send a PR in the near future.