Drasil

Abstract

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:

• [%PAGE_TITLE%]: this hook is rendered using the page title (i.e. the file name of the current html page under rendering)
• [%NAV_MENU%]: the navigation menu that depends on the actual page that has been rendered
• [%BODY%]: here goes the content of the current html page
• [%LAST_UPDATE%]: last modified date of the rendered page taken from file system table

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

• [%VER%]: print the current version of Drasil
• [%TREE_GEN%]: generate a graphic representation of the website tree

Indexers

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.

Plug-ins

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

• [$today$]: today date
• [$ddate$]: today date in the format of discordian calendar
• [$tag:args: ...$]: tagging system. A page can have one or more tag and is used as an alternative website navigation system. Args are the tags separed by :
• [$gittag$]: if the website src folder is in a GIT repository, this tag prints the current GIT tag
• [$gitlog$]: if the website src folder is in a GIT repository, this tag prints the output of the command git log --pretty=oneline
• [$thumbnailer:img_path:width:label$]: generate the thumbnail of given an image (img_path) of width (width) and incorporate it to the HTML code with a link and a caption (label)

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:

• _ or .: the underscore symbol (or the dot in a unix system) in front of a file or a folder means that the node will be ignored (i.e. not rendered and not copyed, used as placeholder or for temporarily remove a site page or entire section)
• $: the dollar symbol in front of a file or a folder means that there will be no menu item for that file, but that file will be rendered (i.e. useful for hidden pages, or under construction items)
• %: the percent symbol in front of a FOLDER means that the content of the folder is ordered by DATE instead of alphabetical order (i.e. useful for news/blog)
• ##_: where ## are digits (i.e. 00_, 01_, ...) is used for forcing a specific ordering to the content

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.

FAQ

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