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.
%macro{arg1}{arg2}) that powers the entire rendering process.%def intrinsic.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:
# Heading is converted to %h1{Heading}*Emphasis* is converted to %em{Emphasis}> Quote is converted to %quote{Quote}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.
MacroDown uses CMake for building. You will need a C++23 compliant compiler.
mkdir build
cd build
cmake ..
make
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)
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
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;
}
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!");
MacroDown allows you to define custom shorthand syntax that maps to macros.
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>");
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>");
To run the unit tests:
cd build
./macrodown_test
include/: Header files.src/: Source code.tests/: Unit and integration tests.design.md: Detailed design document.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.
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.
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