bUwUma/README.md

# bUwUma
`bUwUma` is a build system that uses **GNU make** and a **preprocessor** written in python to build **static**, **multilingual** websites.

This readme only documents the preprocessor.
For more information and a quickstart guide on how to use `bUwUma`, please 
refer to the article [on my website](https://quintern.xyz/en/software/buwuma.html).

# HTML Preprocessor Documentation
## Syntax
### Commands
    - All commands must be located within a html comment what starts with `<!--` and ends with `-->`.
    - Commands start with a `#` character, the command must follow the `#` immediately.
    - Everything after the command until the end of the comment or a newline character are considered the argument of the command.
    ```html
    <!-- #command everything here is an argument -->
    <!--
        #command everything here is an argument
        #anothercommand more arguments
        While this is a comment right now, it will be UNCOMMENTED in the after the preprocessor finishes!
        #comment This will be a single line html comment after the preprocessor finishes.
    -->
    ```
    - All commands return a string, which can be empty.
    - If a comment contains a command, the entire comment will replaced with the return value of the command.
    - If there are multiple commands in a command, it will be replaced by all the return values added together.
### Variables
    - Variable names must only consist of these characters: `a-zA-Z0-9_`
    - A variable with name `varname` can be used like this: `#$(varname)`
    - A variable usage will be replaced by the value of the variable
    - Any variable that has is not defined has empty string as value
### General
    - Whitespaces around a token are ignored, so `<!--#include     dir/file-->` is the same as `<!-- #include dir/file -->`
    - If a command-comment takes up a whole line, the whole line including the newline character is replaced.

## Commands
### include
    Include the content of a file at the position of the command.
    **Synopsis**:
        `<!-- #include path/to-a-text-file.html -->`
    **Argument**:
        A absolute or relative path to a text file
    **Return Value**:
        The content of the file or `<!-- Could not include '{args}' -->` empty string if the file can not be opened.
### set 
    Set the value of a variable
    **Synopsis**:
        Set the value of `varname` to `this is the value`:
        `<!-- #set varname this is the value -->`
        Set the value of `varname` depending on the value of `othervar`:
        `<!-- #set varname othervar?{*:fallback,key1:val1,key2:val2...}>`
    **Argument**:
        The first word is the name of the variable, the rest is the value or a dictionary.
    **Return Value**:
        Empty string
    You can make the value of `varname` dependant on the value of another variable `othervar` by using a dictionary-like syntax described above.
    In this case, `varname` will take the first value from the dictionary that matches tha value of `othervar`. 
    `*` always everything and can be used as fallback. General wildcards like `a*` to match everything that starts with a are not supported.
    Instead of commas `,` you can also use semicolons `;` as separators, but this must be consistend within the map.
### default
    Same as `set`, but it sets the variable's value only if it has no value yet.
### comment
    Comment the arguemnts.
    **Synopsis**:
        `<!-- #comment This will stay as comment in the html -->`
    **Argument**:
        Any string
    **Return Value**:
        The argument in comment tags
    This can be useful in multiline comments that contain other commands: In that case, the comment tags will be removed and each command replaced with
    its return value, so if you want to just have commented text in there you can use `#comment` 
### uncomment
    Uncomment the comment.
    **Synopsis**:
        `<!-- #uncomment This will not be commented -->`
    **Argument**:
        Any string
    **Return Value**:
        The argument
    This can be useful when you want to look at the unprocessed html without variables or when your syntax highlighting gets confused by a variable.
### sidenav
    Manage the generation of a content menu which contains links to all headings in your html that have an id. The menu is called sidenav here.
    An entry is a html heading with a id: `<h1 id=myheading>This heading will be linked in the sidenav</h1>`
    **Synopsis**:
        `<!-- #sidenav sidenav-command arguments -->`
    sidenav-command must be one of the following:
    #### `include`
        Include the generated sidenav at this position.
        **Argument**:
            Ignored
        **Return Value**:
            The generated sidenav
    #### `section`
        Group all following entries in named section.
        **Argument**:
            The name of the section
        **Return Value**
            Empty string
    #### `name`
        Use a custom name instead of the heading itself for the link to the next heading.
        **Argument**:
            The link-name of the next heading
        **Return Value**:
            Empty string
    #### `custom`
        Include a custom link in the sidenav.
        **Synopsis**:
            `<!-- #sidenav custom href="my-link" name="Go to my link!" -->`
        **Argument**:
            Must be `href="..." name="..."`. Either single `'` or double `"` quotes are required.
        **Return Value**:
            Empty string
## Pitfalls
    - The `#include` command must not be in the last line of the file
    - The maps in `set` have **at least 2** options
    - If you want to use variables in markdown, you have to escape the `#` with a backslash, so `#$(var)` becomes `\#$(var)`