hablo/README.md

# 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](https://www.haskell.org) and uses [cabal](https://www.haskell.org/cabal) for installation. The following instructions assume your version of cabal is fairly recent (≥ 1.24) please [adapt them](https://www.haskell.org/cabal/users-guide/intro.html) 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

```bash
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 ?

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

Visit my [Nix packages](https://git.marvid.fr/Tissevert/mynixpkgs) for a more declarative setup.

#### Manual install from this repository

Get a copy of this repository

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

Build the binary

```bash
cabal new-update
cabal new-build
```

Install the result
```bash
cabal new-install hablo
```

### Dependencies

Hablo requires [UnitJS](https://git.marvid.fr/Tissevert/UnitJS) which is handled by [SJW](https://git.marvid.fr/Tissevert/SJW). Make sure you have installed it regularly with `SJW`. If it isn't yet, the following commands should help you:

```bash
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

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

or

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

### Using hablo (tutorials)

Wanna give it a try ? Start by [generating your blog](https://git.marvid.fr/Tissevert/hablo/wiki/Generating%20your%20blog)

Want to see your blog in a web browser ? How about reading a bit about [deployment](https://git.marvid.fr/Tissevert/hablo/wiki/Deploying%20a%20hablo%20blog) 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](https://git.marvid.fr/Tissevert/hablo/wiki/Customizing%20your%20blog).

## 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

- [Command line](https://git.marvid.fr/Tissevert/hablo/wiki/Command-line) arguments and options
- articles [metadata](https://git.marvid.fr/Tissevert/hablo/wiki/Metadata)
- template [variables](https://git.marvid.fr/Tissevert/hablo/wiki/Template%20variables)

### 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](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices)