Context
Case studies need embedded evidence blocks, diagrams and callouts. MDX allows that, but an MDX file is a program: anything in it runs at build time and in the browser.
Options
- MDX. Flexible, but every content file is code.
- Markdown with a small directive vocabulary, mapped to an allowlisted set of React components.
Decision
Content files are Markdown with GitHub-flavoured tables and four directives: ::evidence{id},
::limitations{id}, ::diagram{name} and :::callout{kind}. They are parsed with unified/remark into
a syntax tree that is sanitized and then mapped to React elements. Nothing is evaluated, and raw HTML is
dropped. The evidence audit rejects unknown directives, unknown evidence ids, unknown diagrams and raw
script, style or iframe tags.
Consequences
- A content change cannot run code.
- Adding a new embedded component needs a code change and review. That is intended.