markdown

Rendering

2026-05-12T21:20:17.378753286Z

renderToHTML is the default emitter, but the AST is not bound to it. There’s also an XML emitter, and the public helpers (renderBlockToHTML, renderInlines, plainText) let you compose your own pipeline.

Two entry points

def renderToHTML(md: String,    config: MarkdownConfig = MarkdownConfig.default): String
def renderToHTML(node: Node,    config: MarkdownConfig = MarkdownConfig.default): String

The string overload parses then renders. The node overload skips parsing — useful when you’ve built or transformed the AST yourself.

Escape rules

Inline Text is escaped via escapeXml, which encodes &, <, >, and ". Single quotes are not escaped (they’re safe in attribute values when those values are double-quoted, which the renderer guarantees).

Code spans and code blocks are escaped the same way — never raw-passed. This is deliberate: an <code> span containing <script> should render as visible text, not execute.

URLs in <a href="…"> and <img src="…"> go through percentEncode first. The function intentionally treats % as already-safe, so a hand-written https://example.com/foo%20bar stays as %20 rather than getting double-encoded to %2520.

Raw HTML

HTMLBlock (block-level) and RawHTML (inline) pass through verbatim — no escaping, no transformation. This is the standard CommonMark behavior. If you’re rendering untrusted input, sanitize the output yourself; this library does not pretend to be a sanitizer.

Custom code highlighting

Set codeHighlighter on the config to plug in syntax highlighting:

codeHighlighter: Option[(String, String) => Option[String]]
//                       ^^ code     ^^ language
//                                              ^^ highlighted HTML or None

When the function returns None, the renderer falls back to plain <pre><code>…</code></pre>. When it returns Some(html), that html is dropped in directly — your highlighter is responsible for any escaping.

import io.github.edadma.markdown.*
import io.github.edadma.highlighter.*

val mode = ClassMode("hl-")
val scalaHl = Highlighter.fromJson(scalaGrammarJson, mode).toOption.get

val cfg = MarkdownConfig.all.copy(
  codeHighlighter      = Some((code, lang) =>
                           if lang == "scala" then Some(scalaHl.highlight(code)) else None
                         ),
  indentedCodeLanguage = Some("scala"), // assume indented blocks are Scala
)

renderToHTML("```scala\nval x = 42\n```", cfg)

Works with highlighter or any function with the right shape.

Helpers for AST consumers

The renderer exposes its block- and inline-level workers as public functions:

def renderBlockToHTML(node: Block, config: MarkdownConfig = MarkdownConfig.default): String
def renderInlines(inlines: List[Inline]): String
def plainText(inlines: List[Inline], escape: Boolean = false): String

renderInlines is what you reach for to render heading or link-text content as HTML without a surrounding <p> wrapper — the building block for table-of-contents items, anchor labels, summary excerpts.

plainText flattens an inline list to its textual content, stripping all formatting. escape = true runs the result through escapeXml, which is what you want when emitting into alt="…", title="…", or a <title> tag.

XML output

def renderToXML(doc: Document, system: String = "document"): String

Emits CommonMark XML format with <?xml … ?> declaration and a DTD reference. Heading rendering is simplified to plain text — the XML form is intended for spec conformance and AST-diffing tools, not for downstream HTML.

Heading IDs and slugs

When autoHeadingIds = true, the parser populates each heading’s id from its plain-text content via the slugify callback. The renderer just emits whatever’s already on the node — it doesn’t slug-ify at render time. This means slug behaviour is controlled at parse time, and the same Document value will always render with the same ids.

Explicit ids set via the attributes extension always win:

## Hello, World! {#my-explicit-id}

renders to <h2 id="my-explicit-id">Hello, World!</h2> regardless of whether autoHeadingIds is on.

Render to your own format

The renderers are not magic — they’re pattern matches on Block and Inline. To target a different format, write your own walker. See Recipes → Custom renderer for a worked example.

Quickstart

2026-05-12T21:20:17.378753286Z

This walkthrough shows the three things you’ll do with the library 95 % of the time: render to HTML, parse to an AST, and turn on extensions.

1. Render markdown to HTML

The one-line case:

import io.github.edadma.markdown.*

renderToHTML(
  """
    |# Hello, CommonMark!
    |
    |This is **bold**, *italic*, and `code`.
    |""".stripMargin
)

Output:

<h1>Hello, CommonMark!</h1>
<p>This is <strong>bold</strong>, <em>italic</em>, and <code>code</code>.</p>

The default config follows the CommonMark spec exactly — no GFM tables, no math, no emoji. Predictable output for any input.

2. Parse to an AST

When you want the structured form rather than HTML:

import io.github.edadma.markdown.*

val doc: Document = parseDocumentContent("# Hello\n\nWorld.")

// All top-level Heading blocks, in source order.
val titles: List[Heading] = doc.headings

// Plain-text projection of a list of inlines (strips formatting).
val title: String = plainText(titles.head.inlines)
// → "Hello"

Document.children is a List[Block]; each Heading, Paragraph, ListBlock, etc. carries its own typed children. See AST for the full hierarchy.

3. Turn on extensions

MarkdownConfig.default is pure CommonMark. MarkdownConfig.all flips on every extension at once:

val cfg = MarkdownConfig.all

renderToHTML("| a | b |\n|---|---|\n| 1 | 2 |", cfg)
// → "<table>...</table>"

Or pick the ones you actually want:

val cfg = MarkdownConfig.default.copy(
  tables          = true,
  strikethrough   = true,
  taskListItems   = true,
  autoHeadingIds  = true,
)

renderToHTML("## Hello, World!", cfg)
// → <h2 id="hello-world">Hello, World!</h2>

The full list of flags lives on the Options page.

Where to go next

Concepts → AST — the node hierarchy you walk after parsing.
Concepts → Rendering — escape rules, raw-HTML pass-through, custom highlighters.
Reference → API — every public function, signature, and return type.
Recipes → Custom renderer — turn the AST into your own format.

Parsing

2026-05-12T21:20:17.378753286Z

The parser is structured as a pipeline. Each stage has one job and produces input for the next:

String
   │
   ▼  InputReader
LazyList[C]                    cursors carrying char + position + isLiteral
   │
   ▼  groupIntoLines
