hablo/doc/Customizing-your-blog.md

108 lines
4.7 KiB
Markdown
Raw Permalink Normal View History

2019-04-19 21:31:41 +02:00
# Customizing your blog
«Miss !» I hear you calling. «Miss, the blog we've generated… it's… it's pretty ugly actually ?!»
No it's not. It's just pure HTML. Hablo isn't there to provide you with a full-fledged website, it's just the tool that writes the HTML files of your static blog and updates them so you only have to concentrate on what matters : the contents of your articles.
## How do I use a custom skin ?
Hablo provides an option to embed arbitrary HTML in the `<head></head>` of the pages it generates. This is the perfect place to put a link to a CSS file you've written ! The idea behind hablo is to generate a part of your blog, the HTML files, but the rest of your blog's directory is all yours to put what you like in it.
Create a CSS file !
```bash
echo > style.css <<EOF
a {
color: #0cc;
}
EOF
```
Then write a HTML header line that includes it :
```bash
echo > head.html <<EOF
<link rel="stylesheet" href="/style.css"/>
EOF
```
And tell hablo to use this file when generating the blog:
```bash
hablo --head head.html
```
«Ok, now the skin is a bit better, but I don't like the default texts, and I can't fix that with CSS !»
## How do I customize the templates ?
Hablo doesn't allow you to change the [structure of the pages](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#customization) but what you can do is change the texts used by default. They are contained in the file `share/defaultWording.conf` and you can copy this file to your blog's directory and override its entries (you don't have to keep the ones you don't change). For example, let's do this:
```bash
echo "latestPage = Recently on Turtles/paradize" > wording.conf
```
Then generate your blog telling hablo to use this wording
```bash
hablo -w wording.conf
```
The complete list of the available template variables can be found in the [reference](https://git.marvid.fr/Tissevert/hablo/wiki/Template%20variables).
Another possible customization that would be done by means of template files in other blog generators is the header of your blog. Just like for the CSS header, write a custom file with your HTML and tell hablo about it, this time the option is called `banner`:
```bash
echo > banner.html <<EOF
<h1>## T·U·R·T·L·E·S / paradize##</h1>
<div>
<p>The amazing world of fashionable young turtles.</p>
</div>
EOF
```
Then run hablo and pass it the path to your file with the `--banner` option.
```bash
hablo --banner banner.html
```
If you'd like to read more details about all the available customization, you should read about hablo's [command-line arguments](https://git.marvid.fr/Tissevert/hablo/wiki/Command-line).
## How do I activate comments on my blog ?
Since hablo is [static](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#static-and-lazy) there's no way to directly include the comments in the pages. On a blog generated with hablo comments are fetched with JS and dynamically added to the page when it gets rendered in the client.
2019-04-19 21:31:41 +02:00
Let's say you published an article, tell people about it from your fediverse instance by posting a link to that article. First, we need to find the status [`id`](https://docs.joinmastodon.org/api/entities#status) of your post.
Point your web browser to the page that focuses on it and shows the thread of its answers (possibly none yet if you've just posted it) and take the «code» component of the URL (a series of apparently meaningless digits or letters).
On a Mastodon instance the URL should look like
```
https://turtles.social/users/fondofshells/statuses/101841418824885713
```
The part that interests you is the end of the URL after `statuses/` (here, `101841418824885713`).
On a Pleroma instance URLs look like
```
https://turtles.social/notice/9hK9GL3GcRbMw0CV0a
```
And you still want the end, in this case after `notice/` (here, `9hK9GL3GcRbMw0CV0a`).
Now that you've found your post's `id`, let's add a `comments` [metadata](https://git.marvid.fr/Tissevert/hablo/wiki/Metadata#comments) to your article with this `id` as value in its metadata header :
```YAML
comments: 101841418824885713
```
Now, when you generate your blog, tell hablo to look for comments on the instance where you posted :
```bash
hablo --comments-at https://turtles.social
```
Be sure to clear the cache of your web browser before visiting your article again. A «comments» section now shows after your article, with possibly some comments if someone has already answered your post on the fediverse. Also, please note that, as comments are purely handled by the fediverse so is the moderation : you should preferably use this feature on an instance where you have moderation rights and will be able to delete hateful comments or where you know the moderation team will be able to react appropriately.