diff --git a/docs/decisions/frontend/architecture/adr-choose-markdown-library/adr1.md b/docs/decisions/frontend/architecture/adr-choose-markdown-library/adr1.md new file mode 100644 index 000000000..3ef5988fd --- /dev/null +++ b/docs/decisions/frontend/architecture/adr-choose-markdown-library/adr1.md @@ -0,0 +1,46 @@ +# Architecture Decision Record 1: Use react-markdown with remark-gfm for Rendering Markdown Content + +Date: 05/03/2026 + +# Context + +The base model detail page displays long-form content (overview, use cases, performance, limitations) that was previously rendered using manual paragraph splitting and hardcoded HTML structures. As content grows in complexity — with bold text, inline code, lists, headings, and links — maintaining this as plain strings with custom rendering logic becomes difficult and error-prone. + +We need a solution to render rich, structured text from markdown strings so that content authors can express formatting naturally, while the UI consistently applies the project's design system. + +## Decision Drivers + +- Content flexibility: authors should be able to use headings, bold, lists, code, and links without code changes. +- Consistency: rendered markdown must match the application's existing design system (colors, typography, spacing). +- Minimal bundle impact: the chosen library should be lightweight and avoid unnecessary overhead. +- Existing ecosystem: leverage libraries already present in the project wherever possible. +- Security: HTML should be sanitised by default to prevent XSS from user-supplied content. + +## Considered Options + +- **[react-markdown](https://github.com/remarkjs/react-markdown) + [remark-gfm](https://github.com/remarkjs/remark-gfm)** — A lightweight React component that converts markdown to React elements via the unified/remark ecosystem. `remark-gfm` adds GitHub Flavored Markdown support (tables, strikethrough, task lists, autolinks). Does **not** use `dangerouslySetInnerHTML`; it builds a React virtual DOM tree. Already installed as project dependencies. +- **[markdown-to-jsx](https://www.npmjs.com/package/markdown-to-jsx)** — A single-package alternative that compiles markdown to JSX. Slightly smaller bundle size, but lacks the plugin ecosystem of remark and does not support GFM features without extra work. + +- **Custom rendering logic** — Continue splitting strings on `\n\n` and mapping to `

`, `