LazyList[List[C]]              one list per line, with leading tabs expanded
   │
   ▼  block parsers (priority-ordered registry)
List[Block]                    blocks containing raw List[Inline] of cursors
   │
   ▼  processInlines
Document                       inlines resolved, entities decoded, link refs bound

1. Input normalization

new InputReader(input) produces the cursor stream LazyList[C]. Each C carries a single character plus its source position, line, column, and an isLiteral flag (true if the character was backslash-escaped). The reader normalizes line endings (CR / CRLF → LF) and replaces null with U+FFFD. Backslash escapes of ASCII punctuation are resolved here — the escaped character gets isLiteral = true so downstream parsers know not to treat it as syntax.

You won’t usually call InputReader directly; parseDocumentContent wraps it.

2. Line grouping

groupIntoLines chunks the cursor stream into lines. It uses LazyList.unfold to stay lazy, and expandLeadingTabs to expand tabs to spaces in leading whitespace only (CommonMark requires column-based indent semantics).

3. Block parsing

Block parsers form a priority-ordered registry. For each line, the parser walks the registry calling canStart() then parse() on each entry. Whichever parser claims the line consumes one or more lines and returns a Block. Returning zero lines means “not me, try the next parser.” Returning a null block means “I consumed lines but produced no output” — the only parser that does this is LinkReferenceDefinitionParser, which accumulates link reference definitions into a side table for later resolution.

Priority order (top wins):

LinkReferenceDefinitionParser — [label]: dest "title"
ThematicBreakBlockParser — ***, ---, ___
ListBlockParser — unordered (-, +, *) and ordered (1., 1))
IndentedCodeBlockParser — 4+ space indent
SetextHeadingBlockParser — looks ahead for === or --- underline
ATXHeadingBlockParser — #–######
HTMLBlockParser — types 1–7 per CommonMark §4.6
TableBlockParser — GFM tables (requires tables)
CollapsibleBlockParser — ::: title … :::
DefinitionListBlockParser — term + : definition (requires definitionLists)
FencedCodeBlockParser — ``` or ~~~
MathBlockParser — $$ fences (requires math)
CalloutBlockParser — > [!TYPE] admonitions (requires callouts)
BlockQuoteParser — > prefixed blocks with lazy continuation
ParagraphBlockParser — fallback, absorbs continuation lines until interrupted

The fallback at the end is critical: anything not claimed by an earlier parser becomes a Paragraph. ParagraphBlockParser‘s notion of when it gets interrupted by a later block construct (ATX heading, thematic break, HTML block 1–6, fence, blockquote, list-that-can-interrupt, math block) is what makes the spec’s “no blank line needed” rules work.

4. Inline parsing

After the block tree is built, processInlines(linkRefs, config) is called on the Document. It walks every block recursively and calls parseInline on the List[Inline] it finds.

parseInline is a single-pass algorithm operating on a doubly-linked list. Its main loop checks each C cursor against a fixed set of trigger characters in spec-defined precedence order:

Char	Triggers	Guarded by
`	code spans (highest precedence)	always on
`:`	emoji shortcodes	`emoji != Disabled`
`$`	inline math	`math`
`<`	autolinks and raw HTML tags	always on
`*`, `_`	emphasis / strong (deferred via delimiter stack)	always on
`~`	strikethrough (delimiter stack)	`strikethrough`
`[`	link / image opener	always on
`]`	link / image closer	always on
`\n`	hard or soft line break	always on
`h`, `w`	extended autolinks (bare URLs)	`extendedAutolinks`

After the main loop, processEmphasis walks the delimiter stack and resolves emphasis pairs using the CommonMark “rule of 3” (isValidEmphasisPair). Then consolidateCharacters merges adjacent C cursors into Text nodes, and decodeHtmlEntities resolves named, decimal, and hex entity references.

5. Link references

Link reference definitions are accumulated during block parsing into an immutable.Map[String, LinkReference]. They’re passed into processInlines, where lookForLinkOrImage consults them when resolving full reference ([text][label]), collapsed reference ([text][]), and shortcut reference ([text]) link forms — in addition to inline [text](url).

Labels are normalized via Unicode case-folding (toLowerCase plus ß → ss) and whitespace collapsing before comparison.

What you actually call

import io.github.edadma.markdown.*

// Most common:
val html: String     = renderToHTML(md, config)
val doc:  Document   = parseDocumentContent(md, config)

// Need the link reference table back? (e.g. for cross-document analysis)
val (doc2, refs) = parseDocumentContentWithRefs(md, config)

See Reference → API for every entry point with full signatures.

Options

2026-05-12T21:20:17.378753286Z

MarkdownConfig is the single source of truth for parser and renderer behaviour. Construct one explicitly, or copy MarkdownConfig.default (pure CommonMark) or MarkdownConfig.all (every extension on).

Prefabs

Value	Meaning
`MarkdownConfig.default`	Pure CommonMark. No extensions. Predictable spec-only output.
`MarkdownConfig.all`	Every boolean extension on; `emoji = Unicode`; `autoHeadingIds = true`.

Full reference

Option	Type	Default	Notes
`tables`	`Boolean`	`false`	GFM-style pipe tables.
`definitionLists`	`Boolean`	`false`	`Term\n: defn` style definition lists.
`math`	`Boolean`	`false`	`$$…$$` block math, $…$ inline math.
`callouts`	`Boolean`	`false`	`> [!TYPE]` admonition blocks.
`strikethrough`	`Boolean`	`false`	GFM `~~strikethrough~~`.
`taskListItems`	`Boolean`	`false`	GFM `- [ ]` / `- [x]` checkbox list items.
`extendedAutolinks`	`Boolean`	`false`	Bare URL / `www.` autolinks (no `<>` brackets needed).
`footnotes`	`Boolean`	`false`	`[^label]` references with `[^label]: …` definitions.
`smartPunctuation`	`Boolean`	`false`	Curly quotes, en/em-dashes, ellipsis.
`attributes`	`Boolean`	`false`	`{#id .class key=value}` on headings, fenced blocks, images.
`autoHeadingIds`	`Boolean`	`false`	Auto-populate heading `id`s. Explicit ids (via `attributes`) win.
`slugify`	`String => String`	`defaultSlugify`	Slug function used by `autoHeadingIds`.
`emoji`	`EmojiConfig`	`Disabled`	`Disabled` / `Unicode` / `Image(baseURL)`.
`docTags`	`DocTagConfig`	`disabled`	`@name [target] — body` annotation parsing.
`codeHighlighter`	`Option[(String, String) => Option[String]]`	`None`	Pluggable code-block syntax highlighter.
`indentedCodeLanguage`	`Option[String]`	`None`	Default language tag applied to indented code blocks.
`indentedCodeBreaksList`	`Boolean`	`false`	If true, an indented code block after a blank line ends the enclosing list item instead of being absorbed.

