feat(mdx): add MDX support with component embedding, routing, and content indexing

[skafai]

Summary

This PR is the first step toward a complete mdx package (similar to @next/mdx). It fulfills the Markdown support item on the roadmap.

Adds topcoat-mdx, a compile-time MDX pipeline. compile_mdx! reads a .mdx or .md file relative to CARGO_MANIFEST_DIR, parses it with markdown-rs, walks the mdast into view! AST nodes, and emits tokens. Nothing is parsed at runtime.

The crate follows the usual trio layout: topcoat-mdx holds the runtime types (MdxIndexEntry, the mdx_components! macro_rules!), grammar/ holds the parser options and the walker, and macro/ is the proc-macro entry point. The facade gains an mdx module behind an mdx feature that pulls in router, and forwards discover to the macro crate.

Macros

• compile_mdx!(path), or with a leading component registry -- either a braced block or mdx_components! { Callout => path::to::callout }. overrides = { "a" => ... } routes HTML elements through components; wrapper = Path wraps the compiled content in a layout component.
• mdx_page!(route, path, ...) compiles one file and registers it as a page.
• mdx_pages!(dir, prefix = ..., ...) walks a directory, compiles every .mdx and .md file, and registers a handler per file with kebab-cased slugs derived from the path. It also emits a &'static [MdxIndexEntry] const and an mdx_index_{dir}() accessor carrying each file's slug, route path, and frontmatter title, date, excerpt, and tags.

Both page macros submit a PageFn to the link-time inventory behind the discover feature, so Router::builder().discover() mounts them.

Walker

Covers CommonMark plus the GFM extensions (tables, strikethrough, task lists, autolinks). HTML passthrough is disabled, so only MDX JSX tags reach the component path; raw HTML renders as text. Reference links, reference images, and footnotes need the definitions before the nodes that use them, so the walk runs in two passes: one to collect definitions, one to render. Footnotes render as a numbered section at the end with backlinks.

Headings get an id derived from their text, deduplicated with -1/-2 suffixes. Fenced code block meta strings become data-lang, data-lines, data-title, and data-emphasis attributes. Overridable elements are a, h1--h6, img, pre, and hr. Link and image URLs are checked before an override component sees them: all data: URIs are rejected and C0 control characters are stripped, so neither can smuggle a scheme past the check.

Changes outside topcoat-mdx

The walker builds view! AST nodes programmatically, which needs a few additions in topcoat-view/grammar: Default on Attributes and ViewWriter; Nodes::new(); and ViewWriter made pub rather than pub(crate). #[must_use] on the constructors. No change to parsing or to the code view! generates.

topcoat-core/grammar gains a topcoat_mdx path helper so generated code can reach the crate through the facade or standalone.

Examples

Eight, under examples/mdx/:

• simple -- two pages, compile_mdx!, manual registration.
• components -- component embedding: props, children, self-closing tags, nesting.
• overrides -- element overrides and wrapper =, serving the same file with and without overrides for comparison.
• gfm -- tables, task lists, footnotes, and code block meta driving a highlighting component through a pre override.
• blog -- mdx_pages! over a nested posts/ directory alongside module_router!, with a listing built from the index.
• content-index -- listing, tag pages, and a sitemap driven entirely by mdx_index_*.
• mdx-pages -- directory scan plus .discover() end to end.
• docs-site -- footnotes, reference links, overrides, wrappers, code meta, and heading IDs on dedicated pages.

Testing

• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
• cargo test --workspace --all-features
• RUSTDOCFLAGS="--cfg docsrs -Dwarnings" cargo +nightly doc --workspace --all-features --no-deps --locked
• cargo +nightly fmt --all and cargo topcoat fmt

Building the three new examples surfaced three defects that are fixed here with regression tests: mdx_pages! emitted &"a", "b" for frontmatter tags rather than &["a", "b"], so any tagged file failed to compile; WalkContext was constructed without its collected definitions in the file-compiling path, so reference links and footnotes silently degraded there while passing in the string-based tests; and malformed frontmatter panicked the proc macro instead of reporting a spanned syn::Error.

Disclaimer

This work was done with coding assistance from Claude (Opus 5) under human supervision. The design, the requirements, and the review of every change are the author's; the model assisted with writing code, tests, docs, and examples, and drafted this description.