BareGit
Commits
Clone:
Name Latest commit Last update
πŸ“‚ cmake
πŸ“‚ designs
πŸ“‚ include
πŸ“‚ src
πŸ“‚ tests
πŸ“‚ web
πŸ“„ .clang-format Implement the rest of markups. Now it should have all CommonMark markups. 8 months ago
πŸ“„ .gitignore Escape HTML in inline and block code contents 8 days ago
πŸ“„ CMakeLists.txt Fix Emscripten bootstrap when MacroDown is a dependency 5 weeks ago
πŸ“„ README.md Fix Emscripten bootstrap when MacroDown is a dependency 5 weeks ago
πŸ“„ prd.md Enhance custom markup with regex patterns and extended character support 10 months ago
πŸ“„ todo.md Adopt test suite from github.com/karlcow/markdown-testsuite. They don’t all pass right now 4 months ago

MacroDown

MacroDown is a C++ Markdown processor that extends the CommonMark syntax with a powerful TeX-like macro system. It treats all markup elements as syntactic sugar for macro calls, allowing for extensive customization and extension.

Features

How it Works

MacroDown uses a unified approach to document processing. Instead of having separate logic for every Markdown element, the parser first transforms standard Markdown syntax into an internal tree of macro calls.

For example:

These macros are then evaluated using a standard library of definitions that produce the final HTML output. This architecture makes it incredibly easy to change the output of standard Markdown elements by simply redefining their corresponding macros.

Building

MacroDown uses CMake for building. You will need a C++23 compliant compiler.

mkdir build
cd build
cmake ..
make

Integration

Using FetchContent

You can add MacroDown to your project using CMake's FetchContent.

include(FetchContent)

FetchContent_Declare(
  macrodown
  GIT_REPOSITORY https://git.xeno.darksair.org/macrodown.git
  GIT_TAG master # Or a specific tag/commit
)

FetchContent_MakeAvailable(macrodown)

# Link to the library
target_link_libraries(your_target PRIVATE MacroDown::MacroDown)

Usage

CLI

You can use the macrodown executable to convert Markdown to HTML.

From a file:

./macrodown input.md > output.html

From stdin:

echo "# Hello World" | ./macrodown

Library Interface

You can integrate MacroDown into your C++ projects using the MacroDown class.

#include "macrodown.h"
#include <iostream>

int main() {
    macrodown::MacroDown md;

    std::string input = "# Hello\n\nThis is **MacroDown**.";

    // Step 1: Parse to Syntax Tree
    auto root = md.parse(input);

    // Step 2: Render to HTML
    std::string html = md.render(*root);

    std::cout << html << std::endl;
    return 0;
}

Defining Macros

You can define macros directly in your Markdown document:

%def[greet]{name}{Hello, %strong{%name}!}

%greet{World}

Output:

<p>Hello, <strong>World</strong>!</p>

Or programmatically in C++:

md.evaluator().define("greet", {"name"}, "Hello, %name!");

Custom Markups

MacroDown allows you to define custom shorthand syntax that maps to macros.

Prefix Markups

Useful for tags or mentions. A prefix markup starts with a character and ends at a whitespace or punctuation boundary.

// Transforms #test into %tag{test}
md.definePrefixMarkup({"#", "tag", ""});
md.evaluator().define("tag", {"content"}, "<span class=\"tag\">#%content</span>");

Delimited Markups

Useful for custom inline styles. A delimited markup starts and ends with the same character.

// Transforms :important: into %highlight{important}
md.defineDelimitedMarkup({":", "highlight"});
md.evaluator().define("highlight", {"content"}, "<mark>%content</mark>");

Testing

To run the unit tests:

cd build
./macrodown_test

Project Structure

WebAssembly and live preview

You can let CMake download and install Emscripten into /tmp:

cmake -S . -B build_wasm -DMACRODOWN_BOOTSTRAP_EMSDK=ON \
    -DCMAKE_BUILD_TYPE=Release
cmake --build build_wasm -j24
python3 -m http.server 8000 --directory build_wasm/web