`EmojiConfig`

enum EmojiConfig:
  case Disabled
  case Unicode
  case Image(baseURL: String)

Unicode substitutes the Unicode glyph (e.g. :smile: → 😄). Image("/emoji") substitutes <img src="/emoji/smile.svg" alt=":smile:" /> — the baseURL is prefixed verbatim.

`slugify`

Default behaviour (MarkdownConfig.defaultSlugify):

lowercase the input
collapse runs of non-alphanumeric characters into a single -
strip leading and trailing -
return "" if the input has no letter/digit content

Same algorithm Hugo, mkdocs, and GitHub use. Override when your URL scheme differs:

val cfg = MarkdownConfig.default.copy(
  autoHeadingIds = true,
  slugify = s => s.toLowerCase.replaceAll("[^a-z0-9]+", "_").stripPrefix("_").stripSuffix("_"),
)

`codeHighlighter`

codeHighlighter: Option[(String, String) => Option[String]]

The function receives the raw code body and the language tag (from the info string, or from indentedCodeLanguage for indented blocks). Return Some(html) to inject custom HTML inside <code>…</code>; return None to fall back to the default <pre><code>{escaped}</code></pre> output.

The renderer does not escape your highlighter’s output — it’s assumed to be valid HTML already.

`DocTagConfig`

case class DocTagConfig(
  enabled:           Boolean      = false,
  registry:          TagRegistry  = TagRegistry.empty,
  strictUnknownTags: Boolean      = false,
)

See Extensions → Doc-tags for the integration model and a full example.

Worked configurations

“Hugo-flavoured”: tables, autolinks, smart quotes, heading ids

val cfg = MarkdownConfig.default.copy(
  tables             = true,
  extendedAutolinks  = true,
  smartPunctuation   = true,
  autoHeadingIds     = true,
)

“Obsidian-flavoured”: callouts, footnotes, math, tables

val cfg = MarkdownConfig.default.copy(
  tables    = true,
  callouts  = true,
  footnotes = true,
  math      = true,
)

“GFM-flavoured”: tables, strikethrough, task lists, autolinks

val cfg = MarkdownConfig.default.copy(
  tables             = true,
  strikethrough      = true,
  taskListItems      = true,
  extendedAutolinks  = true,
)

Everything

val cfg = MarkdownConfig.all

Juicer integration

2026-05-12T21:20:17.378753286Z

Juicer is a Hugo-style static site generator written in Scala 3. It uses this library as its sole markdown engine — meaning every .md file under your site’s content/ tree is parsed and rendered by exactly the code documented here.

Where it sits

Juicer’s pipeline is roughly:

