CentrMark (.cmk) is the ideal markup format designed for modern technical writing and developer documentation. It explicitly seeks to address the limitations of Markdown, the syntactic noise of AsciiDoc, and the heavy developer-centric Javascript infiltration introduced by MDX, by providing a completely declarative, clean, and extensible syntax for document blocks and spans.

• 1. Core Philosophy
• 2. Why Not Markdown?
• 3. Why Not AsciiDoc?
• 4. Why Not MDX?
• 5. The CentrMark Answer
• 6. How CentrMark Improves Documentation (Simple Breakdown)
• 7. Cross-source references (xref vs link, without choosing)
• 8. License
• 9. Certification and Conformance
• 10. MVP Reference Implementation (D)
• 11. FFI surface for wrappers (no CLI dependency)
• 12. Website
• 13. Antora CMK backend
• 14. Wrappers
• 15. Commercial licensing lane (alternative terms)
• 16. Changelog

1. Familiar Base: The 90% use case remains pure Markdown (# headers, * bold, []() links) because it is ubiquitous, highly readable, and typed entirely with common keyboard keys without excessive shifting.

2. Native Extensibility: By avoiding HTML tags and React JSX (from MDX), CentrMark keeps documentation distinct from code. It uses a uniform Directive syntax for structural and dynamic features (like Confluence macros).

3. SDL-Powered: CentrMark abandons YAML frontmatter and JSON configuration, natively embracing SDL (Simple Declarative Language) for strongly typed, unquoted configuration of frontmatter and component properties.

4. Context-Sensitive Blocks: Like Python and Markdown, CentrMark is context-sensitive to reduce noise. Block hierarchies are managed visually with colons (:::) preserving pure text flow to the human eye.

5. Human and Machine Readability: Structuring is parsable directly into unified ASTs mapping perfectly to component frameworks or static site generators.

Traditional Markdown is too weak for technical writing. It lacks a standard Table of Contents, native support for tabs, admonitions, file transclusions, definition lists, or standardized cross-links. Markdown forces you into using fragile HTML fallback or proprietary markdown flavors.

AsciiDoc is robust but suffers from extreme syntax noisiness. The proliferation of ====, ----, …​., [source, type], and obscure attribute scoping make simple documents look unappealing in plaintext, slowing down the writing process.

MDX solves extensibility by injecting JSX and Javascript module importing into documents (import { Button } from './Button'). What was once text becomes an engineering artifact. Technical writers shouldn’t be writing React code to render a warning banner.

CentrMark defines three core mechanisms that extend Markdown capabilities seamlessly:

• The Void Directive: :: toc – self-closing, single-line functions or elements without content.

• The Block Directive: ::: tabs – container elements that hold complex markdown or other directives.

• The Inline Directive: @badge[color="red"](New) – text-span level enrichments.

For detailed breakdown, please see the spec/ folder.

Theo’s question is exactly the one we should answer up front: “how does this solve problems?”

CentrMark improves documentation by replacing tool-specific syntax hacks (Markdown extensions, AsciiDoc macro noise, and MDX/JS injection) with a small set of declarative primitives that map into a canonical AST. That gives you consistent behavior across implementations and keeps content focused on meaning.

You write a Semantic Link once: [[url | text]].

At build/render time:

• if url targets a known internal page/anchor in any content source, it behaves like an xref (jump + navigation)

• otherwise it behaves like a normal external link

Writers don’t need to remember “use xref here, link there”.

CentrMark materials in this repository are licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE, NOTICE, Licensing intent, and Trademark guidelines.

To keep CentrMark behavior consistent across independent implementations, this repository also defines a Conformance and Certification Program (CTS + registry + approved wording).

This repo includes an initial reference implementation in D:

• dlang/centrmark: parser + canonical AST JSON export (parseCmk, toJsonCanonical)

• dlang/centrmark-cli: centrmark-cli parse …​ command to emit canonical AST JSON

• dlang/centrmark-ffi: C-ABI dynamic library exposing:

  • cmk_parse_ref(input, len, outLen) → canonical AST JSON

  • cmk_parse_opt(input, len, outLen) → canonical AST JSON (optimized)

  • cmk_free(ptr) → free returned JSON

Wrappers should call the FFI directly (per wrappers/README.adoc) instead of shelling out to a CLI.

Build locally with dub:

The documentation + example registry site is in website/.

If you want to publish Antora documentation authored in CentrMark (.cmk), this repo includes an MVP backend/preprocessor at antora/cmk-antora-backend/.

See wrappers/README.adoc for the MVP download-and-load strategy per language.

Separately from sponsorship or paid support, this project may offer an alternative commercial licensing lane (via written agreement) for proprietary deployments, if maintainers/copyright holders have the required rights.

See Licensing intent and Commercial (Alternative) Licensing Lane.

See the Changelog for an iteration history of the specification.