📝 Project: Building a Markdown to HTML Converter

This project will guide you through building a simple, functional Markdown to HTML converter. It's a perfect real-world example of how the declarative power of the uCalc.Transformer can solve complex text-structuring problems more safely and readably than traditional tools like Regular Expressions.

The Goal

We'll create a transformer that can convert basic Markdown syntax into the corresponding HTML tags:

• Headers: # A Header → <h1>A Header</h1>
• List Items: * An item → <li>An item</li>
• Bold Text: **bold** → <b>bold</b>
• Italic Text: *italic* → <i>italic</i>

🤔 Why uCalc Instead of Regex?

While you could attempt this with a series of Regex.Replace calls, you would quickly run into problems, especially with inline styles. A regex for italic text (\*(.*?)\*) would incorrectly match bold text (**text**), leading to broken tags. Handling this requires complex negative lookarounds that are difficult to write and maintain.

The uCalc Transformer avoids this by being token-aware and using a clear rule precedence system, making the solution both more robust and easier to understand.

Step 1: Setting Up the Transformer

First, we need a Transformer instance. We will also enable RewindOnChange for all rules. This is crucial because it tells the transformer to re-scan the text after a replacement. Without it, after converting a list item line like * text with **bold** into <li>text with **bold**</li>, the engine would not re-scan the new text to find and convert the **bold** part.

csharp
using (var t = new uCalc.Transformer()) {
t.DefaultRuleSet.RewindOnChange = true;
// ... rules go here ...
}


Step 2: Defining the Rules

Next, we'll define our conversion logic using FromTo() rules. We'll start with block-level elements (headers and lists), which operate on whole lines.

Now for the inline elements. This is where rule order becomes critical.```csharp
// Rule for Italic text
t.FromTo("*{text}*", "<i>{text}</i>");

// Rule for Bold text
t.FromTo("**{text}**", "<b>{text}</b>");
```## Step 3: Rule Order is Crucial! (LIFO Precedence)In the code above, why did we define the rule for italics *before* the rule for bold? Because the [Transformer](/Reference/uCalcBase/Transformer/Constructor) checks rules in a **LIFO (Last-In, First-Out)** order. The **last rule defined is checked first**.*   The pattern `**{text}**` is more specific than `*{text}*`.*   If the italic rule were defined last, it would match `**bold**` as `*` + `*bold` + `*`, resulting in `<i>*bold</i>*`—incorrect HTML!*   By defining the bold rule last, we give it higher precedence. The transformer will check for `**...**` first. If it matches, great. If not, it will then check for `*...*`.This is a fundamental concept for writing correct transformation logic.## Step 4: Putting It All TogetherThe full example below combines these rules to process a sample Markdown document. The transformer will correctly handle both block-level tags and nested inline tags in a single pass.## Next Steps: Handling `<ul>` TagsYou'll notice this simple converter creates `<li>` tags but doesn't wrap them in the required `<ul>...</ul>` container. This is a classic multi-pass transformation problem. To solve it, you could:1.  Run the first pass (as we did here) to generate the `<li>` tags.2.  Run a second pass with a new rule that finds consecutive blocks of `<li>` tags and wraps them in `<ul>...</ul>`.This demonstrates how you can build sophisticated pipelines by chaining transformers or using the [Pass](/Reference/uCalcBase/Transformer/Pass) system.