✍️ Markdown & Hybrid Mode

Mustela’s Markdown engine is built for one thing: Extreme Throughput.

To achieve our benchmark of 9,000+ pages per second, we use a linear, single-pass parser. It supports all essential formatting while introducing a unique "Hybrid Mode" that lets you escape Markdown and enter the world of dynamic HTML.

1. Supported Markdown Features

Our parser follows the standard Markdown philosophy but is optimized for technical documentation and speed.

Feature	Support	Technical Note
Headers	`#` to `######`	Supports nested formatting (e.g. `# Bold Title`).
Emphasis	`` and `*`	Fully nestable: `*Bold & Italic*` works as expected.
Blockquotes	`>`	Supports all other inline Markdown features inside.
Code Spans	`inline`	Preserves backticks and raw characters.
Code Blocks	```	Standard fenced blocks for code snippets.
Links	`[text](url)`	Supports titles and internal project links.
Images	`![alt](url)`	Renders as standard `<img>` tags.
Rules	`---`	Generates a clean `<hr>` separator.
Lists	`*` or `1.`	Bullet and numbered lists. Nested lists are not supported (they will break the group).

💡 Pro Tip

Mustela uses a non-recursive list parser. If you try to nest a list, the engine will automatically break out of the current group and start a fresh list. This design choice eliminates recursive overhead, contributing to our extreme parsing speeds.

2. Optimization Trade-offs

To maintain our 9,000+ pages/sec benchmark, we deliberately omitted features that require expensive backtracking or recursive lookups.

Feature	Status	Recommendation
Nested Lists	❌ Unsupported	Keep your structures flat for better readability and 9,000+ p/s throughput.
Markdown Tables	❌ Unsupported	Use `html do` blocks. They are more flexible, accessible, and easier to style.
Footnotes	❌ Unsupported	Use inline links or a dedicated "References" section at the bottom of your document.
Task Lists	❌ Unsupported	Use standard bullet points or `html do` for custom interactive checklists.

3. The Hybrid Content Power

This is the "Killer Feature" of Mustela. We break the wall between static content and dynamic templating. Unlike traditional generators where a file is either data or content, a Mustela file is a living stream.

Why it's a Game Changer:

Self-Contained Articles: Everything a page needs (logic, variables, and content) stays in one .md file.
Contextual Logic: You can inject custom layouts or CSS classes only for specific articles without touching the global theme.
Ruby-ish Flow: Writing in Mustela feels like writing a high-level script.

4. Grand Finale: Mixed Mode Example

Below is a demonstration of how Metadata, Markdown, and HTML Blocks coexist in a single file. This is the intended "Mustela Workflow."

advanced-guide.md

meta do
  title:  "The Hybrid Power"
  author: "Filip Vrba"
  index:  article
end

# Mixing Markdown & Mustela
This is standard Markdown text. But wait, we can inject logic:

html do
<div class="special-callout">
  <h4>🦦 Mustela Insight</h4>
  <p>You are reading a variable: <strong>@author</strong></p>
</div>
end

Back to Markdown. Even **bold text** or [links](/doc/concepts.html) work perfectly here.

html do
<script>
  console.log("Mustela injected this script specifically for this page!");
</script>
end

🛡️ Handling Special Characters

Mustela’s variable engine is smart enough to distinguish between a DSL trigger and common text (like emails). However, if you need to be explicit, here is how to handle it:

In Markdown

Use a backslash to escape formatting:

\# Not a header
\*Not italic\*

In HTML Blocks

Use HTML entities to prevent variable injection:

<span>&#64;handle</span> 
<!-- Renders as @handle -->

5. Technical Rendering Specs

Mustela follows a "What You See Is What You Get" philosophy with a focus on performance and semantic correctness. Here is exactly how the engine transforms your Markdown into HTML.

5.1 Images

Mustela automatically differentiates between decorative images and descriptive figures. We also include loading="lazy" by default to boost your PageSpeed score.

With Caption: ![The Mustela logo](logo.png)

<figure>
  <img src="logo.png" alt="The Mustela logo" loading="lazy">
  <figcaption>The Mustela logo</figcaption>
</figure>

Decorative (No alt):

<img src="logo.png" alt="" loading="lazy">

5.2 Links

Mustela handles empty labels gracefully by using the URL as the display text.

Standard: [Mustela](https://mustela.vercel.app)

<a href="https://mustela.vercel.app">Mustela</a>

Auto-link: [](https://mustela.vercel.app)

<a href="https://mustela.vercel.app">https://mustela.vercel.app</a>

5.3 Code

Syntax highlighting is prepared via CSS classes, keeping the HTML output clean and fast.

Code Blocks: ```mu

<pre>
  <code class="language-mu">
    /* Your code here */
  </code>
</pre>

Code Spans `:

<code>code</code>

5.4 The List Logic

As mentioned in the Pro Tip, Mustela does not support nesting. Instead, it groups consecutive items of the same type. If you switch types or break the order, Mustela starts a new group.

Markdown Input:

1. faa
2. fee
- foo
3. fii

HTML Output:

<ol>
  <li value="1">faa</li>
  <li value="2">fee</li>
</ol>
<ul>
  <li>foo</li>
</ul>
<ol>
  <li value="3">fii</li>
</ol>

Congratulations! You've mastered the Mustela DSL. Ready to deploy? Check out the Project Structure & Workflow guide.