content/*.md → frontmatter parse → parseDocumentContent (this library) → template render → HTML files

The Document AST is exposed to templates as .page.content (rendered HTML) and via individual heading / TOC accessors. Juicer also walks the AST to:

build per-page tables of contents from Document.headings;
generate stable URL slugs via autoHeadingIds + the configured slugify;
produce the search index (search.json) from plainText(...) of each page;
detect link reference targets across the content tree.

Configuration

Juicer’s site-level config exposes the relevant MarkdownConfig flags directly. From a site.toml:

[markdown]
tables             = true
strikethrough      = true
taskListItems      = true
extendedAutolinks  = true
smartPunctuation   = true
autoHeadingIds     = true

Those keys map 1-to-1 onto fields of MarkdownConfig. Flags not listed default to false (pure CommonMark). See Options for the full set.

Code highlighting

Juicer wires codeHighlighter to its bundled highlighter library. Authoring a fenced block with a known language tag picks up syntax highlighting automatically; with no tag (or an unknown one), you get plain <pre><code>.

Shortcodes

Juicer adds an extra layer above this library — its [= shortcode =]…[= /shortcode =] syntax is processed before markdown parsing. The result of expanding a shortcode is markdown text that this library then parses normally. So shortcodes don’t change the spec compliance of the underlying parse.

Cross-linking

Juicer treats unresolved markdown links as the SSG’s job, not the parser’s. A [Page](page-slug) in source goes through this library as a normal Link(destination = "page-slug", ...); juicer rewrites the destination at render time to whatever URL the slug resolves to in the content tree. From this library’s point of view, link resolution is purely string-level.

A minimal juicer-like loop

The skeleton of “render every .md in content/ to public/“ is just:

import io.github.edadma.markdown.*
import java.nio.file.{Files, Path, Paths}
import scala.jdk.CollectionConverters.*

val cfg = MarkdownConfig.default.copy(
  tables = true, autoHeadingIds = true, smartPunctuation = true,
)

Files.walk(Paths.get("content")).iterator.asScala
  .filter(p => p.toString.endsWith(".md"))
  .foreach { src =>
    val md   = Files.readString(src)
    val html = renderToHTML(md, cfg)
    val out  = Paths.get("public", src.getFileName.toString.replace(".md", ".html"))
    Files.createDirectories(out.getParent)
    Files.writeString(out, html)
  }

Real SSGs add frontmatter parsing, templating, asset copying, and a full link-resolution pass — but the parseDocumentContent / renderToHTML pair is the unchanged core of the markdown step. The rest is plumbing.

Installation

2026-05-12T21:20:17.378753286Z

Scala (sbt)

libraryDependencies += "io.github.edadma" %%% "markdown" % "0.4.3"

The %%% form picks the right artifact for whichever Scala platform you’re on — JVM, Scala.js, or Scala Native — so the same line works in any cross-built project.

import io.github.edadma.markdown.*

val html = renderToHTML("# Hello, CommonMark!")
// → "<h1>Hello, CommonMark!</h1>\n"

The package object exposes everything via io.github.edadma.markdown.*. There’s no other namespace to learn.

JavaScript / TypeScript (npm)

The Scala.js build is also published as an npm package, with TypeScript typings:

npm install @edadma/markdown

import { renderToHTML, extractHeadings, plainText } from "@edadma/markdown"

renderToHTML("# Hello", { autoHeadingIds: true })
//// → '<h1 id="hello">Hello</h1>'

extractHeadings("# Intro\n## Setup")
//// → [{ level: 1, text: "Intro", id: "intro" },
////    { level: 2, text: "Setup", id: "setup" }]

The npm bundle’s exact API surface lives in npm/README.md inside the repo.

From source

git clone https://github.com/edadma/markdown.git
cd markdown
sbt test                                              # all tests, all platforms# all tests, all platforms
sbt 'project markdownJVM' test                        # JVM only
sbt 'project markdownJS' test                         # JS (Node 20+)
sbt 'project markdownNative' test                     # Scala Native

The aggregate sbt test runs the full 652-test CommonMark spec on every platform plus the unit tests.

Cross-build matrix

Target	Version	Runtime requirement
Scala	3.8.3	—
JVM	—	Java 17 or newer
Scala.js	1.21.0	Node.js 20+
Scala Native	0.5.11	Clang
CommonMark spec	0.31.2	—

Verifying the install

import io.github.edadma.markdown.*

@main def smoke(): Unit =
  println(renderToHTML("**hello**"))
  // <p><strong>hello</strong></p>

If you see the <strong> tag, you’re done. Move on to the Quickstart for a tour of the API surface most callers actually use.

Extensions

2026-05-12T21:20:17.378753286Z

CommonMark itself is conservative: anything not in the spec is off by default. The library ships every popular extension as a flag on MarkdownConfig. Set MarkdownConfig.all to turn them all on at once, or copy the default and enable just what you need.

Tables (`tables`)

GFM-style pipe tables. Header row, separator row, body rows. Per-column alignment via :---, :---:, ---:.

| Name     | Status |
|----------|:------:|
| ready    |   ✓    |
| pending  |   …    |

Strikethrough (`strikethrough`)

GFM ~~text~~ renders to <del>text</del>. Two-tilde delimiters; a single ~ does nothing.

This is ~~deleted~~ text.

Task list items (`taskListItems`)

GFM - [ ] and - [x] (or - [X]) at the start of a list item render with a disabled checkbox. Works in both ordered and unordered lists.

- [x] write docs
- [ ] ship docs

Extended autolinks (`extendedAutolinks`)

Bare URLs and www.-prefixed hostnames become links without <> brackets:

visit https://example.com or www.example.com

Footnotes (`footnotes`)

[^label] references with [^label]: … definitions. References are renumbered in document order; definitions are collected and emitted as a <section class="footnotes"> at the end of the document, with backrefs.

Here is a claim.[^src]

[^src]: Source: *The Big Book of Claims*, p. 42.

Math (`math`)

Block math with $$…$$ fences and inline math with $…$ . Renders to <div class="math display">\[…\]</div> and <span class="math inline">$…$</span> — pair with KaTeX or MathJax client-side.

The Pythagorean theorem: $a^2 + b^2 = c^2$.

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

This site has KaTeX wired up (juicerdocs theme, [juicerdocs] math = true in site.toml), so the same source above renders as:

The Pythagorean theorem: $a^2 + b^2 = c^2$.

\[\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}\]

A few more shapes — quadratic formula, a matrix, a sum, and a limit:

\[x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\]

\[A = \begin{pmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{pmatrix}\]

\[\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}\]

\[\lim_{x \to 0} \frac{\sin x}{x} = 1\]

Callouts (`callouts`)

Obsidian / GFM admonition syntax: a blockquote whose first line is [!TYPE] or [!TYPE] Title. Common types: note, tip, info, warning, danger.

> [!warning] Heads up
> This kills the build.

Renders as <div class="callout callout-warning">…</div> with a <div class="callout-title"> for the title and <div class="callout-content"> for the body.

Smart punctuation (`smartPunctuation`)

"..." becomes “…”, '...' becomes ‘…’, -- becomes – (en-dash), --- becomes — (em-dash), ... becomes … (ellipsis). Off by default to keep CommonMark output character-for-character predictable.

Attributes (`attributes`)

{#id .class key=value} after a heading, fenced code block, or image populates the node’s Attributes value. Multiple classes and arbitrary key-value pairs are supported.

## Hello {#hello-id .lead key="some value"}

![alt](/img.png){.figure width=400}

```scala {#example1 .runnable}
val x = 42


## Auto heading IDs (`autoHeadingIds`)

Every heading gets an `id` attribute generated from its plain-text content via `slugify`. Default algorithm: lowercase, runs of non-alphanumerics → `-`, strip leading/trailing `-`. Same algorithm Hugo, mkdocs, and GitHub use.

```scala
val cfg = MarkdownConfig.default.copy(autoHeadingIds = true)
renderToHTML("## Hello, World!", cfg)
// → <h2 id="hello-world">Hello, World!</h2>

Plug in a custom slug function:

val cfg = MarkdownConfig.default.copy(
  autoHeadingIds = true,
  slugify = s => s.toLowerCase.replaceAll("[^a-z0-9]+", "_").stripPrefix("_").stripSuffix("_"),
)

Explicit ids set via the attributes extension (## Heading {#explicit}) always win.

Emoji (`emoji`)

Three modes:

Config	Behavior
`EmojiConfig.Disabled`	`:smile:` is left as text.
`EmojiConfig.Unicode`	`:smile:` becomes `😄`.
`EmojiConfig.Image(baseURL)`	`:smile:` becomes `<img src="{baseURL}/smile.svg" />`.

The shortcode set is the standard GitHub / Slack list.

Definition lists (`definitionLists`)

A term followed by one or more : definition lines:

Term
: A succinct definition.
: Another sense of the term.

Renders to <dl><dt>Term</dt><dd>…</dd><dd>…</dd></dl>.

Indented code language (`indentedCodeLanguage`)

Indented code blocks (4-space) carry no language tag in CommonMark. Set indentedCodeLanguage = Some("scala") (or any other) to default them to a language for highlighting:

val cfg = MarkdownConfig.default.copy(
  indentedCodeLanguage = Some("scala"),
  codeHighlighter      = Some(myHighlighter),
)

Indented code breaks list (`indentedCodeBreaksList`)

A subtle one. CommonMark says an indented code block following a blank line inside a list item is absorbed into the list item. Set indentedCodeBreaksList = true to make the indented code block instead end the enclosing list item. Useful when you’re using indented blocks as section breaks rather than list-internal code.

Doc-tags (`docTags`)

Block-level @name [target] — body annotations. Designed for documentation tools built on top of the AST. The processor parses the syntax and renders a sensible default (<dl class="doc-tag doc-tag-{name}">); binding tags to code declarations and resolving cross-references is the downstream tool’s job.

import io.github.edadma.markdown.*

val registry = TagRegistry(
  TagDefinition("api",     acceptsTarget = false, ContentMode.InlineMarkdown),
  TagDefinition("param",   acceptsTarget = true,  ContentMode.InlineMarkdown),
  TagDefinition("example", acceptsTarget = false, ContentMode.BlockMarkdown),
)

val cfg = MarkdownConfig.default.copy(
  docTags = DocTagConfig(enabled = true, registry = registry),
)

renderToHTML("@param msg — the error message\n", cfg)

ContentMode controls how each tag’s body is parsed:

Mode	Body is
`Opaque`	a single `Text` node, not parsed
`InlineMarkdown`	parsed by the inline parser only (becomes one `Paragraph`)
`BlockMarkdown`	parsed by the block parser (arbitrary block content)

strictUnknownTags = true causes unknown tag names to fall back to ordinary text. With the default (false), unknown tags are still emitted as DocTagBlock with acceptsTarget = true and InlineMarkdown mode — convenient for forward-compatible doc pipelines.

Combined: everything on

val cfg = MarkdownConfig.all
//                              ^ tables, math, callouts, strikethrough, taskListItems,
//                                extendedAutolinks, footnotes, smartPunctuation,
//                                attributes, definitionLists, autoHeadingIds, emoji=Unicode

Note that MarkdownConfig.all does not turn on docTags or set codeHighlighter / indentedCodeLanguage / indentedCodeBreaksList — those need explicit configuration values, not just a boolean.

Embedding the parser

2026-05-12T21:20:17.378753286Z

The library has zero runtime third-party dependencies, and the same line in build.sbt works on every platform. Embedding it in an existing app is a one-import change.

1. Add the dependency

libraryDependencies += "io.github.edadma" %%% "markdown" % "0.4.3"

The %%% form picks the right artifact for whichever Scala platform you’re on.

2. Pick a config that fits your audience

Three common shapes:

import io.github.edadma.markdown.*

// User comments, support tickets — predictable, no surprises.
val commentCfg = MarkdownConfig.default

// Knowledge base / wiki — table-heavy, link-heavy, anchor-heavy.
val wikiCfg = MarkdownConfig.default.copy(
  tables            = true,
  extendedAutolinks = true,
  autoHeadingIds    = true,
  smartPunctuation  = true,
)

// Author-facing docs / notes — full Obsidian / Hugo flavour.
val docsCfg = MarkdownConfig.all

There’s no global config. Pass the one you want at every call site, or store one per-context.

3. Render

class CommentService:
  def renderComment(body: String): String =
    renderToHTML(body, commentCfg)

That’s the full integration for the simple case.

4. Cache the parsed AST when it pays

For server-side rendering of frequently re-rendered content (a comment loaded a thousand times, a doc page hit on every request), cache the Document rather than the rendered HTML — it’s smaller and the rendering step is cheap.

import io.github.edadma.markdown.*

class CachedRenderer(cfg: MarkdownConfig):
  private val cache = scala.collection.mutable.HashMap.empty[String, Document]

  def render(key: String, body: => String): String =
    val doc = cache.getOrElseUpdate(key, parseDocumentContent(body, cfg))
    renderToHTML(doc, cfg)

Invalidation strategy is your problem; the library is referentially transparent over (input, config).

5. Preserve link references across documents

Cross-document analysis (a wiki where [Page] resolves against another file’s link reference table) needs the references separately:

val (doc, refs) = parseDocumentContentWithRefs(body, cfg)

refs: Map[String, LinkReference] carries every [label]: dest "title" that appeared in the source. Hold them in your store; merge across files at render time as you see fit.

6. Sanitization

The library does not sanitize. RawHTML and HTMLBlock pass through verbatim — that’s the CommonMark contract. If you’re rendering untrusted input, run the output through a sanitizer (jsoup’s Cleaner, OWASP HTML Sanitizer, DOMPurify on the JS side) after rendering.

You could also walk the AST and remove raw-HTML nodes before rendering — see Custom renderer for the walker pattern.

7. Cross-platform notes

The same code runs on JVM, Scala.js (Node 20+), and Scala Native. The only platform-specific concern is filesystem I/O (cross_platform.readFile / writeFile), which is exposed by a sister library if you need it.

For the JS side specifically, the published @edadma/markdown npm bundle gives you the same API as direct Scala-from-Scala.js consumption — pick whichever surface fits your stack.

Writing a custom renderer

2026-05-12T21:20:17.378753286Z

The built-in renderers are not magic. renderToHTML and renderToXML are pattern matches over Block and Inline. To target a different format, you write the same shape of pattern match for your output.

The walker pattern

Every Block either holds child blocks (BlockQuote, ListBlock, …) or a List[Inline] (Paragraph, Heading, …). Every Inline either holds child inlines (Emphasis, Strong, Link, …) or carries a leaf value (Text, CodeSpan, …). You walk recursively.

Example: a plain-text dumper

A renderer that emits exactly what plainText gives you for inlines, but with sensible block-level whitespace:

import io.github.edadma.markdown.*

def renderToText(node: Node): String =
  val out = new StringBuilder

  def block(b: Block): Unit = b match
    case Paragraph(inlines)              => inlines.foreach(inline); out += '\n'; out += '\n'
    case Heading(level, inlines, _)      =>
      out ++= "#" * level; out += ' '
      inlines.foreach(inline); out += '\n'; out += '\n'
    case Code(content, _, _, _)          => out ++= content; out += '\n'; out += '\n'
    case BlockQuote(children)            => children.foreach(b => { out ++= "> "; block(b) })
    case ThematicBreak()                 => out ++= "----\n\n"
    case ListBlock(data, items)          =>
      items.zipWithIndex.foreach { case (item, i) =>
        out ++= (if data.isOrdered then s"${i + 1}. " else "- ")
        item.content.foreach(block)
      }
    case HTMLBlock(c)                    => out ++= c; out += '\n'
    case _                               => () // table / callout / footnote / etc.

  def inline(i: Inline): Unit = i match
    case Text(c)                  => out ++= c
    case SoftLineBreak()          => out += ' '
    case HardLineBreak()          => out += '\n'
    case CodeSpan(c)              => out += '`'; out ++= c; out += '`'
    case Emphasis(xs)             => xs.foreach(inline)
    case Strong(xs)               => xs.foreach(inline)
    case Strikethrough(xs)        => xs.foreach(inline)
    case Link(_, _, xs)           => xs.foreach(inline)
    case Image(_, _, xs, _)       => xs.foreach(inline)
    case AutoLink(_, text)        => out ++= text
    case _                        => ()

  node match
    case Document(children) => children.foreach(block)
    case b: Block           => block(b)
    case i: Inline          => inline(i)

  out.toString

Use it:

val md = "# Title\n\nA paragraph with **bold**.\n"
val txt = renderToText(parseDocumentContent(md))
// → "# Title\n\nA paragraph with bold.\n\n"

Example: terminal ANSI

The same pattern with ANSI escape sequences instead of HTML tags. Just substitute the inline cases:

case Strong(xs)        => out ++= "[1m"; xs.foreach(inline); out ++= "[22m"
case Emphasis(xs)      => out ++= "[3m"; xs.foreach(inline); out ++= "[23m"
case CodeSpan(c)       => out ++= "[7m"; out ++= c; out ++= "[27m"
case Link(_, _, xs)    => out ++= "[4m"; xs.foreach(inline); out ++= "[24m"

Same for headings (use bright color + bold), code blocks (block-level reverse-video), thematic breaks (a row of ─).

Filtering before rendering

Walking the AST also lets you transform it before rendering. Strip raw HTML for safety, demote heading levels, rewrite link destinations:

def stripRawHtml(doc: Document): Document =
  def b(block: Block): Block = block match
    case HTMLBlock(_)               => Paragraph(Nil)            // drop it
    case Paragraph(inlines)         => Paragraph(inlines.filterNot(_.isInstanceOf[RawHTML]))
    case Heading(l, inlines, a)     => Heading(l, inlines.filterNot(_.isInstanceOf[RawHTML]), a)
    case BlockQuote(children)       => BlockQuote(children.map(b))
    case ListBlock(data, items)     => ListBlock(data, items.map(it => ListItem(it.content.map(b))))
    case other                      => other
  Document(doc.children.map(b))

val safe = renderToHTML(stripRawHtml(parseDocumentContent(input)), MarkdownConfig.default)

This is not a substitute for a real HTML sanitizer — emphasis text can still contain dangerous URLs in Link destinations, etc. But it’s the right shape when your goal is “this AST is what I want, render it the normal way.”

Reusing the built-in inline renderer

If you want to keep the built-in inline rendering and only change block-level output, call renderInlines directly:

def myCustomBlock(b: Block): String = b match
  case Heading(level, inlines, _) => s"<my-h$level>${renderInlines(inlines)}</my-h$level>"
  case Paragraph(inlines)         => s"<my-p>${renderInlines(inlines)}</my-p>"
  case other                      => renderBlockToHTML(other)   // fall back

That gives you “HTML, but the wrappers I want” for free.

Reaching into `processInlines`

If you build Block values programmatically — e.g. you constructed a Heading(2, List(C(...)), None) from a non-markdown source — and want to re-resolve the inline content, call node.processInlines(linkRefs, config):

val raw  = Heading(2, List(/* C cursors */), None)
val done = raw.processInlines(Map.empty, MarkdownConfig.default)

