mkpage

mkpage is a deconstructed, post modern, content management system for generating static websites.
It is suited to building sites hosted on services like Github Pages or Amazon’s S3. It is
comprised of a set of command line utilities that augment the standard suite of Unix/Posix commands
available on most Posix based operating systems (e.g. Linux, Mac OS X, Raspberry Pi and Windows systems that
have a port of Bash).

mkpage can run on machines as small as a Raspberry Pi. Its small foot print and minimal
dependencies means installation usually boils down to copying the precompiled binaries to a bin directory
in your path. Precompiled binaries are available for Linux, Windows and Mac OS X running on Intel as
well as for the ARM7 versions of Raspbian running on Raspberry Pi. mkpage is built on Go’s text templates.
The template markup similar to the Mustache templates and
Handlebars. mkpage has been easier for us to support when compared with
more established static site generators like Jekyll.

mkpage’s minimalism turns into an advantage when you combine mkpage with the standard suite of text
processing tools available under your typical Unix/Posix like operating sytems. This makes scripting a
mkpage project using languages like Bash and Python relatively straight forward. Each mkpage utility
is independent. You can use as few or as many as you like as you when you script the website creation
process that best fits your needs.

The following command line tools come with mkpage

mkpage – a single page renderer with support for Markdown, JSON and Go text templates

A quick tour

mkpage command accepts key value pairs and applies them to a Golang text/template.
The key side of a pair corresponds to the template element names that will be replaced in the render
version of the document. If a key was called “Content” the template element would look like {{ .Content }}.
The value of “Content” would replace {{ .Content }}. Go text/templates elements can do more than
that but the is the core idea. On the value side of the key/value pair you have strings of one of
three formats - plain text, markdown and JSON. These three formatted strings can be explicit strings,
data from a file or content retrieved via a URL. Here’s a basic demonstration of sampling of capabilities
and integrating data from the NOAA weather website.

Notice the two explicit strings are prefixed with “text:” (other possible formats are “markdown:“, “json:“).
Values without a prefix are assumed to be file paths. We see that in testdata/signature.txt. Likewise the
weather data is coming from a URL. mkpage distinguishes that by the prefixes “http://” and “https://“.
Since a HTTP response contains headers describing the content type (e.g. “Content-Type: text/markdown”) we
do not require any other prefix. Likewise a filename’s extension can give us an inference of the data format
it contains. “.json” is a JSON document, “.md” is a Markdown document and everything else is just plain text.

Since we are leveraging Go’s text/template the template itself
can be more than a simple substitution. It can contain conditional expressions, ranges for data and even
include blocks from other templates.

companion utilities

mkpage

mkpage comes with some helper utilities that make scripting a deconstructed
content management system from Bash easier.

mkslides

mkslides generates a set of HTML5 slides from a single Markdown file. It uses
the same template engine as mkpage

mkrss

mkrss will scan a directory tree for Markdown files and add each markdown file with
a corresponding HTML file to the RSS feed generated.

byline

byline will look inside a markdown file and return the first byline it finds
or an empty string if it finds none. The byline is identified with a regular
expression. This regular expression can be overriden with a command line option.

titleline

titleline will look inside a markdown file and return the first h1 exquivalent title
it finds or an empty string if it finds none.

reldocpath

reldocpath is intended to simplify the calculation of relative
asset paths (e.g. common css files, images, feeds) when working from
a common project directory.

Example

You know the path from the source document to target document from the project root folder.

ws

ws is a simple static file webserver. It is suitable for viewing your local copy
of your static website on your machine. It runs with minimal resources and by default
will serve content out to the URL http://localhost:8000. It can also be used to host
a static website and has run well on small Amazon virtual machines as well as Raspberry Pi
computers acting as local private network web servers.

Example

ws Sites/mysite.example.org

This would start the webserver up listen for browser requests on http://localhost:8000.
The content viewable by your web browser would be the files inside the Sites/mysite.example.org
directory.

ws -url http://mysite.example.org:80 Sites/mysite.example.org

Assume the machine where you are running ws has the name mysite.example.org then your could
point your web browser at http://mysite.example.org and see the web content you have in
Site/mysite.example.org directory.