⚙️ Configuration & Metadata

Mustela uses a structured approach to manage site-wide settings and page-specific data. This is handled through two main blocks: config (global) and meta (local).

1. Global Configuration Reference (config/mustela.mu)

The config block is the control panel of your project. It contains a fixed set of variables that govern the build system and default metadata. You cannot add custom keys to this block.

Website Identity & Metadata

These variables are available in templates via the @ prefix (e.g., @title) and serve as fallbacks for the entire site.

Build Settings (Generators)

These keys determine which files Mustela generates during the compilation process (both in build and watch mode).

2. Page & Template Metadata (meta do ... end)

Metadata define the state of a specific context. While they are usually written at the top of a .md file, they can also be applied within .mu template files. Unlike the global config block, you are free to define any custom variables here.

Variable Usage & Restrictions

Variables (prefixed with @) cannot be rendered directly within raw Markdown text. To display a variable's value, you must always place it inside an HTML block:

• html do ... end: For direct injection into the flow.
• html as block_name do ... end: For named templates.

Example:

html do
    title:  My Article
    author: Filip Vrba
    tags:   vlang, web, dsl
end

This will NOT work in raw Markdown:
Hello @author!

Correct usage:
html do
<p>Hello @author!</p>
end

3. Scope & Priorities

Mustela follows a specific-over-general hierarchy when resolving variables:

1. Local Metadata: Defined in the .md file (Highest priority).
2. Global Configuration: Defined in config/mustela.mu.
3. Engine Defaults: Factory settings built into Mustela (Fallback).

4. Immutable Constants

These variables are automatically generated by the Mustela engine. You can read and display them, but you cannot overwrite them.

5. The Logic of index

The index variable acts as a template router.

html do
    index: article
end

In this example, Mustela will search your templates for a block named html as article do. If found, it uses that layout. If index is not defined, it defaults to main.

6. Syntax Rules

Flexible Values

Mustela's parser is designed to be user-friendly. When defining values in config or meta blocks, you don't need to worry about special characters or spaces.

• No quotes required: You can write title: My Awesome Website directly.
• Optional styling: If you prefer using quotes for syntax highlighting or personal style (e.g., title: "My Awesome Website"), you can, but it has no effect on the final output.

Deactivating Variables (Comments)

Mustela does not use a specific comment symbol inside configuration blocks. To "comment out" or deactivate a variable, simply prefix the key with any character:

meta do
    # lang: cs   <-- Ignored (system doesn't recognize the key "# lang")
    lang: en     <-- Active variable
end

Data Types

All values are internally handled as Strings. For example, id_headers: true is processed as the text "true".

7. Date Format Reference

When setting the date_format in your config, you can use the following tokens:

8. Header IDs (id_headers)

When building long-form documentation, you often need anchor links. By enabling id_headers, Mustela transforms your Markdown headers into linkable targets:

Markdown:

## 1. Installation

Output (if id_headers: true):

<h2 id="s1-installation">1. Installation</h2>