This is rarely needed in practice. parseDocumentContent always returns a fully-resolved document.

AST

2026-05-12T21:20:17.378753286Z

The AST is a small set of case classes organized into three families. Document is the root; it holds a list of Blocks; each block holds either child blocks or a list of Inlines.

The hierarchy

Node (trait)
├── Document
│   └── children: List[Block]
│
├── Block (trait) — anything that can appear at document or list-item level
│   ├── Paragraph(inlines)
│   ├── Heading(level, inlines, attrs?)
│   ├── Code(content, infoString?, indented, attrs?)
│   ├── BlockQuote(children)
│   ├── ThematicBreak
│   ├── HTMLBlock(content)
│   ├── ListBlock(data: ListData, items: List[ListItem])
│   │   └── ListItem(content: List[Block])
│   ├── Table(headerRow, rows, alignments)
│   │   ├── TableRow(cells)
│   │   └── TableCell(content)
│   ├── DefinitionListBlock(items: List[(term, defs)])
│   ├── MathBlock(content)
│   ├── CalloutBlock(calloutType, title?, children)
│   ├── CollapsibleBlock(title, isOpen, children)
│   ├── FootnoteDefinition(label, content)
│   └── DocTagBlock(name, target?, body, contentMode)
│
└── Inline (trait) — anything that can appear inside a paragraph / heading
    ├── Text(content)
    ├── SoftLineBreak
    ├── HardLineBreak
    ├── CodeSpan(content)
    ├── Emphasis(inlines)
    ├── Strong(inlines)
    ├── Strikethrough(inlines)
    ├── Link(destination, title?, inlines)
    ├── Image(destination, title?, inlines, attrs?)
    ├── AutoLink(destination, text)
    ├── RawHTML(content)
    ├── MathExpr(content)
    ├── Emoji(name)
    ├── FootnoteReference(label)
    └── C(char, pos, line, column, isLiteral)

