This is the KLANGBAUM!

Rendered on 2022-10-16, Prickle-Prickle, the 70th day of Bureaucracy in the YOLD 3188



Drasil is a static HTML website generator based on hierarchical tree structure. It works by recursively render each node starting from the root directory and scanning each sub folder of that root in the search of a renderable node.
The rendering is done recursively while scanning the directory tree, that meansthat there is no back-tracking capabilities (i.e. the rendering of a current node connot be influenced by a content or a rendering results of another node).
This very website is generated using Drasil.

Drasil is written in Python, it can be extended using plugins and it's meant to be easy to use. The code is far from perfect, and the documentation is scarce :) but my plans are to improve on that front.

Drasil is very simple to use in the sense that there are no config files to tweak and you can generate the website with one command.

    $ drasil --src path/to/website/three/ -o path/to/generated/html/folder
So, how do you configure your website with Drasil?

Mode of operation

Well, as a first step you have to create a template html that is used for each page. The template file is called _template.html. Note the "_", that means that this particular page is ignored (i.e. is not rendered as a html page and does not generate an item in the navigation menu).

All of the files and subfolders are parsed by Drasil (walk the Bifrost), each file and each folder are a menu item. A folder is a menu with sub items, a file is a leaf menu item.

Each file and folder needs to be rendered as a static html file. The content of each html file is parsed and is used within the given template.
The template page can contain some hooks (NOTE: available ONLY in the template) that are recognized by Drasil and trigger some actions:

Other built-in hooks are available also for other pages:


If a folder contains a page with the same name as the folder itself, the landing page of that folder will be the latter page rendered as usual. If instead, a folder does not contains a page with same name, the landing page of that folder will be rendered as an INDEXER. That means that it will be rendered as a list of links that point to all of the pages or folder contained in that said folder.


By the means of plugins, one can define custom hooks with the syntax [$hook_name$]. Some plugins are already present, such as:

File naming conventions

The files that can be parsed by Drasil are only html files. Other files are copied as is in the rendered website.
Note that each file is linked by the navigation menu, and the items are usually ordered in alphabetical order. Anyway, there are some special character to be used as file name prefix that can change this behaviour:

These special characters are not rendered in the nav menu or in the link.
NOTE: each underscore in the file name are substituted by a whitespace during rendering.
NOTE2: ##_ can be followed by % (i.e. 00_%blog will be a folder that is linked as a first element on the nav menu, and the content of that folder is presented ordered by creation date).
NOTE3: The hidden files (the one with a name that begins with a dot) are ignored and not copied to the static website. If you want dotfiles to be copied to the redered folder (i.e. .htacces) you have to put the dollar symbol $ in front of the file name (example: $.htacces). The dollar symbol will be removed from the file name in the rendered folder.


How can I link a specific page that has to be rendered?
The rendered website is flat in the given output folder. So, if you have a page that is named my_beautiful_page.html or 01_my_beautiful_page.html (no matter how deep in the directory tree is) can be linked using an anchor with href="my_beautiful_page.html".

Check it out on GitHub

Distributed under GNU General Public License v3.0