MDEx LMML

An MDEx plugin providing first-class support for LMML (Language Model Markup Language) fenced blocks, inline embeds, and file references.

Overview

LMML is a Markdown-superset markup language designed for LLM prompts and conversational narratives. It introduces file references (@name.ext) and named inline or external embeds (@@@name.ext ... @@@), stored as bare .lmml text narratives or packaged in .lmmlz zip archives.

MDEx LMML bridges LMML and MDEx, transforming LMML constructs in Markdown documents into rich, semantic, and highly configurable HTML output.

Key Features

lmml Fenced Code Blocks:
- ```lmml ... ``` blocks in Markdown are rendered as rich HTML narratives (or styled code blocks / conversation turn cards).
Inline Embed Blocks (@@@name.ext ... @@@):
- Block-level embed constructs are captured byte-for-byte and rendered into styled cards, collapsible <details>, or syntax-highlighted code blocks with language detection from file extensions.
File References (@name.ext):
- External file references in narrative prose (@diagram.png, @config.yaml) are transformed into links, spans, badges, or inline images.
- Automatically targets document anchors (#embed-name) when an inline embed with the matching name exists.
- Sentence punctuation (., ,, !, ?, )) trailing the asset name is cleanly preserved as prose.
- Email addresses (e.g. user@example.com) and code spans (`@ref`) are safely ignored.
Bundle Integration (Lmml.Bundle):
- Seamlessly resolves asset entries from .lmml and .lmmlz archives.
- Directly renders referenced images in bundles as Base64 data URIs.
Conversation Turn Segmentation:
- Automatically identifies role markers (## Turn 1 -- user, ) and renders distinct role cards when render_turns: true is enabled.

Installation

Add mdex_lmml and mdex to your mix.exs dependencies:

def deps do
  [
    {:mdex_lmml, "~> 0.1"},
    {:mdex, "~> 0.13"},
    {:lmml, "~> 0.2"}
  ]
end

Usage

1. With `MDEx.to_html!/2`

markdown = """
# Project Context

Please review @diagram.png before starting.

@@@settings.yaml
model: gpt-5
temperature: 0.2
@@@
"""

html = MDEx.to_html!(markdown, plugins: [MdexLmml])

2. With `MDEx.new/1` Pipeline

MDEx.new(markdown: markdown, plugins: [{MdexLmml, render_as: :span}])
|> MDEx.to_html!()

3. Fenced ```lmml … ``` Blocks in Markdown

markdown = """
Here is the interaction transcript:

```lmml
## Turn 1 -- user
Can you optimize @query.sql?

@@@settings.yaml
timeout: 5000
@@@
```
"""

html = MdexLmml.to_html!(markdown)

4. Working with `Lmml.Bundle` (.lmml / .lmmlz)

# From an in-memory Lmml.Bundle struct:
{:ok, bundle} = Lmml.Bundle.new_zip("convo.lmml", "See @chart.png", %{"chart.png" => image_bytes})
html = MdexLmml.to_html!(bundle, render_as: :embed)

# Or directly from a file path:
html = MdexLmml.to_html!("session.lmmlz")

Configuration Options

Option	Type	Default	Description
`:render_reference` (alias `:render_as`)	`:link` \| `:span` \| `:badge` \| `:embed` \| `function/2`	`:link`	How `@name.ext` references in prose are rendered. `:embed` inlines `<img>` tags for images.
`:render_embed`	`:container` \| `:card` \| `:details` \| `:code` \| `:raw` \| `function/3`	`:container`	How `@@@name.ext ... @@@` blocks are rendered. `:details` creates collapsible accordions.
`:fenced_block_mode`	`:render` \| `:code` \| `:turns`	`:render`	How ```lmml code blocks are handled. `:render` parses and renders the inner LMML narrative.
`:render_turns`	`boolean`	`false`	Whether to transform turn headers (`## Turn N -- <role>`) and comments (`<!-- <role> -->`) into turn cards.
`:url_prefix`	`String.t() \| nil`	`nil`	Base URL prepended to external reference link `href` attributes (e.g. `"/assets"`).
`:anchor_embeds`	`boolean`	`true`	When true, references matching inline embeds in the same document link to `#embed-<name>`.
`:bundle`	`Lmml.Bundle.t() \| nil`	`nil`	An `Lmml.Bundle` instance to resolve entries against.
`:classes`	`keyword() \| map()`	`[]`	Custom CSS class overrides (`:ref`, `:embed`, `:block`, `:turn`, `:image`, `:badge`).

Testing

Run the test suite:

mix test

Run code formatting and quality checks:

mix format --check-formatted
mix credo --strict