C is the cursor type used during parsing — you’ll only see it inside Inline lists before the inline parser has run. After parseDocumentContent, every C has been folded into Text. You won’t encounter one in normal use.

`Document`

case class Document(children: List[Block]) extends Node {
  def headings: List[Heading]
}

headings is a convenience accessor — children.collect { case h: Heading => h }. Useful for table-of-contents builders, page-title extraction, anchor generators.

Block nodes

Node	Carries	Renders to
`Paragraph`	`inlines: List[Inline]`	`<p>…</p>`
`Heading`	`level: Int`, `inlines`, `attrs: Option[Attributes]`	`<h1>` … `<h6>`
`Code`	`content: String`, `infoString: Option[String]`, `indented: Boolean`, `attrs`	`<pre><code class="language-…">`
`BlockQuote`	`children: List[Block]`	`<blockquote>…</blockquote>`
`ThematicBreak`	—	`<hr />`
`HTMLBlock`	`content: String`	passed through verbatim
`ListBlock`	`data: ListData`, `items: List[ListItem]`	`<ul>` / `<ol>` with `<li>` children
`Table`	`headerRow`, `rows`, `alignments`	`<table>` (when `tables` is on)
`DefinitionListBlock`	`items: List[(term, defs)]`	`<dl><dt>…<dd>…`
`MathBlock`	`content: String`	`<div class="math display">\\[…\\]</div>`
`CalloutBlock`	`calloutType`, `title?`, `children`	`<div class="callout callout-…">`
`CollapsibleBlock`	`title`, `isOpen`, `children`	`<details><summary>…</summary>…`
`FootnoteDefinition`	`label`, `content`	renumbered, emitted at end of document
`DocTagBlock`	`name`, `target?`, `body`, `contentMode`	`<dl class="doc-tag doc-tag-…">`

