Render Markdown components with MDC

#Context

A documentation theme needs components inside prose — callouts, tabbed code, parameter fields, trees. Two syntaxes were available. MDX compiles Markdown into a component module and lets a page import and write JSX; MDC is the block and inline component syntax Content already ships and parses.

The pages are also read by something other than a browser. The theme publishes each page's Markdown source for models, so whatever syntax the pages are written in is what a model receives.

#Decision

Components in Markdown are MDC. Components callable from a page live in a dedicated content directory, where a consumer's file of the same name replaces the layer's.

#Consequences

Nothing has to be installed or configured for a page to call a component, and a page stays a Markdown file rather than becoming a module.

An MDC block survives being handed to a model as text: it reads as a component call with named arguments. Compiled JSX would not.

The syntax is Content's, so its capabilities and its limits are Content's too. Anything a page wants that MDC cannot express has to be solved as a component rather than as an expression in the page — which is a constraint on authors and, for a documentation site, a desirable one.

Component names in the content directory are part of the public surface, since a page written against one is a consumer's file.

#Alternatives considered

MDX. More expressive, and every bit of that expressiveness is JavaScript in a documentation page. It would also need a module and a build path Content does not have, to end up with pages that are worse to hand to a model.