Extension 12 / kotmark-ext-yaml-front-matter

YAML front matter

Front matter remains available to the application while HTML output contains the Markdown body only.

Artifact: io.heapy.kotmark:kotmark-ext-yaml-front-matter:0.1.0
Package: io.heapy.kotmark.ext.front.matter

Usage

Visit the parsed document with YamlFrontMatterVisitor to read the top-level metadata.

Read metadata and render the body

import io.heapy.kotmark.ext.front.matter.YamlFrontMatterVisitor
import io.heapy.kotmark.ext.front.matter.yamlFrontMatter
import io.heapy.kotmark.extensions
import io.heapy.kotmark.parser.parser
import io.heapy.kotmark.renderer.html.htmlRenderer

class Page(val metadata: Map<String, List<String>>, val html: String)

fun readPage(markdown: String): Page {
    val extensions = extensions { yamlFrontMatter() }
    val parser = parser { extensions(extensions) }
    val document = parser.parse(markdown)
    val visitor = YamlFrontMatterVisitor()
    document.accept(visitor)
    // The front matter is a separate node; HTML output contains only the body.
    return Page(visitor.data, htmlRenderer().render(document))
}

Example

readPage returns metadata and HTML separately. The map below is the extracted metadata; only the Markdown body appears in the HTML output.

INPUT · Markdown

---
title: Release notes
tags:
  - kotlin
  - markdown
---

# Hello

METADATA · Kotlin map

{title=[Release notes], tags=[kotlin, markdown]}

OUTPUT · HTML

<h1>Hello</h1>

Behavior

The extension recognizes only front matter at the beginning of a document. It does not validate YAML application schemas; use the returned values to apply your own validation and defaults.