ListData carries isOrdered, bulletChar, startNumber, delimiter, isTight, and indent. It’s how the renderer knows whether to emit <ul> or <ol start="N"> and whether items are tight (no <p> wrappers) or loose.

Inline nodes

Node	Carries	Renders to
`Text`	`content: String`	escaped text
`SoftLineBreak`	—	a literal newline
`HardLineBreak`	—	`<br />`
`CodeSpan`	`content: String`	`<code>…</code>`
`Emphasis`	`inlines: List[Inline]`	`<em>…</em>`
`Strong`	`inlines: List[Inline]`	`<strong>…</strong>`
`Strikethrough`	`inlines: List[Inline]`	`<del>…</del>`
`Link`	`destination`, `title?`, `inlines`	`<a href="…">…</a>`
`Image`	`destination`, `title?`, `inlines`, `attrs?`	`<img src="…" alt="…" />`
`AutoLink`	`destination`, `text`	`<a href="…">…</a>`
`RawHTML`	`content: String`	passed through verbatim
`MathExpr`	`content: String`	`<span class="math inline">\$…\$</span>`
`Emoji`	`name: String`	Unicode glyph or `<img>` (per `EmojiConfig`)
`FootnoteReference`	`label: String`	`<sup class="footnote-ref"><a>N</a></sup>`

Auxiliary types

case class Attributes(
  id:       Option[String]      = None,
  classes:  List[String]        = Nil,
  kvPairs:  Map[String, String] = Map.empty,
)

case class LinkReference(destination: String, title: Option[String])

case class ListData(
  isOrdered:   Boolean,
  bulletChar:  Option[Char] = None,
  startNumber: Option[Int]  = None,
  delimiter:   Option[Char] = None,
  isTight:     Boolean      = true,
  indent:      Int,
)

enum TableAlignment:
  case Left, Center, Right, None

enum ContentMode:
  case Opaque         // body stored as a single Text node, no inline parsing
  case InlineMarkdown // body parsed with the inline parser
  case BlockMarkdown  // body parsed with the block parser

