Extension index / opt-in syntax
Extensions
Keep the CommonMark core focused and add only the modules an application needs.
Extension modules
| Module | Adds |
|---|---|
| Autolink | Bare URL and email links |
| Emoji | Unicode emoji from :shortcode: aliases |
| Footnotes | Footnote references and definitions |
| GFM alerts | GitHub-style alert blocks |
| GFM strikethrough | Struck-through text |
| GFM tables | Pipe tables |
| Heading anchors | Stable heading IDs |
| Table of contents | Linked heading outlines with [TOC] or [[_TOC_]] |
| Highlight | ==highlighted text== |
| Image attributes | Extra image attributes |
| Inserted text | Inserted text syntax |
| Math | Inline and block formula source |
| Task list items | Checkbox list items |
| YAML front matter | YAML document metadata |
Registration
Create one list with io.heapy.kotmark.extensions { … }, then pass it to
parser { extensions(list) } and each renderer that needs it. Import the registration
functions from the packages listed on the individual extension pages.
import io.heapy.kotmark.ext.gfm.strikethrough.strikethrough
import io.heapy.kotmark.ext.gfm.tables.tables
import io.heapy.kotmark.extensions
import io.heapy.kotmark.parser.parser
import io.heapy.kotmark.renderer.html.htmlRenderer
fun renderWithExtensions(markdown: String): String {
val extensions = extensions {
tables { maxCells = 100_000 }
strikethrough { requireTwoTildes = true }
}
val parser = parser { extensions(extensions) }
val renderer = htmlRenderer { extensions(extensions) }
return renderer.render(parser.parse(markdown))
}| Module | Registration inside extensions { … } |
|---|---|
| Autolink | autolink { linkTypes = setOf(AutolinkType.URL) } |
| Emoji | emoji() or emoji(customAliases = mapOf("party" to "🥳")) |
| Footnotes | footnotes { inlineFootnotes = true } |
| GFM alerts | alerts { addCustomType("INFO", "Information") } |
| GFM strikethrough | strikethrough { requireTwoTildes = true } |
| GFM tables | tables { maxCells = 100_000 } |
| Heading anchors | headingAnchor { idPrefix = "section-" } |
| Table of contents | toc { headingLevels = 2..6 } |
| Highlight | highlight() |
| Image attributes | imageAttributes() |
| Inserted text | ins() |
| Math | math() |
| Task list items | taskListItems() |
| YAML front matter | yamlFrontMatter() or yamlFrontMatter(factory) |
Configuration blocks are optional. Use add(customExtension) for a custom instance
or addAll(existingExtensions) to compose lists. Registration order is preserved;
the first registered renderer for a node type wins. See
configuration for snapshot and sharing rules.
Parser-only and renderer-only extensions can share the same list: each consumer applies only the extension interfaces it supports. The kotlinx.html renderer needs its matching adapters for extension output.