diff options
Diffstat (limited to 'skaldpress.1')
| -rw-r--r-- | skaldpress.1 | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/skaldpress.1 b/skaldpress.1 new file mode 100644 index 0000000..5ed2046 --- /dev/null +++ b/skaldpress.1 @@ -0,0 +1,96 @@ +.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) |