Attributes is populated from the attributes extension ({#id .class key=value} after a heading, image, or fenced block) and from autoHeadingIds.

The `processInlines` step

Block parsing produces blocks whose inline content is still a raw List[Inline] of C cursors and the Inlines the block-level parsers were able to identify (e.g. raw HTML in HTML blocks). After all blocks are parsed, the parser walks the document calling node.processInlines(linkRefs, config) on every node, which:

runs the inline parser to build Emphasis / Strong / Link / etc. trees;
consolidates runs of C cursors into single Text nodes;
decodes HTML entities and resolves link references against the accumulated linkRefs table;
assigns id attributes to headings if autoHeadingIds is on.

parseDocumentContent wraps this for you. You only need to know it exists if you’re building blocks programmatically and want them re-resolved. See Parsing for the pipeline.

API

2026-05-12T21:20:17.378753286Z

All public functions live in the package object — import io.github.edadma.markdown.* and you have everything below.

Parsing

Function	Returns	Notes
`parseDocumentContent(input, config?)`	`Document`	Most common entry point. Throws away the link reference table.
`parseDocumentContentWithRefs(input, config?)`	`(Document, Map[String, LinkReference])`	Use when you need the link references for cross-document analysis.
`parseDocument(stream, config?)`	`(Document, Map[String, LinkReference])`	Lower level — takes a `LazyList[C]` from `InputReader`.

def parseDocumentContent(
    input:  String,
    config: MarkdownConfig = MarkdownConfig.default,
): Document

def parseDocumentContentWithRefs(
    input:  String,
    config: MarkdownConfig = MarkdownConfig.default,
): (Document, Map[String, LinkReference])

def parseDocument(
    stream: LazyList[C],
    config: MarkdownConfig = MarkdownConfig.default,
): (Document, Map[String, LinkReference])

HTML rendering

Function	Returns	Notes
`renderToHTML(md: String, config?)`	`String`	Parse + render. The one-line case.
`renderToHTML(node: Node, config?)`	`String`	Render an existing AST. Errors if `node` is an inline.
`renderBlockToHTML(node: Block, config?)`	`String`	Render a single block — without the trailing newline `renderToHTML` adds.
`renderInlines(inlines: List[Inline])`	`String`	Render inline content with no surrounding `<p>`.
`plainText(inlines, escape: Boolean = false)`	`String`	Strip all formatting. `escape=true` runs the result through `escapeXml`.

def renderToHTML(md:   String, config: MarkdownConfig = MarkdownConfig.default): String
def renderToHTML(node: Node):                                                      String
def renderToHTML(node: Node,   config: MarkdownConfig):                            String

def renderBlockToHTML(node: Block, config: MarkdownConfig = MarkdownConfig.default): String

def renderInlines(inlines: List[Inline]):                              String
def plainText   (inlines: List[Inline], escape: Boolean = false):      String

XML rendering

Function	Returns	Notes
`renderToXML(doc: Document, system?)`	`String`	Emits CommonMark XML format with `<?xml … ?>` declaration and DTD. Headings rendered as plain text.
`escapeXml(s: String)`	`String`	Encodes `&`, `<`, `>`, `"`. Used internally; exposed for renderer authors.

def renderToXML(doc: Document, system: String = "document"): String
def escapeXml  (s: String):                                  String

URL helpers

Function	Returns	Notes
`percentEncode(input: String)`	`String`	URI percent-encoding. Treats `%` as already-safe to avoid double-encoding pre-encoded URLs.

AST walking helpers

Function	Returns	Notes
`Document.headings`	`List[Heading]`	All top-level `Heading` blocks, in source order.
`extractHeaders(doc: Document)`	`List[(Int, String)]`	`(level, plain-text-content)` pairs.
`inlinesToPlainText(inlines: List[Inline])`	`String`	Lighter alternative to `plainText` — drops only `Text`, `CodeSpan`, `Emphasis`, `Strong`, and bare `C` cursors.
`plainText(inlines, escape?)`	`String`	Recommended. Handles every inline type and strips images, links, math, etc., to their text content.

def extractHeaders(document: Document):       List[(Int, String)]
def inlinesToPlainText(inlines: List[Inline]): String

Input layer

You’ll rarely call these directly — parseDocumentContent wraps them — but they’re public for renderer / formatter authors:

Function	Returns	Notes
`new InputReader(input).stream`	`LazyList[C]`	The cursor stream. Normalizes line endings and resolves backslash escapes.
`rawText(cursors: List[C])`	`String`	Reconstruct source text, restoring backslashes for literal-flagged characters. Used by code-block parsers.
`expandLeadingTabs(line, startCol = 0)`	`List[C]`	Expand tabs to spaces in leading whitespace only.
`virtualIndent(line: List[C])`	`Int`	Tab-aware indent count of a line.
`dropIndent(line, n, startCol = 0)`	`List[C]`	Remove `n` columns of (tab-aware) leading indent.

Config

MarkdownConfig is one big case class with one copy constructor. Two prefab values:

Value	Meaning
`MarkdownConfig.default`	Pure CommonMark — no extensions enabled.
`MarkdownConfig.all`	Every extension enabled.

See Options for the per-flag table.

Doc-tag extension

case class TagDefinition(
  name:          String,
  acceptsTarget: Boolean,
  contentMode:   ContentMode,
)

final class TagRegistry:
  def lookup(name: String): Option[TagDefinition]
  def isEmpty:  Boolean
  def nonEmpty: Boolean
  def all:      Iterable[TagDefinition]

object TagRegistry:
  val empty: TagRegistry
  def apply(defs: TagDefinition*):           TagRegistry
  def fromList(defs: Iterable[TagDefinition]): TagRegistry

enum ContentMode:
  case Opaque, InlineMarkdown, BlockMarkdown

case class DocTagConfig(
  enabled:           Boolean      = false,
  registry:          TagRegistry  = TagRegistry.empty,
  strictUnknownTags: Boolean      = false,
)

object DocTagConfig:
  val disabled: DocTagConfig

See Extensions → Doc-tags for the integration model.

markdown

Rendering

Two entry points

Escape rules

Raw HTML

Custom code highlighting

Helpers for AST consumers

XML output

Heading IDs and slugs

Render to your own format

Quickstart

1. Render markdown to HTML

2. Parse to an AST

3. Turn on extensions

Where to go next

Parsing

1. Input normalization

2. Line grouping

3. Block parsing

4. Inline parsing

5. Link references

What you actually call

Options

Prefabs

Full reference

EmojiConfig

slugify

codeHighlighter

DocTagConfig

Worked configurations

“Hugo-flavoured”: tables, autolinks, smart quotes, heading ids

“Obsidian-flavoured”: callouts, footnotes, math, tables

“GFM-flavoured”: tables, strikethrough, task lists, autolinks

Everything

Juicer integration

Where it sits

Configuration

Code highlighting

Shortcodes

Cross-linking

A minimal juicer-like loop

Further reading

Installation

Scala (sbt)

JavaScript / TypeScript (npm)

From source

Cross-build matrix

Verifying the install

Extensions

Tables (tables)

Strikethrough (strikethrough)

Task list items (taskListItems)

Extended autolinks (extendedAutolinks)

Footnotes (footnotes)

Math (math)

Callouts (callouts)

Smart punctuation (smartPunctuation)

Attributes (attributes)

Emoji (emoji)

Definition lists (definitionLists)

Indented code language (indentedCodeLanguage)

Indented code breaks list (indentedCodeBreaksList)

Doc-tags (docTags)

Combined: everything on

Embedding the parser

1. Add the dependency

2. Pick a config that fits your audience

3. Render

4. Cache the parsed AST when it pays

5. Preserve link references across documents

6. Sanitization

7. Cross-platform notes

Writing a custom renderer

The walker pattern

Example: a plain-text dumper

Example: terminal ANSI

Filtering before rendering

Reusing the built-in inline renderer

Reaching into processInlines

AST

`EmojiConfig`

`slugify`

`codeHighlighter`

`DocTagConfig`

Tables (`tables`)

Strikethrough (`strikethrough`)

Task list items (`taskListItems`)

Extended autolinks (`extendedAutolinks`)

Footnotes (`footnotes`)

Math (`math`)

Callouts (`callouts`)

Smart punctuation (`smartPunctuation`)

Attributes (`attributes`)

Emoji (`emoji`)

Definition lists (`definitionLists`)

Indented code language (`indentedCodeLanguage`)

Indented code breaks list (`indentedCodeBreaksList`)

Doc-tags (`docTags`)

Reaching into `processInlines`

`Document`

The `processInlines` step