Start with the core, then name every extension
CommonMark is a specification and test suite for Markdown's core behavior. GFM is GitHub's formal extension of that baseline. GitHub's product also documents features such as mathematical expressions, alerts, and Mermaid diagrams that are useful but separate from the formal GFM specification.
MDLoom keeps those layers visible. The local workspace and bundle manifest store a profile identifier; cloud revisions and server artifacts additionally record renderer identity or engine metadata where that path provides it.
Choose based on the destination
Use CommonMark for the smallest broadly specified surface. Choose strict GFM when the destination is GitHub-style documentation and tables, task lists, strikethrough, or autolinks matter. Choose GitHub Extended inside MDLoom when you also need an explicitly versioned set of supported extras.
- CommonMark: portable prose, lists, quotes, links, images, and code.
- Strict GFM: CommonMark plus formal GitHub table, task-list, strikethrough, autolink, and tag-filter behavior.
- GitHub Extended: MDLoom's default, adding only a documented allowlist of extra GitHub-style features.
- Pandoc Publishing: metadata, footnotes, math, and a managed Pandoc reader for rich exports; not every Pandoc extension has a matching browser preview component.
Treat a profile change as a transformation
Changing a profile can turn plain text into a table, alter autolinks, expose raw HTML differences, or remove support for an extension. MDLoom performs a dry-run comparison and shows diagnostics before confirmation; confirming the profile does not rewrite the source.
Write the profile into the project policy
For a team repository, document the selected flavor beside lint and build instructions. Test representative fixtures—especially nested lists, tables, links, HTML, math, and diagrams—against the real destination.
- Pin the renderer or record its version in generated artifacts.
- Reject unknown extensions rather than silently ignoring them.
- Keep executable MDX out of untrusted user content.
- Include source and report files when handing off rich exports.