Markdown++.
The documentation format with the publishing power of XML and the source-file simplicity of plain Markdown. CommonMark-valid by design, MIT-licensed, and readable by any tool — or any AI agent — that reads Markdown.
<!--#authentication--> ## Authentication The $product_name; API uses OAuth 2.0. Tokens expire after $token_ttl;. <!--style:Note--> > Refresh tokens before expiry to avoid auth churn. <!--condition:internal--> For internal services, see the [shared OAuth flow](shared-oauth.md). <!--/condition-->
Publishing power, plain-text source.
Technical writing teams keep running into the same choice: power or simplicity. XML-based formats like DITA, DocBook, and FrameMaker XML cover structured content, conditional processing, content reuse, and multi-format publishing — but the source files read like XML, the tooling is specialized, and the learning curve is steep.
CommonMark is the opposite: simple, readable, works everywhere. But CommonMark alone lacks the publishing features professional documentation requires — no conditional content, no variables, no structured cross-references, no custom styling, no multi-format output pipeline.
Markdown++ removes the tradeoff. It extends CommonMark through HTML-comment directives and inline tokens that are invisible to standard Markdown renderers. Every Markdown++ file is a valid CommonMark document — the extensions activate when a Markdown++-aware tool reads them, and remain inert when a CommonMark viewer does.
The Markdown++ 1.0 specification is published under the MIT license at quadralay/markdown-plus-plus. It is not a proprietary file format; teams that adopt Markdown++ own their content in a vendor-neutral format.
Two extension mechanisms. Both invisible.
Every Markdown++ feature uses one of two extension mechanisms — both invisible to standard CommonMark renderers.
HTML Comment Directives
<!--style:Note--> > Always validate before publishing. <!--condition:online--> This section appears in web output only. <!--/condition--> <!--include:chapter-01.md-->
Standard Markdown renderers treat HTML comments as invisible. A publishing tool that supports Markdown++ activates the directives and produces structured output.
Inline Tokens
# $product_name; v$version; Welcome to $product_name;. Released on $release_date; for $platform_list;. The CLI ships with the $version_label; toolchain. See the [$product_name; Setup Guide](setup.md).
$product_name;, $version;, $release_date; define reusable values resolved
at publishing time. In a standard Markdown viewer the token appears as literal text; in published output it resolves
to the configured value.
Why Markdown++ is different.
Markdown++ covers the same structured content ground as DITA and DocBook — with simpler source files and full backward compatibility with the Markdown ecosystem you already use.
Attach semantic meaning to content without embedding presentation in the source. <!--style:Note--> maps to the appropriate output styling for each format. Standard renderers see a paragraph; the publishing tool applies the styling.
Show or hide sections based on output format, audience, or any defined condition. <!--condition:online-->...<!--/condition--> blocks render in standard Markdown for review and resolve to format-specific output during publishing.
Define reusable values managed centrally. $product_name;, $version;, and $release_date; tokens resolve at publishing time, so a single edit propagates everywhere.
Assemble multi-file publications using <!--include:chapter-01.md--> directives. Each file is independently editable and previewable. The book file is a manifest, not a monolithic document.
Semantic slugs decoupled from heading text mean references stay intact when content evolves. One reference resolves correctly in standard Markdown viewers, standalone publishing, and composite assemblies alike.
<!--markers:{"Keywords": "..."}--> attaches metadata for SEO, search indexing, and content management. Author once; publish to every format with the right metadata applied.
Markdown multiline tables — cells that hold block content.
Standard Markdown tables hold a single line of text per cell. Real documentation tables hold more —
multi-paragraph notes, bulleted lists, code samples, styled callouts. The Markdown++
<!-- multiline --> directive opens table cells to block-level content while keeping the base
table valid in any CommonMark viewer.
Maps to DITA's nested XML inside <entry> elements — without leaving plain text. Full syntax
in the
Markdown++ whitepaper §8.
<!--multiline--> | Step | Action | |------|---------------------------------------| | 1 | Install the CLI: | | | ```bash | | | npm install -g webworks-cli | | | ``` | | | Verify with `wwcli --version`. | | | | | 2 | Configure the project: | | | - Set `API_URL` | | | - Set `API_KEY` | | | - Run `wwcli build` | | | |
The base table renders cleanly in GitHub, VS Code, and any other CommonMark viewer — the
<!-- multiline --> directive is invisible. Markdown++-aware tools render the full cell structure:
lists, code fences, styled blockquotes, and continuation rows. One source file, both contexts.
Markdown++ vs. DITA / DocBook.
Markdown++ provides structured content capabilities comparable to DITA and DocBook, without requiring authors to write or maintain XML.
.md files + <!--include:--> @audience, @platform attributes<!--condition:--> <!--include:-->, variables <prolog>, <metadata> elements<!--markers:{}--> <xref>, @href[text][slug] with link reference definitions <!--style:--> directives For the capabilities most technical writing teams use daily, Markdown++ covers the ground DITA and DocBook occupy — with dramatically simpler source files. The full structured-content comparison and worked examples are available in the Markdown++ 1.0 Whitepaper.
The honest framing is comparable to DITA without XML overhead, not a drop-in replacement. DITA's relationship tables, specialization constraints, key scoping, and XLIFF-based localization have no direct Markdown++ equivalent — for teams that depend on those, DITA remains the right format.
The format AI agents read and write fluently.
AI language models read and write Markdown more fluently than any other documentation format — it is the format they encounter most in training, and the one they generate with the fewest structural errors. Markdown++ extensions follow predictable patterns models learn quickly. AI-generated DITA XML and FrameMaker XML content tends to carry mismatched elements, incorrect nesting, and missing attributes; AI-generated Markdown++ generally does not.
Combined with a CLI-driven publishing engine — ePublisher AutoMap — Markdown++ closes the agent-driven authoring loop. The agent drafts source in Markdown++; the agent publishes via the CLI; the resulting Reverb 2.0 helpset and matching Knowledge Files refresh on agent-driven cadence. No GUI in the loop; no human in the publishing seat; the output is the same.
Two public Claude Code skill packs demonstrate the loop end-to-end today: quadralay/markdown-plus-plus covers Markdown++ authoring — drafting in the directive grammar, validating extensions, applying conditional content — and quadralay/webworks-claude-skills covers ePublisher operations on Markdown++ source.
Because the source is readable, AI tools read Markdown++ diffs straight through — the content edit shows up directly, not buried under markup churn. A content-QA agent reviewing a PR sees what changed in the documentation, not in the XML wrapping it. Markdown++ source also produces a higher-quality Reverb 2.0 Knowledge Base for WebWorks Platform AI retrieval — structurally cleaner correspondence between source and Knowledge Files.
Meet your team where it already is.
Markdown++ is designed to meet teams where they already are. Existing ePublisher customers can adopt Markdown++ without changing their publishing pipeline.
Gain version control with meaningful diffs, no binary format lock-in, and pull request reviews for content changes. Custom paragraph and character styling carries forward via <!--style:--> directives.
FrameMaker .book files map directly to Markdown++ book assembly files using <!--include:--> directives. Conditional text, variables, cross-references, and index markers all carry forward.
DITA maps become book structure files. DITA topics become .md files. Topic-based authoring, content reuse, conditional processing, metadata, and multi-format output remain — without the XML overhead.
AsciiDoc content joins the pipeline via the upstream quadralay/asciidoctor-mdpp bridge — an open-source converter that produces valid Markdown++. From MDX and rST, the trade is non-standard syntax for full CommonMark compatibility — every Markdown++ file renders cleanly in standard tools, with no JSX, no custom block syntax, no build step just to preview.
Where Markdown++ works today.
Every Markdown++ extension is syntactically invisible to standard renderers. These are not fallback experiences — they are productive parts of a Markdown++ workflow.
File views, pull request diffs, and code review work cleanly. The ++ extensions are hidden as HTML comments.
Standard Markdown preview in VS Code, JetBrains, and any other Markdown-aware editor — no plugins required.
MkDocs, Docusaurus, Jekyll, Hugo, and any other CommonMark-compliant viewer render Markdown++ files as Markdown.
Activates the extensions and produces multi-format output — Reverb 2.0, PDF, CHM, Eclipse Help, and Dynamic HTML — from a single source.
Three decades of publishing expertise.
Markdown++ did not emerge from a startup experiment or an academic research project. It is the product of Quadralay / WebWorks — a company that has been solving technical publishing problems since the early 1990s. The design decisions in Markdown++ reflect lessons learned across three decades of structured authoring and multi-format output generation.
WebWorks began with Adobe FrameMaker integration in the early 1990s, added Microsoft Word support in 2005, and DITA XML support in 2007. Markdown was added as an input format in 2017 as documentation shifted toward developer-centric workflows. Markdown++ followed in 2020 — extending CommonMark using the invisible-extension pattern to bring the same structured authoring capabilities to the simplest and most widely adopted authoring format in the industry.
The result is a documentation format backed by a company that has processed millions of pages across every major authoring format and refined its publishing pipeline through seven generations of online help output.
Get started with Markdown++.
The Markdown++ 1.0 specification, examples, and reference implementation are open and free under the MIT license. WebWorks ePublisher provides a complete publishing pipeline for Markdown++ source — try it free for 14 days.