diff --git a/README.md b/README.md index 5c59d67..ab9df7b 100644 --- a/README.md +++ b/README.md @@ -8,108 +8,133 @@ refer to the article [on my website](https://quintern.xyz/en/software/buwuma.htm # HTML Preprocessor Documentation ## Syntax ### Commands - - All commands must be located within a html comment what starts 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 - - - ``` - - 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. +- All commands must be located within a html comment what starts 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 + + +``` + +- 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 +- 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 `` is the same as `` - - If a command-comment takes up a whole line, the whole line including the newline character is replaced. +- Whitespaces around a token are ignored, so `` is the same as `` +- 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**: - `` - **Argument**: - A absolute or relative path to a text file - **Return Value**: - The content of the file or `` empty string if the file can not be opened. +Include the content of a file at the position of the command. +**Synopsis**: +`` +**Argument**: +A absolute or relative path to a text file +**Return Value**: +The content of the file or `` 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 the value of `varname` depending on the value of `othervar`: - `` +Set the value of `varname` depending on the value of `othervar`: +`` - **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` +Comment the arguemnts. +**Synopsis**: +`` +**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**: - `` - **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. +Uncomment the comment. +**Synopsis**: +`` +**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: `

This heading will be linked in the sidenav

` - **Synopsis**: - `` - 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**: - `` - **Argument**: - Must be `href="..." name="..."`. Either single `'` or double `"` quotes are required. - **Return Value**: - Empty string +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: `

This heading will be linked in the sidenav

` +**Synopsis**: +`` +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**: +`` +**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)` +- 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)`