Documentation: https://markup-poets.github.io/markup-poets/ · Changelog: CHANGELOG.md

A type-safe Kotlin DSL for building markup models — documents, tables, graphs, grammars — and writing them as source text: AsciiDoc, Markdown, Graphviz DOT, or the BNF family. Built with Kotlin Multiplatform.

This is the DSL poet of the Markup Poet family — a growing set of markup tools ("poets") that includes asciidoc-kmp, the AsciiDoc parser.

An abstract, format-agnostic document model composed of sub-DSLs, each usable standalone, plus writer modules that write the models as concrete markup formats:

Planned: further markup writers (e.g. DocBook) as sibling modules, and further sub-DSLs. Rendering to presentation formats (HTML, PDF) is out of scope here — that's the job of downstream tools consuming the written markup.

• Type-safe DSL: Describe documents in Kotlin — sections, paragraphs, code blocks, images, tables, nested lists
• Standalone sub-DSLs: Each sub-DSL (e.g. tables) works on its own; build and write a table without a document around it
• Writer modules per format: AsciiDoc, Markdown, Graphviz DOT and the BNF family today — toAsciidoc() / toMarkdown() / toDot() / toBnf(), write*To(Appendable), write*To(Sink) (kotlinx-io), *Flow(): Flow<String> (streaming)
• Platform independent: JVM, Android (API 24+), iOS, Linux, macOS
• Zero dependencies in the model/DSL modules; writer modules use kotlinx-io and kotlinx-coroutines

import org.markup.poet.dsl.document.article
import org.markup.poet.dsl.document.ListType
import org.markup.poet.dsl.write.asciidoc.toAsciidoc

val doc = article("Markup Poet") {
    section("Usage") {
        +"A DSL for markup documents."
        code("kotlin") {
            +"val doc = article {}"
        }
        list(ListType.ORDERED) {
            +"build"
            +"write"
        }
    }
}

println(doc.toAsciidoc())

produces AsciiDoc source text:

= Markup Poet

== Usage

A DSL for markup documents.

[source,kotlin]
----
val doc = article {}
----

. build
. write

article(title) { } writes the title as the = document title and starts sections at ==, following AsciiDoc convention. The title-less form article { } starts sections at = instead.

Sub-DSLs work without a document. The table DSL, for example:

import org.markup.poet.dsl.table.table
import org.markup.poet.dsl.write.asciidoc.toAsciidoc

val t = table {
    header {
        cell("name")
        cell("value")
    }
    row("answer", "42")
}

println(t.toAsciidoc())

|===
|name|value

| answer
| 42
|===

The same table { } builder is used inside documents via section { table("title", "id") { ... } }.

The graph DSL works the same way — build a graph, write it as Graphviz DOT:

import org.markup.poet.dsl.graph.digraph
import org.markup.poet.dsl.write.dot.toDot

val g = digraph("Pipeline") {
    node("parse") { shape = "box" }
    node("write") { shape = "box" }
    edge("parse", "write") { label = "model" }
}

println(g.toDot())

digraph Pipeline {
  parse [shape=box];
  write [shape=box];
  parse -> write [label=model];
}

Render it with Graphviz: dot -Tsvg pipeline.dot -o pipeline.svg.

The grammar DSL follows the same shape — build a grammar, write it as BNF, EBNF or ABNF:

import org.markup.poet.dsl.grammar.grammar
import org.markup.poet.dsl.write.bnf.BnfFlavor
import org.markup.poet.dsl.write.bnf.toBnf

val g = grammar {
    rule("expr") {
        ref("term")
        zeroOrMore {
            choice {
                +"+"
                +"-"
            }
            ref("term")
        }
    }
}

println(g.toBnf())

expr = term, {("+" | "-"), term};

One model, three notations — the flavor is a parameter, not a different writer:

g.toBnf(BnfFlavor.ABNF)   // expr = term *(("+" / "-") term)
g.toBnf(BnfFlavor.BNF)    // <expr> ::= <term> <expr-rep>
                          // <expr-rep> ::= <expr-alt> <term> <expr-rep> | ""
                          // <expr-alt> ::= "+" | "-"

EBNF is the default because it maps 1:1 to the model. Classic BNF has no optional, repetition or grouping syntax, so those become synthetic rules — see the BNF mapping for the full table.

Beyond the typed style properties, arbitrary attributes pass through at graph, node, and edge level — attr("rankdir", "LR"), attr("penwidth", "2") — so the full DOT attribute vocabulary is available. And because the graph model is generic, it covers DAG/FSM-style use cases: markup-graph ships Graph.isAcyclic() and Graph.topologicalSortOrNull() (Kahn's algorithm, deterministic order) for directed graphs.

Every model type gets four write forms in each writer module:

doc.toAsciidoc()                 // String
doc.writeAsciidocTo(appendable)  // any Appendable (StringBuilder, java.io.Writer, ...)
doc.writeAsciidocTo(sink)        // kotlinx-io Sink, UTF-8; caller flushes/closes
doc.asciidocFlow()               // cold Flow<String> of chunks, in document order;
                                 // concatenating all chunks == toAsciidoc()

doc.toMarkdown()                 // same four forms per format
doc.writeMarkdownTo(sink)
doc.markdownFlow()

Markdown notes (GFM): block ids become <a id="..."></a> anchors, table titles become a bold line, headerless tables get an empty header row, image width/height are dropped (no native syntax).

Note: depending on a writer module brings kotlinx-io and kotlinx-coroutines onto your classpath; the model/DSL modules (markup-table, markup-document) stay dependency-free.

./gradlew build                                    # full build
./gradlew :markup-table:jvmTest :markup-document:jvmTest :markup-asciidoc-writer:jvmTest
./gradlew :markup-asciidoc-writer:linuxX64Test     # native tests (Linux host)

Licensed under the Apache License, Version 2.0. See LICENSE for details.