This opt-in bootstrap requires Git, Python 3.8 or newer, and network access for the first download. It installs and activates Emscripten 6.0.12 under /tmp/macrodown_emsdk, then selects its toolchain automatically; emcmake and shell activation are unnecessary. Subsequent configurations reuse the SDK. It does not modify your shell startup files or install system packages. The SDK is temporary and may need to be downloaded again after /tmp is cleaned. For standalone builds, use a separate directory from your native build.

Set MACRODOWN_EMSDK_DIR to change the installation directory and MACRODOWN_EMSDK_VERSION to select a release. When changing SDK versions, use a new SDK directory and build directory. The bootstrap cannot be combined with a different CMAKE_TOOLCHAIN_FILE in standalone builds.

When MacroDown is included through FetchContent or add_subdirectory, the option installs the SDK but keeps the parent project's native compiler and toolchain. It sets the EMCMAKE_EXECUTABLE cache variable to the SDK's emcmake, so the parent can configure a separate WebAssembly build:

include(ExternalProject)
ExternalProject_Add(macrodown_browser
    SOURCE_DIR "${macrodown_SOURCE_DIR}"
    BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/macrodown_wasm"
    CONFIGURE_COMMAND "${EMCMAKE_EXECUTABLE}" "${CMAKE_COMMAND}"
        -S <SOURCE_DIR> -B <BINARY_DIR>
        -DCMAKE_BUILD_TYPE=Release
        -DMACRODOWN_BUILD_WASM=ON
        -DMACRODOWN_BUILD_CLI=OFF
        -DMACRODOWN_BUILD_TESTS=OFF
    INSTALL_COMMAND ""
)

The browser artifacts are generated under macrodown_wasm/web in the parent's build directory. Bootstrap alone does not add a browser build to a native parent; the separate build above does.

Alternatively, install and activate Emscripten, then configure a separate build directory:

emcmake cmake -S . -B build_wasm -DCMAKE_BUILD_TYPE=Release
cmake --build build_wasm -j24
python3 -m http.server 8000 --directory build_wasm/web

Open http://localhost:8000. The demo renders locally in a module Web Worker with a 150 ms typing debounce. It displays the generated HTML in a sandboxed iframe that blocks scripts and network requests, including external images. Serve the files over HTTP rather than opening index.html directly.

Smaller production builds

To optimize for download size, use -Oz and link-time optimization instead of the release build above:

emcmake cmake -S . -B build_wasm \
    -DCMAKE_BUILD_TYPE=MinSizeRel \
    '-DCMAKE_CXX_FLAGS_MINSIZEREL=-Oz -DNDEBUG -flto' \
    -DCMAKE_EXE_LINKER_FLAGS=-flto
cmake --build build_wasm -j24

With Emscripten 6.0.12, this reduced the Wasm file from approximately 342 KiB to 279 KiB. The size-optimized file compressed to approximately 90 KiB with gzip or 74 KiB with Brotli. Sizes vary with the toolchain and source version; size optimization may trade some execution speed for size. The release Wasm already omits debug and symbol-name sections, so additional stripping offers little benefit.

Enable gzip or Brotli compression on your production HTTP server for both the .wasm and .mjs files. Serve .wasm as application/wasm, .mjs as JavaScript, and compressed responses with the matching Content-Encoding header. The Python server above is for local preview and does not enable compression automatically.

JavaScript API

The build produces macrodown.mjs and macrodown.wasm. Keep these files alongside one another when using the module in another frontend:

import createMacroDown from "./macrodown.mjs";

const macrodown = await createMacroDown();
const html = macrodown.renderMarkdown("# Hello");

renderMarkdown(source) returns an HTML string synchronously after module initialization. Every call uses a fresh document and macro environment. Custom macros defined in the source work as in the native renderer. The API does not yet expose programmatic macro or markup registration. For large documents, use a worker as the demo does; each update parses the full source. Generated HTML is not sanitized. Use an appropriate sandbox or sanitizer when displaying untrusted documents in your application.

Native CLI and GoogleTest targets default to off under Emscripten, and retain their existing defaults for native builds. They can be controlled separately with MACRODOWN_BUILD_CLI and MACRODOWN_BUILD_TESTS. MACRODOWN_BUILD_WASM defaults to on under Emscripten.

Run the JavaScript/Wasm smoke tests with Node (optionally providing a native binary to check output parity):

node tests/test_wasm.mjs build_wasm/web/macrodown.mjs build/macrodown