⚙️ 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. Robots & Sitemap Interaction

Mustela handles search engine visibility automatically based on the combination of generate_robots and generate_sitemap keys.

Automatic Modes

Manual Mode (The "Safety Catch")

If you set generate_sitemap: true but generate_robots: false, Mustela enters Manual Mode.

The engine assumes you want to manage your robots.txt by hand (e.g., for complex rules), but it will warn you during every build to ensure you haven't forgotten to link your newly generated Sitemap:

11:13:49 PM [mustela] WARNING | Feed: robots.txt generation skipped (manual mode)

Indexing Control (Variable Overriding)

Mustela makes it easy to control search engine indexing by leveraging its metadata priority system. Instead of writing complex logic, you can simply override a default value.

1. Set the default in your Template

Define the default behavior for all pages within the template's metadata block.

meta do
    robots_content: index, follow
end

html as header do
    <meta name="robots" content="@robots_content">
end

2. Override in a specific Page

To hide a specific page, just redefine the same variable. Mustela's priority system will favor the local value over the template default.

meta do
    robots_content: noindex, nofollow
end

3. 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

4. Scope & Priorities

Mustela follows a specific-over-general hierarchy. This system allows you to define shared defaults within your templates that stay consistent across the entire site, while still giving individual pages the power to override them.

5. Immutable Constants

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

6. 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.

7. 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".

8. Date Format Reference

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

9. 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>