hablo/README.md

3.7 KiB

Hablo

Hablo is a minimalist tool written to generate a simple blog structure from markdown articles.

Its key principles are to keep your blog a collection of markdown files while being completely static, leveraging the fediverse to handle comments. The best image you can have of a hablo blog is a HTML/JS article viewer. Despite this heavy usage of JS, it strives to provide a clean site that can still be displayed if JS is disabled and used to get links to the markdown files themselves.

Getting started

Installation

Hablo is written in haskell and uses cabal for installation. The following instructions assume your version of cabal is fairly recent (≥ 1.24) please adapt them if you're running an older version of it, for instance on a Debian Jessie (the same command without the new- prefix roughly work but you might want to use sandboxes — read about it).

Simple install with cabal

Just issue the following line in a terminal

cabal new-install hablo

Alternatively, if you prefer to do things yourself you can do a

Simple install with nix

Want to give hablo a quick try using nix ?

nix-env -f 'https://git.marvid.fr/Tissevert/mynixpkgs/archive/main.tar.gz' -i hablo

Visit my Nix packages for a more declarative setup.

Manual install from this repository

Get a copy of this repository

git clone https://git.marvid.fr/Tissevert/hablo.git

Build the binary

cabal new-update
cabal new-build

Install the result

cabal new-install hablo

Dependencies

Hablo requires UnitJS which is handled by SJW. Make sure you have installed it regularly with SJW. If it isn't yet, the following commands should help you:

cd /tmp
git clone https://git.marvid.fr/Tissevert/UnitJS.git
cd UnitJS
mkdir -p ~/.sjw
cp -r src/ ~/.sjw/unitJS

Then, the static data used by hablo need to be available in a XDG path. Depending on whether you are installing for your user or system-wide, you may want to perform something either

cp -R share ~/.local/share/hablo

or

sudo cp -R share /usr/local/share/hablo

Using hablo (tutorials)

Wanna give it a try ? Start by generating your blog

Want to see your blog in a web browser ? How about reading a bit about deployment to get your local environment ready or setup a publicly available one ?

A bit of stretching (how-to)

Got the basics ? Wondering how to turn the dummy blog project you've created into a magnificent blog ? You should read about customization.

Exploring things in depth

If you know everything you need to start your blog and use hablo, here are some full references to help you when you need a precise description of how some option works or what metadata you can include in your articles.

References

Explanation

If you want a more general view of the project to understand its background and the logic behind the way the various options work, read about the architectural choices