Expressive Markdown

Why Expressive Markdown

Rich editors can store formatting, block structure and document metadata as well as words. Saving that document as Markdown and opening it again requires the text file to carry that information:

Rich editor → Markdown → rich editor

The goal is to preserve rich content through that round trip while keeping the Markdown source readable and practical to edit by hand.

CommonMark defines ordinary Markdown. GFM adds tables, task lists and strikethrough.¹ Expressive Markdown builds on these formats to address three recurring problems in richer documents:

Problem #1 - Conversions can lose structure

A rich editor may support warning callouts, centered layouts and tab groups. CommonMark and GFM have no standard shorthand for those features. Even when an editor supports them fully, its Markdown export needs a way to describe them.

For example, a warning exported using only ordinary Markdown shorthand might keep its words and bold title:

**Before upgrading**

Back up your data.

The file contains no warning type or separate title field. Even the same editor cannot reliably tell whether the bold paragraph was a warning title or ordinary formatted text. The information was lost in the export representation. Raw HTML or tool-specific extensions can carry extra information; restoring it still needs agreed import rules.

Expressive Markdown defines readable extensions for that context:

::: warning [Before upgrading]
Back up your data.
:::

The container names the warning and separates its title from its body. Shared attributes carry formatting and settings; YAML frontmatter carries document metadata. These details stay explicit in the text, with a shared document tree for tools to read and write consistently. That is the “expressive” part: richer documents without giving up readable Markdown.

See the warning example →

Problem #2 - Tables can be hard to edit

Pipe tables work well for short values. Long rows are harder to scan and require editing across columns. GFM cells cannot contain block content such as paragraphs, lists or fenced code.⁷

List-based tables let each cell read from top to bottom. Text can wrap without aligning neighboring columns, and cells can hold ordinary Markdown blocks:

::: table

- Task: Install
  Steps:
    - Download the package.
    - Run the installer.

:::

Explore tables and merged cells → Traditional pipe tables remain supported for compatibility.

Problem #3 - Extensions vary between tools

Documentation tools provide callouts, tabs and other features through extensions. Their syntax and conventions vary, so moving a document can require translating those features individually.²³

CommonMark and GFM do not define a shared format for those features. Expressive Markdown brings common extensions into one well-defined syntax, with shared meanings and a document model. Containers, inline extensions, attributes and YAML frontmatter carry rich structure, formatting context and metadata in readable source. Custom types use the same grammar.

The format is independent of a component framework or site generator.

What the proposal defines

Chapters

Tools

expressmark is the JavaScript tooling project for Expressive Markdown, with releases on npm. Its repository documents the available APIs and implementation status. The language and AST remain independent of that package.

Prior art

Expressive builds on established Markdown conventions:

• CommonMark and GFM: ordinary Markdown, tables, task lists and strikethrough.¹
• Docusaurus and remark: documentation callouts, nested colon fences and named constructs.²³
• Pandoc: attribute IDs and leading-pipe line blocks.⁴
• UMD: compact markers for merged table cells.⁵
• mdast and unist: documented tree structures; Expressive uses its own named content fields.⁶

These influences do not imply full source compatibility. MDX/JSX, JavaScript execution and framework component APIs are outside the language.

References

1. CommonMark 0.31.2 and GitHub Flavored Markdown.
2. Docusaurus Markdown features and admonitions.
3. remark-directive.
4. Pandoc's Markdown.
5. UMD table-spanning documentation.
6. mdast and unist.
7. GFM table syntax and cell contents.