tcomp

A simple html templater utility

requirements

• pandoc

installation

python -m build
pip install dist/tcomp-*.tar.gz

usage

usage: tcomp [-h] [-v] [-p DIR] [-P DIR] [-s] [-d] [infile] [outfile]

A simple html templater utility

positional arguments:
  infile
  outfile

General:
  -h, --help           Show this help message and exit
  -v, --version        Print program version and exit
  -p, --path DIR       set alternative source file directory to DIR
  -P, --root-path DIR  set root path to DIR
  -s, --static         compile in static mode
  -d, --dynamic        compile in dynamic mode

Convert tcomp file

tcomp site/index.tcomp out/index.html

Convert tcomp without files

cat site/index.tcomp | tcomp > out/index.html

In practice when tcomp files depend on each other they might not know where they're executed from and so will use absolute paths for dependencies, that's why --root-path should be used to set custom site directory, otherwise it defaults to current directory

tcomp --root-path site site/posts/index.tcomp out/posts/index.html

When input comes from a file it's directory is used for finding dependencies using relative paths, when passing input from stdin this path has to be specified with --path

echo '
    <tcomp href="post.tcomp">
        <tcomp shell="cat site/posts/1.md" markdown />
    </tcomp>
' | tcomp --root-path site --path site/posts > out/posts/1.html

By default compilation happens in dynamic mode, --static flag changes mode to static

tcomp --dynamic site/index.tcomp out/index.php
tcomp --static site/index.tcomp out/index.html

Get some help

tcomp --help

syntax

tcomp files are html files with exception that tcomp tags in them get replaced or removed based on conditions in it's attributes.

tcomp tag can be closed in it's starting tag i.e. <tcomp /> or have insides which will be passed as input to called tcomp format.

attributes

Behaviour of tcomp tags depends on attributes in it.

insides

If insides attribute is present the whole tag is replaced by provided input when calling tcomp format, even if input is empty. Provided input replaces all such tags.

list.tcomp:

<div class=first>
    <tcomp insides />
</div>
<div class=second>
    <tcomp insides>
        random text
    </tcomp>
</div>

page.tcomp:

<tcomp href="/list.tcomp">
    content
</tcomp>

tcomp page.tcomp

outputs

<div class=first>

    content

</div>
<div class=second>

    content

</div>

input attributes

Provides input to be executed. If tag has defined type and doesn't have insides then input will be converted to said type, otherwise insides will be converted and passed to input executed as tcomp format.

<!-- passes converted markdown to /html.tcomp component -->
<tcomp href="/html.tcomp" markdown>
# Header

text
</tcomp>

<!-- replaces tag with converted markdown -->
<tcomp href="/main.md" markdown />

<!-- converts favicon.png at root of the site to jpg as base64 -->
<tcomp shell='magick "$SITE_ROOT/favicon.png" jpg:-' base64 />

href

Gets file from provided path relative to directory of calling file, if path is absolute it'll be processed relative to site root path.

shell

Executes provided command in shell in the same directory as executed file and gets it's output. Path to root of the site is stored in $ROOT_PATH environment variable.

types attributes

If none specified type defaults to tcomp.

tcomp

Executes input as tcomp format converting it to html

html

Returns the exact same input, in assumption that it's valid html

php

Returns the same input enclosed in <?php ?> tag

file

Escapes &, <, >, ', " characters to html entities to protect html structure

base32

Converts to base64

base64

Converts to base64

markdown

Converts markdown to html by calling /usr/bin/pandoc -f gfm -t html --highlight-style=pygments

mode attributes

The following attributes cause tags to be removed if mode tags are not the same as current execution mode (see --static and --dynamic options).

static

Preserves tags only when in static mode. php tags also get removed in static mode.

dynamic

Preserves tags only in dynamic mode.

input.tcomp

<tcomp>
    neither
</tcomp>
<?php
    echo "test";
?>
<tcomp static>
    The mode is static!
</tcomp>
<tcomp dynamic>
    The mode is dynamic!
</tcomp>

running

tcomp --static t.tcomp

outputs

    neither



    The mode is static!

running

tcomp --dynamic t.tcomp

outputs

    neither

<?php
    echo "test";
?>


    The mode is dynamic!

slow execution speed

If you have problems with execution speed, know that it's entirely the fault of pandoc, unfortunately no other converter is extensive enough to color code blocks of markdown.