An (experimental) static page generator that supports multiple languages, templating, two-level menus, content categories ("content types") and direct rendering of system command outputs into content.
Implemented in a single ~200 LOC Makefile. Created during a heavy hail storm in may 2015, hence the name (hagel means hail in german).
An example page rendered with hagel can be found here.
My own homepage is also rendered with hagel.
You may find this useful if
- you are building a website (not a web application)
- you are familiar with writing HTML, CSS and JS by hand
- you think that many static page generators, most web frameworks and especially most CMS are too heavyweight for simple websites
- you think that content that won't change for months shouldn't be rendered on each request
hagel lets you create template files for the overall page, categories, content and the menu. The structure of the website is defined as a directory hierarchy. Languages, categories and content are described as *.info files in which variables can be defined. These variables can be accessed in the template files. Since variables are expanded two times and can include direct output of system calls, this allows for quite elaborate setups.
You should have make installed. On debianesque systems, type
apt-get install make
to install it.
The following commands are used and should be either installed as binaries or provided as built-in functions of your shell:
find, test, GNU sed, tr, cp, cat, rm, mkdir, touch, printf
If you are running a unix-like system, you shouldn't have to worry about them. Please note, however, that hagel makes use of some GNU extensions to sed. If you have a version of sed installed that only supports posix style parameters, you won't be able to use hagel.
A repo for an example page using a bootstrap base theme can be found here.
A very simple example page is included in this repository (in ./content). You can build it by typing
make
After the build has finished, you should be able to open ./html/index.html with your favorite webbrowser. By default, hagel uses the absolute file system path of index.html files to follow links. If you want to move the site to a live web server and your webserver automatically displays index.html files if directories are queried, you can adjust the base and index path by setting BASE, for example like this:
make BASE='/' INDEX=''
For a more thorough explanation of the build process parameters, see below.
Template files are in ./templates. You can modify them and run make again to see changes. There are 6 types of template files which are presented here in hierarchical order. See the comments in the ./template files for a list of variables that are accessible in them
page.tmpl, a template file for the overall pagecategory_menu_row.tmpl, a template file for a single category entry in the menu. You can insert the special variable$submenu{}anywhere in this file. It will be replaced with 2ndary menu (a list of content in this category, visible if a user is inside a content in this category)content_menu_row.tmpl, the template file for a single content entry in the 2ndary menulan_switch_row.tmpl, a template file for a single entry in the language switchercategory.tmpl, a template file for category pages (pages which offer a list of content teasers)content_row.tmpl, a template file for a content row inside a category page (is used to render the 'teaser' of a content)content.tmpl, a template file for full content
Template files can be overwritten by placing them inside a category folder in ./content. See below for more information on that.
Be default, hagel uses the template found in ./template. If you are for example using several templates in different directories, you can set TEMPLATE to a different path in your make call like this:
make TEMPLATE='my-shiny-new-template'
Categories appear in the menu and can either be used as simple content pages (if you have a simple one-level page layout) or as a way to group content together. In the category.tmpl file, you have access to the special $rows{} variable that renders each *.content file found in the category folder into a teaser list.
A category must have a category.info file in its directory. You can define variables there at will (variable names may contain letters, numbers, _ and -). Each variable defined in category.info can be accessed in the category.tmpl file by writing
$category{<VARIABLE NAME>}
You are free to add, for example, a short introdution to a category be defining a variable like MY_INTRO in the category.info and rendering it in category.tmpl like this:
<div class="cat-intro">
$category{MY_INTRO}
</div>
Categories offer the special WEIGHT variable which defines the order a category is rendered in the menu. Lower weight means it appears earlier in the menu.
Content is defined per category and is stored in *.content files. Have a look at the examples to see how variables for the full and teaser contents are defined.
Just like category.info files, *.content files offer the WEIGHT variable which defines the order content rows are rendered in the category's teaser list.
You can override certain template files (page.tmpl, category.tmpl, content.tmpl and content_row.tmpl) per category. Just add the file to the category folder. It will be used in the rendering process for that category.
Static files are not part of the rendered HTML content. Be default, they are placed in ./static and the $global{STATIC_PATH} variable is filed with the absolute file system path of ./static. However, if you are deploying your application to a live webserver, you should define the path static files will be reachable from the site during the build process like described below.
The general build command is
make
or
make all
which has to be executed in the base folder of this repository. It only re-renders those parts of the website that have changed since the last build.
If you want to rebuild the page completely, you can either run
make !
or
make all!
or
make clean && make
The clean target removes every rendered file.
By default, hagel renders the HTML for direct file system access through the browser. However, this is most likely not what you want.
Three parameters have to be configured if you are planning to deploy the website to a live server:
BASEthe base path used for the entire website. If you setBASEto/, a link toen/main/will for example be rendered as/en/main, orhttp://mysite.com/en/mainif you setBASEtohttp://mysite.com/.INDEXthe path that is used to access indexes. By default, this is set to/index.html. If your web server deliversindex.htmlautomatically on directory requests (like most web servers do), you can set this to/.STATICthis is mostly for your own use through$glocal{STATIC_PATH}. It should contain the path at which the web browser can access static files on your server.
To render a site which can be access directly via the / endpoint on a server that delivers index.html automatically and which holds static files at /static, run this command:
make BASE=/ INDEX=/ STATIC=/static/
There is no paging for content rows. This is the next big thing that has to be implemented.
Error messages are for the most part cryptic errors from sed. Most of them are entirely useless to you.
Hagel is a mere hobby project and is still in experimental alpha status. Please report any bugs :)
GPL v2