Feature showcase

Mud renders GitHub-Flavoured Markdown with a set of extended features beyond the CommonMark baseline. This document demonstrates all of them in one place.

Alerts

GFM alert syntax (> [!TYPE]) produces colour-coded call-outs with Octicon icons.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Alerts can also contain rich content — code blocks, lists, inline formatting, and links:

Tip

Press Space to toggle between Up mode (rendered) and Down mode (raw source) without losing your scroll position.

Or use the toolbar button, or View → Toggle Mode in the menu bar.

Diagrams

Fenced code blocks with mermaid as the language identifier are rendered as diagrams using the Mermaid library.

Rendering pipeline

graph LR
    A[Markdown source] --> B[cmark-gfm parser]
    B --> C[AST]
    C --> D[UpHTMLVisitor]
    D --> E{Code block?}
    E -->|mermaid| F[mermaid.run]
    E -->|other| G[highlight.js]
    F --> H[SVG diagram]
    G --> I[Highlighted HTML]

Request lifecycle

sequenceDiagram
    participant User
    participant App
    participant Core
    participant WebView

    User->>App: Open file
    App->>Core: renderUpModeDocument()
    Core-->>App: HTML string
    App->>WebView: loadHTMLString()
    WebView->>User: Rendered page

Mode states

stateDiagram-v2
    [*] --> Up
    Up --> Down: Space bar
    Down --> Up: Space bar
    Up --> Up: Cmd+R (reload)
    Down --> Down: Cmd+R (reload)

Syntax highlighting

Code blocks with a language tag are highlighted server-side by highlight.js via JavaScriptCore — no network requests, no external dependencies.

struct Renderer {
    func render(_ markdown: String) -> String {
        let doc = MarkdownParser.parse(markdown)
        var visitor = UpHTMLVisitor()
        visitor.visit(doc)
        return visitor.result
    }
}

from pathlib import Path

def render_file(path: Path) -> str:
    text = path.read_text(encoding="utf-8")
    return markdown.markdown(text, extensions=["tables", "fenced_code"])

mud -u README.md > output.html
mud -u -b README.md        # open in browser
mud -f README.md           # fragment only, no <html> wrapper

Tables

GFM tables support per-column text alignment using : in the separator row.

Feature	Syntax	Status
Alerts	`> [!NOTE]`	✓
Mermaid diagrams	```mermaid	✓
Syntax highlight	```swift	✓
Emoji shortcodes	`:shortcode:`	✓
Task lists	`- [ ]`	✓
Strikethrough	`~~text~~`	✓
DocC asides	`> Note: …`	✓
Status asides	`> Status: …`	✓

Task lists

CommonMark baseline (headings, lists, links, images)
GFM tables
GFM task lists
GFM strikethrough
GFM alerts (note, tip, important, warning, caution)
DocC asides
Status asides
Mermaid diagrams
Syntax highlighting via highlight.js
Emoji shortcodes
Math rendering (not yet planned)

Inline formatting

Standard inline markup: bold, italic, bold and italic, ~~strikethrough~~, and inline code.

Emoji shortcodes resolve to Unicode using GitHub’s gemoji database (~1,800 aliases): 🚀 ✨ 🎉 ✅ ⚠️

“Mud renders Markdown the way GitHub does, right on your Mac.”

DocC asides

DocC-style asides use a word-and-colon prefix instead of the GFM [!TYPE] tag. Both syntaxes produce the same icon and colour scheme.

Note

Use DocC style in documentation comments rendered by Xcode.

Tip

The TOC sidebar (View → Show Sidebar) lists all headings. Click any entry to jump to that section.

Warning

Modifying the file outside Mud while it is open may cause the file watcher to miss the final change event on some filesystems.

Status asides

A blockquote starting with Status: renders as a special call-out — used in plan documents to track progress.

Status: Complete

All features in this document are implemented and shipping.