.TH SKALDPRESS 1 2024-06-08
.SH name
Skaldpress \- Templating engine
.SH SYNOPSIS
.B skaldpress [OPTIONS]

.SH DESCRIPTION
.B smp
smp is a macro processor, made specifically for a usecase when doing templating of websites.


Macros which are available using skaldpress, in addition to the builtin smp(1)-macros
.IP "\fBtemplate(<template>,<content>)\fR"
Will process the content using a template, in-place.
This macro is used by the \fBall_tagged_by\fR-macro.

.IP "\fBall_tagged_by(<tag_name>,<template>[,<field to sort by>][,<reversed>])\fR"
Will output all documents which had the specified tag, using the specified template.
If a field to sort by is specified, it will output ascending based on that field,
or reversed if a fourth argument \fBreversed\fR is specified.

.PP
All input files can have a metadata-block at the beginning.
Any keys will be defined as macros as \fBMETADATA_<key>\fR.
There are a few special keys which has a specific effect:

.IP "\fBskip_smp\fR"
If this is \fItrue\fR, macro processing will be skipped for the file, and it will be
included verbatim.

.IP "\fBskip_build\fR"
If this is \fItrue\fR, the file will not be written to build-dir, but it will be compiled and available for macros like \fBall_tagged_by\fR.

.IP "\fBtags\fR"
This is a list, and all files with entries here will be registered during the first compilation round.
During the second compilation, macros like \fBall_tagged_by\fR will then
make all files with the relevant content available and compile it in.

.IP "\fBtarget_filename\fR"
By default, a file will have the same name in the \fIoutput\fR-directory (unless a template has a different extension).
This overrides the output-filename, but it keeps the file in the same directory, and it will not affect the extension.

.IP "\fBtemplate\fR"
If specified, the file will be compiled using a template.
In the template, all \fBMETADATA_<key>\fR macros will be available,
additionally templates can use the \fBCONTENT\fR-macro to get the expanded content of the file.
This is recursive, meaning that templates can use other templates, with their own metadata-block,
since it is recursive, any metadata in templates will overwrite any metadata from their children, 
but will keep metadata that is not overwritten.
This means templates can add additional context.

.IP "\fBkeep_states\fR"
List or string where every listed state/variable will be kept for subsequenct compilations.
Meaning that you can e.g. construct a array in the first compilation, which is then used the second time around.
Setting this, means that the file will always be recompiled, regardeless of other instances (unless a \fB--filter\fR is set).

.SH OPTIONS
.IP "\fB-o, --out, --output\fR \fIpath\fR
Specifies the directory to output the compiled files to, defaults to \fIbuild\fR.

.IP "\fB-i, --input\fR \fIpath\fR
Specifies the directory where all files are iterated, defaults to \fIcontent\fR.

.IP "\fB-s, --static\fR \fIpath\fR
Specifies the directory where all files are iterated, defaults to \fIcontent\fR.

.IP "\fB-t, --templates\fR \fIpath\fR
Specifies the directory where templates are stored, defaults to \fItemplates\fR.

.IP "\fB-f, --filter\fR \fIfilter\fR
Comma-separated list of files to compile, if not specified, all files in \fB--source\fR
will be compiled.

.IP "\fB-e, --exclude\fR \fIfilter\fR
Comma-separated list of files to exclude, if not specified, all files in \fB--source\fR
will be compiled.

.IP "\fB-m, --metadata\fR \fIkey\fR=\fIvalue\fR
Metadata to add to compiled file, this can e.g. set a template for all files if you don't want to manually add YAML-blocks.
Specify multiple times, to set multiple fields.

.SH EXAMPLES

To run skaldpress on a simple project, simply call it with no arguments
in a directory where you have a \fBcontent\fR-directory,
and optionally a \fBtemplates\fR-directory.
.PP
.nf
.RS
skaldpress
.RE
.fi
.PP

.SH SEE ALSO
smp(1)