tack.1

.\" Automatically generated by Pandoc 2.18
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "TACK" "1" "July 2022" "" ""
.hy
.SH NAME
.PP
tack - a static site generator for the long run
.SH SYNOPSIS
.PP
\f[B]tack\f[R] [-d] [-s] [\f[I]ACTION\f[R]] [\f[I]SITEDIR\f[R]]
.SH DESCRIPTION
.PP
Tack reads website sources, like Mustache HTML templates, Markdown
content markup, and YAML site & page variables, and \[lq]tacks them
together\[rq] to create a static website that can easily be hosted
anywhere.
.PP
The tool is completely self-contained and has no runtime dependencies.
This ensures that updates to the websites you are creating now are still
easily possible do a few years down the road.
.SH ACTIONS
.TP
\f[B]tack\f[R]
Tack the site together into the folder \f[V]output\f[R].
This is the default action, if no verb is specified.
.TP
\f[B]serve\f[R]
Tack the site together and start a web server on port \f[V]8080\f[R]
which can be used to get a live preview of the tacked website.
Changes to the source files (content, templates, assest, \&...)
are re-tacked and reflected in the served site automatically.
.TP
\f[B]help\f[R]
Display a friendly help message.
.SH OPTIONAL FLAGS
.TP
\f[B]-d\f[R]
Debug mode.
Enabling this function will output more information while tacking pages
to ease debugging.
.TP
\f[B]-s\f[R]
Strict mode.
If enabled, tack will quit with an error if an undefined page variable
is referenced from any of the templates.
.SH SITE DIRECTORY
.PP
The optional \f[I]SITEDIR\f[R] argument refers to a directory that
contains the sources of the website project that should be built by
tack.
.PP
If this argument is not specified, tack uses the current working
directory.
.PP
A valid \f[I]SITEDIR\f[R] contains:
.IP \[bu] 2
\f[V]content\f[R] directory with at least a single metadata
(\f[V]*.yaml\f[R]) or markup (\f[V]*.md\f[R]) file
.IP \[bu] 2
\f[V]templates\f[R] subdirectory with at least a single template file
(\f[V]*.mustache\f[R])
.IP \[bu] 2
Optionally: a \f[V]public\f[R] subdirectory with static files
.IP \[bu] 2
Optionally: a \f[V]site.yaml\f[R] metadata file to define some site
variables
.SH PAGE TYPES
.PP
A page is added to the site by creating a directory somewhere below
\f[V]content/\f[R].
This page directory needs to contain at least a single metadata or
markup file.
Based on the directory name, tack differentiates between three types of
pages:
.TP
Floating pages
A page which is not part of the navigation structure of the site.
So, if you don\[cq]t see a need for automatically created menus or you
want to exclude individual pages from the menu, use floating pages.
Pages are made floating by naming their directory without an enumeration
or date prefix.
.TP
Ordered pages
A page that will show up in the \f[B]menu\f[R], \f[B]navigation\f[R],
\f[B]siblings\f[R] variables so it can be iterated over.
The order of pages on the same level is determined by the position given
as part of the directory name, ie.
\f[I]001-about-us\f[R], or \f[I]2.products\f[R]
.TP
Posts
A post is simply a page directory with a name prefixed with a date in
the \f[V]yyyy-mm-dd\f[R] form.
All posts contained in certain page are accessible using the
\f[B]posts\f[R] list of their parent page.
Posts will not show up in the \f[B]menu\f[R], \f[B]navigation\f[R], or
\f[B]siblings\f[R] variables.
Example page names are: \f[I]2012-08-25.first-release\f[R] and
\f[I]2021-06-06-tack-version-one\f[R].
.PP
Additinally, tack might automatically create \[lq]tag pages\[rq] as
children of a floating or ordered page which is configured to be the
\[lq]tag index\[rq].
See TAGGING POSTS below.
.SH TEMPLATES
.PP
All \f[V]*.mustache\f[R] (or, optionally, \f[V]*.stache\f[R] or
\f[V]*.mu\f[R]) files below \f[I]SITEDIR\f[R]/templates can be used to
create HTML page output by filling them with page content.
All templates are expected to be written in the Mustache template
language.
.PP
The default template used to generate a page is called
\f[I]default\f[R].
To use a different template, you can choose to:
.IP \[bu] 2
Create a metadata file in the page directory.
.RS 2
.PP
The basename of said file will be regarded as the template name.
If, for example, a metadata file like
\f[I]SITEDIR\f[R]/content/about-us/simple.yaml exists, the page
/about-us will be rendered using the template from
\f[I]SITEDIR\f[R]/templates/simple.mustache
.RE
.IP \[bu] 2
Specify a \f[V]template\f[R] variable as part of the YAML frontmatter in
any of the pages\[cq] markup files.
.RS 2
.PP
If, for example, the markup file
\f[I]SITEDIR\f[R]/content/about-us/body.md contains frontmatter like
this:
.IP
.nf
\f[C]
---
template: simple
---

