Markdown++ is now an open standard

Technical writing teams keep running into the same choice: power or simplicity.

Formats like DITA XML, DocBook, and FrameMaker handle structured content, conditional processing, content reuse, and multi-format publishing. But they come with real overhead. The tooling is specialized, the learning curve is steep, and source files are hard to read or review without that ecosystem in place.

Markdown is the opposite. Simple, readable, works everywhere. Anyone on the team can contribute. The files are easy to diff and review in modern workflows. But as documentation sets grow — software manuals, API references, multi-audience publications — the gaps get harder to ignore. No standard way to handle conditional content, variables, reuse, stable cross-references, or multi-format publishing.

Most teams pick a side.

Markdown++ removes that tradeoff. It adds professional publishing features to CommonMark through extensions that are invisible to standard Markdown renderers. Every Markdown++ file is a valid Markdown file. The extensions are additive, nothing breaks.

The Markdown++ 1.0 specification is now publicly available on GitHub, published under the MIT license.

The whitepaper covers the format design, side-by-side comparisons with DITA, and migration paths — whether you're evaluating documentation formats from scratch, considering a move from Word or FrameMaker, or building docs-as-code workflows.

What Markdown++ is

Markdown++ is a documentation format built on the CommonMark specification. Quadralay / WebWorks developed it, building on what we've learned publishing across FrameMaker, Word, and DITA XML since 1997.

Extensions use two mechanisms:

• HTML comment directives — <!-- style:Note -->, <!-- condition:online -->, <!-- include:path/to/file.md -->
• Inline tokens — $product_name; for variables resolved at publishing time

Standard Markdown renderers treat HTML comments as invisible and pass inline tokens through as literal text. A Markdown++ file opens cleanly in GitHub, VS Code, MkDocs, or any other Markdown viewer without plugins or configuration. When processed by a publishing tool like WebWorks ePublisher, the extensions activate and produce multi-format output — responsive HTML5, PDF, CHM, Eclipse Help — from a single source.

Existing ePublisher customers can adopt Markdown++ without changing their publishing pipeline.

What makes Markdown++ different

Markdown++ covers the same structured content ground as DITA and DocBook — topic-based authoring, conditional content, variables, content reuse, metadata, cross-references, custom styling — with simpler source files. Here are a few of the extensions:

Custom styles attach semantic meaning to content without embedding presentation in the source:

<!-- style:Note -->
Back up your configuration before upgrading.

In a standard Markdown viewer, you see a paragraph (the comment is invisible). A publishing tool maps Note to the appropriate styling for each output format.

Conditional content shows or hides sections based on output format, audience, or custom conditions:

<!-- condition:online -->
For the latest updates, see the [release notes](release-notes.md).
<!-- /condition -->

In standard Markdown, both branches are visible — an acceptable fallback for review and editing.

Variables define reusable values resolved at publishing time. A $product_name; token appears as literal text in a standard viewer and resolves to the configured value in published output.

File includes enable book assembly from individual topic files using <!-- include:chapter-01.md --> directives, each file independently previewable.

The whitepaper covers all eight extension types with syntax examples, a DITA-to-Markdown++ side-by-side comparison, and the full structured content comparison table. The repository also includes example files for each extension type.

Markdown++ and AI

AI language models are good at reading and generating Markdown. It's the format they encounter most in training data and handle most accurately. Standard Markdown renderers ignore the HTML comment extensions, but language models can parse the directives and work with both the content and the extensions.

In practice, AI coding tools like Claude Code, GitHub Copilot, and Cursor can draft and edit Markdown++ content accurately because the extension syntax is simple and consistent. AI-generated DITA, by contrast, often needs manual correction — mismatched elements, incorrect nesting, missing required attributes.

The whitepaper's AI advantage section covers AI-assisted authoring, automated content migration, content review, and agent-driven publishing workflows in detail.

Read the specification

The Markdown++ 1.0 specification is on GitHub under the MIT license. Third-party tool implementations and community contributions are welcome.

• Markdown++ 1.0 Whitepaper — format design, comparisons, migration paths, worked examples
• Markdown++ Repository — specification, examples, and the Claude Code authoring plugin