5.1 KiB
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.
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.
<!-- #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
varnamecan 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
#includecommand must not be in the last line of the file - The maps in
sethave at least 2 options - If you want to use variables in markdown, you have to escape the
#with a backslash, so#$(var)becomes\#$(var)