# This is the actual Markdown content
\f[R]
.fi
.PP
The same template from \f[I]SITEDIR\f[R]/templates/simple.mustache would
be used.
.RE
.SH PAGE VARIABLES
.PP
For each rendered page, a set of variables will be available to fill
into the chosen template.
These variables are read from the page\[cq]s metadata files.
.PP
Next to the user-specified variables, these per-page ones are
automatically generated by tack:
.TP
\f[V]permalink\f[R]
An absolute link to the referenced page.
.TP
\f[V]slug\f[R]
Last part of the directory name, stripped of any enumeration prefixes.
.TP
\f[V]name\f[R]
A titlecased version of slug.
This page variable can be overwritten using a YAML metadata file or YAML
frontmatter.
.TP
\f[V]current\f[R]
Boolean to signify if the referenced page is the one currently being
rendered (useful to build active elements in navigation menus).
.TP
\f[V]date\f[R]
(Only if this page is a post) Publishing date of the current page in the
form \f[V]yyyy-mm-dd\f[R].
.TP
\f[V]first\f[R]
(Only if this page is being iterated over as part of a list) Boolean to
signify if the referenced page is the first one of the list.
.TP
\f[V]last\f[R]
(Only if this page is being iterated over as part of a list) Boolean to
signify if the referenced page is the first one of the list.
.SH RENDERING CONTEXT
.PP
Additionally to the page variables listed above, when rendering a page,
these variables are availble to the template, too:
.TP
\f[V]parent\f[R]
An object detailing the parent page (giving the variables listed above),
if the current page is not a top-level one.
.TP
\f[V]siblings\f[R]
List of all ordered pages which are a sibling of the current one.
.TP
\f[V]children\f[R]
List of all child pages.
.TP
\f[V]posts\f[R]
List of post pages which are either a child a sibling.
Only available to floating and ordered pages.
.TP
\f[V]ancestors\f[R]
List of all ancestor pages.
.TP
\f[V]navigation\f[R]
List of all toplevel ordered pages to allow for building navigation
menus.
.TP
\f[V]menu\f[R]
List of all ordered pages on the same level (siblings + current page) to
allow for building navigation menus.
.TP
\f[V]tags\f[R]
If the current page is the tag index page (see TAGGING POSTS below),
this list will contain an object for all tags used throughout the site.
If the current page is a post, the list will contain a tag object for
each tag specified in the page\[cq]s settings.
Each tag object will contain a \f[V]permalink\f[R] to the respective tag
page, the \f[V]name\f[R] of the tag, the \f[V]slug\f[R] of the tag, and
a \f[V]count\f[R] how often this tag is used.
.TP
\f[V]count\f[R]
If the current page is a tag page, this variable will contain the number
of posts that reference this tag.
See TAGGING POSTS below.
.SH PAGE SETTINGS
.PP
Next to specifying page variables, you can modify the behaviour of tack
by setting one of the following variables as part of a pages\[cq]
metadata or YAML frontmatter:
.TP
\f[V]name\f[R]
Overrides the name of the page which is usually derived automatically
from the directory name.
.TP
\f[V]posts_limit\f[R]
For ordered or floating pages, this setting can be used to specify the
number of \f[V]posts\f[R] to provide in the rendering context.
By default, all posts would be listed.
.TP
\f[V]tags\f[R]
If the page is a post, you can specify a list of tags to assign to this
page here.
If the page is not a post, setting this variable to \f[V]true\f[R] will
make this page the tag index (see TAGGING POSTS below).
.TP
\f[V]template\f[R]
Sets the template to use which is usually derived automatically from the
metadata filename.
By specifying the template using this setting, you do not need to
provide a metadata file for pages at all.
.TP
\f[V]template_tags\f[R]
For the tag index page (see TAGGING POSTS below), this setting allows
specifying a different template to be used for (auto-generated) tag
pages.
By default, the template of the tag index page would be used instead.
.SH TAGGING POSTS
.PP
Tack includes a functionality to add an arbitrary number of categories,
or \[lq]tags,\[rq] to posts and allows automatically generating an index
of all the tags used throughout the whole site.
.PP
To use tagging,
.IP "1." 3
Add a \f[V]tags\f[R] page setting to the the posts, ie.
.RS 4
.IP
.nf
\f[C]
---
tags: [\[dq]cars\[dq], \[dq]diy\[dq]]
---

# How I repaired my Fiat 500 myself
\f[R]
.fi
.PP
for a post talking about do-it-yourself car repairs.
.RE
.IP "2." 3
Designate one page to be the tag index, by specifying this page setting:
\f[I]tags: true\f[R] if the pages\[cq] metadata file or YAML
frontmatter.
Optionally, specify a \f[V]template_tags\f[R] page setting set the
template to be used for the tag pages.
.IP "3." 3
Start using the \f[V]tags\f[R] page variable in your post and tag index
templates to list the used tags and link to the individual tag pages.
In the tag page templates, use the \f[V]posts\f[R] variable to link back
to the posts using these tags.
.RS 4
.PP
Example, tag index:
.IP
.nf
\f[C]
{{#tags}}
<li>
  <a href=\[dq]{{permalink}}\[dq]>{{name}}</a>: {{count}}
</li>
{{/tags}}
\f[R]
.fi
.RE
.SH EXIT STATUS
.PP
Tack returns a non-zero exit code if tacking the website was not
successful due to being unable to read or process any of the input files
or if the \f[I]output\f[R] directory cannot be written to.
.SH BUGS
.PP
To report bugs, please create a ticket at
https://github.com/roblillack/tack/issues
.SH SEE ALSO
.PP
jekyll(1)
.SH AUTHORS
Robert Lillack.