BareGit

Explain Markdown-to-macro transformation in README

Author: MetroWind <chris.corsair@gmail.com>
Date: Sat Jan 17 17:28:34 2026 -0800
Commit: ed18ef9d73c028735207b97bef67f6c745b176bd

Changes

diff --git a/README.md b/README.md
index 3011d2d..815cc26 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,17 @@ MacroDown is a C++ Markdown processor that extends the CommonMark syntax with a
 *   **Customizable**: Define your own macros using the `%def` intrinsic.
 *   **Two-Step Rendering**: Exposes the syntax tree for inspection or modification before rendering to HTML.
 
+## 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:
+*   `# 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.
+
 ## Building
 
 MacroDown uses CMake for building. You will need a C++23 compliant compiler.