Site Builder Demo

All the static websites I make generally follow the same pattern: a Makefile directs the compilation of source files into website content, based on their filename extensions.

Whenever a rule processes a file the extension is stripped off, which allows me to chain rules together. For example, consider a source file named index.html.md.py, a python script that outputs markdown-format text. The following would occur:

• index.html.md.py is executed as a python script and the markdown output is captured as a temporary intermediate file named
• index.html.md, which pandoc converts to html and saves as
• index.html, the page you are reading now.

This particular demo is very similar to what I have been using to publish my site, with some specifics omitted for simplicity.

Getting Started

Clone this repo

git clone https://tilde.town/~pho4cexa/site.git

Note: tilde.town users may do it this way instead, which is more efficient:

$ git clone ~pho4cexa/public_html/site.git

Generating the demo site

make -rRj DST=demo

Generate a site with your own sources

make -rRj SRC=mysite DST=mysite_rendered

Features

This particular implementation includes the following behavior:

• Markdown and python scripts are recognized as source formats to be processed; all other files are passed verbatim to the output.
• An included example demonstrates how to create a dynamic page list and a JSON-format site-map.
• automatic re-build: if you have inotify-tools installed, running make watch will automatically re-run make whenever a source file changes.

Not features

The following features are useful but intentionally not included, for simplicity. You may wish to modify this, or use something else altogether, if you require them:

• sub-directories of source files
• extension-less URLs (like https://.../foo instead of https://.../foo.html)
• trailing slash on all URLs (like https://.../foo/ instead of https://.../foo.html). This makes it easy and consistent to refer to parent, sibling, and child pages in static content. (../, ../sibling/, child/, respectively.)
• a common template applied to all different types of source format. In this repo, we rely on pandoc’s page formatting. Content authored in raw html or as a python script that outputs html would have to redundantly include the same code to look consistent.
• extra rules for many different types of source content

Sources

This is what the source structure for this website looks like:

content
├── 1.html.md
├── 2.html.md
├── 3.html
├── index.html.md.py
├── Makefile.txt -> ../Makefile
├── map.json.py
└── style.css

0 directories, 7 files

Pages

Here is an automatically-updated list of all the pages on this site, in reverse chronological order of publication.

This is not a feature of the makefile, but instead of the python script included in the example content.

Another example page
An example page written in HTML
An example page written in Markdown

Similar mechanisms:

• Phil Hagelburg uses a similar approach that is even more minimalist. He authors HTML files by hand, using the M4 macro language to wrap a header and footer around it.

• @datagrok’s makebakery intends to collect a large number of features together as modules that you selectively enable through configuration, where this repo is intended to be forked and modified to suit your needs. The core concept is the same, but it is probably much easier to understand this repo’s makefile.

License: AGPL-3.0+ with additional permissions

This software is released under the terms of the GNU Affero General Public License, Version 3 (or, at your option, any later version,) with a grant of additional permission that allows you to apply any terms you wish to the sites you create with it.