5.5 KiB
Architectural choices
Static and lazy
Hablo is a static blog generator which uses markdown for the articles content. This means it generates the web contents once and then no rendering is performed on the server when the clients request a page. Being fully static, the contents of the pages sent by the server won't change unless you call hablo again and regenerate your blog.
Actually, hablo even tries to do as little as possible during this phase. In particular, and this is a major difference with other static blog generators, it won't render your markdown. The aim of hablo is merely to provide the minimum shell of web contents around your articles necessary to display them in a web browser. You can see hablo as a kind of «web viewer» for a set of markdown files. It tries to keep your blog «only a directory with markdown files in it» as much as possible and apologizes for all the HTML generated.
Due to this laziness, a large part of the presentation is done in the web browser with Javascript, mostly intercepting the click on links to load the corresponding content with AJAX and modify the page's structure accordingly. A special attention is paid to not become too dependant on JS though; all the links intercepted point to real pages that can be visited normally so you should be able to browse a hablo blog with JS disabled. The only difference is you will see the markdown content of the article instead of a rendered HTML version.
Reuse
In the same spirit of laziness, hablo tries to implement as little as needed and to reuse everything that is already available from UNIX systems : dates, symlinks, etc.
Files' modification dates are used to sort files chronologically, which allows articles that get modified after they were published to go back to the first pages and be listed as recent topics.
Articles are tagged by placing symlinks to them in the directory representing the tag. From a filesystem perspective, tags are really a selective «view» on your articles, making your blog easy to browse locally.
Page types
As mentioned earlier, hablo tries to generate as little HTML as possible. It will still create two kind of pages : one for each article, and lists for each tag as well as a «general» list that includes all the articles found in the blog (even those untagged).
Pages include a banner, a navigation <div> with links to the various tags and a content.
Article pages
Ideally, the markdown files would be enough and there wouldn't be any HTML generated for articles. Unfortunately, in order to share direct links to articles, some HTML is necessary to reach the blog's interface, loading some JS, to handle the navigation and not only display a markdown file. The additional HTML also allows to generate Open Graph cards to make the links look nicer on social media.
The article pages' content is the body of the markdown file wrapped in a HTML <pre> element and its title.
List pages
There's a list for each tag and a main one that contains all your articles with any tag, even those untagged. For each of these lists there are two HTML pages, one that contains all the articles for that list, and a «short» one that previews only the latest articles that belong to that list.
Latest pages
Those pages contain only the latest articles in each category, including the general one containing all articles, even those untagged. They are contained in the index.html of the directory corresponding to each category (the root directory for the general category and a subdirectory with the tag's name for each tag). With the convention of index.html being served by default for a given path, these are the page you reach by default for each category. In particular, it means the very first page people see when they write the URL of your blog in the navigation bar is the latest page for the general category.
Full pages
Those pages contain all the articles in each category. They are contained in the all.html of the directory corresponding to each category.
Customization
Hablo doesn't have templates. We all know that «HTML is for structure», «CSS is for the style», and «it's wonderful because it's separate and you shouldn't mix the form and the content» but in practice, who hasn't ever changed the structure of their page because it was easier to write the CSS like that ? Who hasn't ever resorted to some ugly CSS trick with three nested phantom divs with absolutely no meaning in the document flow to make a cool effect ?
Hablo takes a stand against this. It aims at generating HTML files that are simple and semantic and you can write a CSS theme for them but not change their structure. It won't let you.
Fediverse
Hablo is conceived from the start to interact with the fediverse and social media in general. It can embed a set of basic Open Graph metadata in the header of all generated pages if you provide the URL where your blog will be deployed to hablo. This allows links posted on social media to appear in a nice box with a picture, the name of the blog and a short description.
Also, being static, hablo doesn't handle dynamic things like comments directly. Instead, comments are toots listed on a fediverse instance.