RhoeMarkdown

RhoeMarkdown is the public Swift compiler engine for semantic Markdown in the RhoePlatform ecosystem. It parses author-friendly Markdown into a structured document model and renders it to HTML, LaTeX, Typst, DOCX, PDF, EPUB, JSON API payloads, presentation artifacts, and WebAssembly-facing projections.

This repository is staged as the Apache 2.0 public foundation release for the compiler package. SwiftUI preview apps and premium studio applications remain separate lanes.

Why RhoeMarkdown?

• Plain text in, structured documents out: keep authoring lightweight while preserving a rich AST for downstream tools.
• Projection-ready compiler core: parse once, render to many surfaces, and preserve semantic metadata for editors and publishing systems.
• Liquid preprocessing built in: use RhoeLiquid 0.1.1 for variables, conditionals, and repeatable document generation before Markdown parsing.
• Serious document formats: generate HTML, LaTeX, Typst, DOCX, PDF, EPUB, JSON API payloads, slides, and project outputs from one compiler pipeline.
• Contributor-friendly by design: CI gates, DocC docs, examples, Homebrew release templates, and explicit compatibility notes live in the repo.

Install

Add RhoeMarkdown to a Swift package:

dependencies: [
    .package(url: "https://github.com/RhoePlatform/RhoeMarkdown.git", from: "0.1.1")
]

Use the compiler library:

import RhoeMarkdownKit

let html = await RhoeMarkdownKit.toHTML("""
# Hello, RhoeMarkdown

This is **semantic Markdown** with a generated HTML projection.
""")

Build the CLI from source:

swift build -c release --product rhoemd
./.build/release/rhoemd --version

The Homebrew release installs two command names for the same compiler: rhoemd is the canonical RhoePlatform command, and markdown is the friendly full-name alias.

Build the CLI for Linux:

RHOE_MARKDOWN_LINUX_MODE=native bash Scripts/CI/build-linux-cli.sh
bash Scripts/CI/build-linux-cli.sh # Static Linux SDK build
RHOE_MARKDOWN_LINUX_SDK_ID=swift-6.3.2-RELEASE_static-linux-0.1.0 \
  swiftly run bash Scripts/CI/build-linux-cli.sh +6.3.2

Build the WebAssembly library target:

bash Scripts/CI/build-wasm.sh
swiftly run bash Scripts/CI/build-wasm.sh +6.3.0

CLI Quick Start

Render a Markdown file to HTML:

rhoemd Examples/sources/research-note.md -o Examples/outputs/research-note.html --format html --css

Render to Typst:

rhoemd Examples/sources/typst-paper.md -o Examples/outputs/typst-paper.typ --format typst

Start a non-blocking browser preview backed by the shared local daemon:

rhoemd preview Examples/sources/research-note.md -o /research-note

The command starts or reuses the same local Hummingbird preview server, watches the source file for changes, prints the preview URL plus daemon PID, and returns control to your shell. Register another document with a different route to serve both from the same daemon.

On macOS 26, preview commands also launch the rhoemd-preview-menu menu bar extra by default. Use --no-menu or RHOEMD_PREVIEW_MENU=0 to keep scripts CLI-only.

Build all checked-in examples:

bash Examples/render-all.sh

Package Surface

The first public release exposes the compiler-focused surface:

• RhoeMarkdownKit: public parse/render umbrella.
• RhoeMarkdownWasm: WebAssembly-facing parse/render API.
• RhoeMDCore: reusable CLI core.
• RhoeMDServer: preview and service support.
• RhoeProjectKitCore: project-build substrate required by rhoemd.
• rhoemd: command-line compiler, installed with the markdown alias through Homebrew.
• rhoemd-preview-menu: macOS-only menu bar companion for preview daemon control.

Deferred to later lanes:

• SwiftUI/native preview products.
• Design-kit utilities.
• Premium studio applications.

Documentation

• DocC catalog: Sources/RhoeMarkdownKit/Documentation.docc
• Contributor docs: Documentation/
• Examples gallery: Examples/
• External CommonMark/GFM conformance: Documentation/Release/ExternalConformance.md
• Linux CLI readiness: Documentation/Release/LinuxCLIReadiness.md
• WebAssembly readiness: Documentation/Release/WebAssemblyReadiness.md
• Release process: RELEASING.md
• Security policy: SECURITY.md

Generate the DocC static site locally:

bash Scripts/CI/build-docc-pages.sh

Maintainer Gates

Run the local release-readiness checks before opening a release PR:

swift package dump-package
swift build
swift build -c release --product rhoemd
swift test
bash Scripts/CI/validate-docs.sh
bash Scripts/CI/validate-examples.sh
bash Scripts/CI/validate-external-conformance.sh
bash Scripts/CI/verify-release-readiness.sh

To refresh and run the pinned external CommonMark/GFM conformance lane:

bash Scripts/CI/fetch-external-conformance.sh
bash Scripts/CI/validate-external-conformance.sh

To include the optional Linux CLI gate locally, run:

RHOE_MARKDOWN_VALIDATE_LINUX_CLI=1 bash Scripts/CI/verify-release-readiness.sh

To include the optional WebAssembly gate locally, run:

RHOE_MARKDOWN_VALIDATE_WASM=1 bash Scripts/CI/verify-release-readiness.sh

If the active Xcode Swift toolchain does not provide WASI target support, run the gate through the matching Swiftly toolchain shown above.

The staged repo intentionally remains non-git until the first public foundation release candidate passes these checks.

Homebrew

The Homebrew formula template lives in Packaging/Homebrew/. Publication is deferred until the clean initial commit, public tag, and release audit are complete. Bottle publication will use the RhoePlatform tap:

brew tap RhoePlatform/rhoe
brew install rhoe-markdown
rhoemd --version
markdown --version

License

RhoeMarkdown is released under the Apache License, Version 2.0. See LICENSE and NOTICE for details.