Kotlin Markdown DSL

Kotlin ❤️ Markdown

A Kotlin DSL for effortless creation of beautiful Markdown pages, supporting both basic and extended syntax (Coming soon™️).

☁️ Setup

repositories {
    mavenCentral()
}

dependencies {
    // include for Common module
    implementation("io.github.milis92.kotlin_markdown:basic:$latest_version_here")

    // include for JVM target
    implementation("io.github.milis92.kotlin_markdown:basic-jvm:$latest_version_here")
}

🧾 Usage

Basic syntax

Basic implementation follows official Markdown syntax and should be supported by almost all Markdown processors.

Text

To create a simple line of text:

markdown {
    line("This is a simple line of text")
}

Or if you have a text with multiple lines:

markdown {
    line {
        """
        |A Kotlin DSL for effortless creation of beautiful Markdown pages,
        |supporting both basic and extended syntax (Coming soon™️).
        """.trimMargin()
    }
}

If you need custom emphasis, you can use the italic, bold or codeSpan spans:

markdown {
    line("This is a" + "simple".bold() + "line".italic() + "of code".codeSpan())
    //Or you can use spans directly if you want to have full lines emphasised:
    bold("This is a bold text")
    italic("This is an italic text")
    codeSpan("This is a code span")
}

You can configure emphasis markers as well:

markdown {
    bold("This is a bold text", EmphasisMarker.Underscore)
    italic("This is an italic text", EmphasisMarker.Asterisks)
}

Paragraph

Every paragraph is consisted of multiple lines and each line (except the last one) will be terminated by a line break (2 space characters + new empty line)

To create a simple paragraph:

markdown {
    paragraph {
        line { "First paragraph" }
        line { "Second paragraph" }
    }
}

Horizontal rules

To create a simple horizontal rule:

markdown {
    horizontalRule()
}

If you want to use a custom style for your horizontal rule:

markdown {
    horizontalRule(style = HorizontalRuleStyle.Hyphen)
}

Headings

Markdown supports two styles of headings:

• ATX Styled Headings
• Setext Styled Headings

Creating ATX Styled Heading:

markdown {
    heading("This is an ATX styled heading")
}

Creating Setext Styled Heading:

markdown {
    underlinedHeading("This is an Setext styled heading")
}

Note Markdown headings support only single line text as headings, so content will be automatically stripped of any new lihnes

If you want to use a custom style for your heading:

markdown {
    heading("This is an ATX styled heading", H1)
    underlinedHeading("This is an Setext styled heading", H2)
}

Headings support text spans as well:

markdown {
    heading("This is an" + bold("ATX") + "styled heading", H1)
    underlinedHeading("This is an" + italic("Setext") + "styled heading", H2)
}

Blockquotes

Creating Simple blockquote:

markdown {
    blockQuote("Simple single line blocquote")
}

Creating Blockquote with nested elements:

Blockquote can hold any other markdown element, including blocquote as well

markdown {
    blockQuote {
        heading("Heading 1")
        underlinedHeading("Underlined Heading")
        horizontalRule()
        orderedList(listOf("Item 1", "Item 2"))
        unorderedList(listOf("Item 1", "Item 2"))
    }
}

Code Blocks

Creating a simple code block:

markdown {
    codeBlock {
        @Language("kotlin")
        val block =
            """
            |val hello = "Hello World"
            """.trimMargin()
        block
    }
}

Note that you can use IJ Language injection to get a bit of help from your IDE

Image and Url Spans

Creating a simple URL:

markdown {
    link("Google", URI("https://www.google.com"))
}

Creating a simple Image:

markdown {
    image("Google", URI("https://www.google.com"))
}

Using URL Element as Line span :

markdown {
    line {
        "This is a link: " + "Google".link(URI("https://www.google.com"))
    }
}

Using Image Element as Line span :

markdown {
    line {
        "This is an image: " + "Google".image(URI("https://www.google.com"))
    }
}

Lists

Markdown supports 2 types of lists:

• Ordered lists (list with numbers)
• Unordered lists (list with bullets)

Creating an ordered list:

markdown {
    orderedList(listOf("Item 1", "Item 2"))
}

Creating an unordered list:

markdown {
    unorderedList(listOf("Item 1", "Item 2"))
}

Creating a list with complex items:

markdown {
    //Works the same for unordered list
    orderedList {
        item {
            line { "First paragraph" }
            line { "Second paragraph" }
        }
        item("Second item")
    }
}

Creating a list with nested list:

markdown {
    //Works the same for unordered list
    orderedList {
        item {
            line { "First item" }
            unorderedList {
                item("First sub item")
                item("Second sub item")
            }
        }
        item("Second item")
    }
}

🖨️ Exports

You can easily export Markdown content to a file using line writer of your choosing.
For example:

val markdown = markdown {
    //your markdown content
}

File("../README").writeText(markdown.content)

---

This library is licensed under the Apache Version 2.0 License - see the License file for details.