Markdown Core

Markdown Core is a cross-platform Markdown parser with a shared immutable abstract syntax tree (AST) for C, Swift, Kotlin, and ECMAScript. One C engine provides consistent parsing behavior and source locations across all bindings.

The library provides synchronous parsing and read-only AST traversal. It has one Markdown dialect with no parse options. Applications own rendering and keep the source text when they need it; the parser does not retain the input.

Read the Markdown syntax guide to learn the language, or the documentation index for the AST and source-location contracts.

Usage

Swift

The Swift package supports iOS 26 and macOS 26 or later. Add the MarkdownCore product to your target:

.package(url: "https://github.com/nouprax/markdown-core", from: "3.0.0")

import MarkdownCore

let source = "Hello, Markdown."
let document = try Document.parse(source)
print(try document.dump(in: source))

The AST is an immutable, Sendable value tree with typed visitors and stack-safe walking. Child relations use read-only MarkupCollection and MarkupGroups values with constant-time random access; use Array(...) when an array is required. Retaining a subtree keeps its immutable Swift store alive. The native C document is freed before parse returns. See Swift storage for ownership and lifecycle details.

The MarkdownCoreLSP product is the language engine, the semantics of the Language Server Protocol 3.17 over the parser, called in process. MarkdownCoreLSP.Server has one method per protocol method, and answers as the C engine and the JSON-RPC adapter markdown-core-server do; Kotlin's com.nouprax.markdown.core.lsp.Server and the ECMAScript entry point @nouprax/es-markdown-core/lsp are the same server.

import MarkdownCoreLSP

let server = try Server()
_ = try server.initialize([.utf8, .utf16])  // UTF-8 when offered
try server.open("file:///note.md", version: 1, text: "# Title\n\n[a](")
let end = Position(line: 2, character: 4)
try server.update("file:///note.md", version: 2, edits: [Edit(scope: Scope(start: end, end: end), text: "/url)")])
let completions = try server.complete("file:///note.md", at: end)  // completions.version == 2

Kotlin Multiplatform

Add the dependency to a Kotlin Multiplatform source set:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.nouprax:kotlin-markdown-core:3.0.0")
        }
    }
}

import com.nouprax.markdown.core.Document

val source = "Hello, Markdown."
val document = Document.parse(source)
println(document.dump(source))

Supported targets are Android API 21 or later, JVM 17, macOS arm64, and Linux x64. Native runtime dependencies are included. On JDK 26 or later, launch JVM applications with --enable-native-access=ALL-UNNAMED to avoid the native-access warning from the JNI loader.

ECMAScript and TypeScript

pnpm add @nouprax/es-markdown-core

import { Document, MarkupDumper } from "@nouprax/es-markdown-core";

const source = "Hello, Markdown.";
const document = Document.parse(source);
console.log(MarkupDumper.dump(document, source));

The ESM package supports Node.js 20 or later and browsers that can load its WebAssembly asset. Parsing is synchronous once the import resolves. TypeScript values are recursively readonly; JavaScript objects are not runtime-frozen.

C and C++

Link the installed CMake target:

find_package(markdown-core CONFIG REQUIRED)
target_link_libraries(my-app PRIVATE markdown-core::markdown-core)

Include <markdown_core.h> and call markdown_core_document_parse. Every call that can fail returns a markdown_core_status and writes its result through an out-parameter only on MARKDOWN_CORE_OK. Release a parsed document with markdown_core_document_free; node and string views borrow from that document. Release an allocated dump with markdown_core_dump_free.

Independent parses may run concurrently. Read-only access to a document is safe while it remains alive. See the public C header for the complete API and ownership rules.

Development

Start with the toolchain and environment guide, validate your setup with scripts/tooling/setup-environment.sh --check, then install dependencies:

pnpm install --frozen-lockfile

Build the package you are working on:

pnpm build:c
pnpm build:swift
scripts/tooling/run-gradle.sh :packages:kotlin-markdown-core:jvmJar
pnpm --dir packages/es-markdown-core build

The C CLI at build/cmake/packages/markdown-core/core/markdown-core reads files or standard input and prints a debug AST dump. To install the C library:

cmake --install build/cmake --prefix /path/to/prefix

Run the tests for your host, such as pnpm test:c-host and pnpm conformance:c-host. See testing for all platform targets, sanitizers, conformance checks, and benchmarks. pnpm verify runs the repository's formatting, lint, contract, and audit checks.

The four bindings live in packages/; shared executable fixtures live in specs/. Reader documentation lives in docs/specs/, implementation design in docs/architecture/, and consumer examples in samples/.

For releases, follow the release guide and change log.

License

Markdown Core is an independent project derived from cmark, cmark-gfm, and DongyuZhao/cmark-gfm. It preserves the applicable upstream copyright and license notices. See LICENSE, COPYING, and UPSTREAM.md for licensing and lineage.