How this blog is made

⏳ 9 min read📅 2021-08-17

A brief overview of how this blog works under the hood.

TL;DR:

🔗Prehistory / Why?

It all started when I was writing a travel blog (in Russian). After some time, it evolved from just a stream of photos to more deep and thoughtful content, which required some thought put in it as well as editing, planning, drafts and formatting. The natural way to keep these drafts was in markdown, and generating a static website was in a stone’s throw from here.

Also, I was thinking about a place to dump my developer’s notes. All in all, I started looking into static site generators and decided to go with…

🔗Zola

Unlike Hugo , Zola is much younger, and thus its community is much smaller. There are no myriads of fancy pre-made themes that look awesome. But for me, this turned out to be a perfect match.

I started with Hugo, but quickly got overwhelmed by its complexity. I picked up a good-looking theme and tried to hack on it, but OMFG that was tough! Lots of JavaScript everywhere, weird templates, TONS of CSS… It was unbearable to change anything: things just kept falling apart. At this point, I realized that the only possibility to make things look the way I wanted them was to create a theme from scratch.

Looking around, I found Zola and decided to try it (yeah, because of Rust). And it was so much more sensible! I started hacking on one of the default themes but quickly rewrote it all from scratch.

The basic idea is simple:

  • You write your posts in markdown (e.g. this page looks like this)
  • You have templates that explain Zola how to build a web page from it:
    • index.html - the front page. I just symlinked it to section.html, since they are the same
    • section.html - a template for a page with post list
    • page.html - a template for a page with a post itself
  • The template language (Terra) is very similar to Jinja2, which should be familiar to all Ansible users
  • Templates can extend other pages, e.g. I use a base.html template that contains header and other common stuff
  • Sass is supported out-of-the-box!
  • To extend markdown syntax, you can use shortcodes. Shortcode is also a template that can be inserted from markdown, e.g. templates/shortcodes/hint.html:
    <span
      class="has-tooltip-arrow {% if hint | length > 20 %} has-tooltip-multiline {% endif %}"
      data-tooltip="{{ hint }}">
          {{ text }}
    </span>
    
    will allow you to create tooltips like this :
    {{ hint(text="like this", hint="hint text goes here") }}
    
    How awesome is that? I use shortcodes to insert:
    • Google maps iframes
    • Open Street Maps iframes
    • Youtube iframes
    • Images and videos with nice-looking comments
    • Katex formulas

🔗Kroki

I like keeping diagrams in plain text format. It makes them easy to edit, read and share. It also improves collaboration, since you can now make readable Pull/Merge Requests.

A good tool for such task is PlantUML. It even provides an API to render images. However, you need to send your diagram in GET request, using special encoding, which Zola doesn’t support. POST requests are implemented, but not enabled on the public server.

Luckily, there is Kroki! It wraps a lot of tools under a unified API: you just send POST requests with your diagram data and get SVG or PNG back. We only need to write a shortcode:

{% set postdata = load_data(
	url="https://kroki.io/plantuml/svg",
	format="plain", method="POST",
	content_type="text/plain",
	body=body,
	required=true
	)
%}
<figure class="image">
	{{ postdata | safe }}

	{% if comment %}
		<p class="comment">
			<em>{{ comment | markdown | safe }}</em>
		</p>
	{% endif %}
</figure>

So now this section in markdown

{% plantuml(comment="simple diagram") %}

participant Zola
participant Kroki

Zola -> Kroki: POST /plantuml/svg\nContent-type: text/plain\n<diagram_data>
activate Zola
Kroki -> Zola: SVG image
deactivate Zola
Zola -> Zola: embed SVG into HTML

{% end %}

… renders into this:

ZolaZolaKrokiKrokiPOST /plantuml/svgContent-type: text/plain<diagram_data>SVG imageembed SVG into HTML

simple diagram

The rendering happens only once - during the site generation step. A diagram then exists as SVG image embedded right into HTML. A cool feature with such approach is that users can copy text from diagram labels, but a downside is that you can’t just download an image. However, you can extract SVG code from the DOM and put it into a file.

🔗Bulma

It’s hard to create a good-looking site with plain HTML nowadays. I use Bulma as my CSS framework, and I am mostly happy with it:

  • No JavaScript required
  • Modularity, meaning smaller asset size
  • Sane configuration

Downsides:

  • Has some rough edges, when you need to hack some styles with custom overrides. Not many, but still.
  • Isn’t developed very actively. But maybe that’s an advantage in the modern world, who knows? :)

The whole Bulma repo is added as a git submodule to the blog. Then from sass/site.scss I can import the required components, and Zola will compile them into a single CSS file.

The result is pretty awesome: I maintain only ~250 LOC SCSS stylesheet, most of which is a custom table of content implementation . This file is rendered into a ~200KB CSS file, which is a bit too much, but not drastically.

🔗Gitlab

I use Gitlab as a hosting service both for the code and the rendered content. The CI setup is pretty straightforward:

  1. Install Zola
  2. Render the blog
  3. Copy it to the /public folder

Gilab then serves it under https://bemyak.gitlab.io/blog. The URL is not nice though, but luckily Gitlab allows you to set up a custom domain. All you need is a domain name and the ability to configure a few DNS records.

🔗Freenom

Freenom is a (free) domain registrar, which serves .tk, .ml, .ga, .cf and .gq zones. For free, you can get a domain only for a year, and then you are required not forget to renew it. The other downside is that there are plenty of scam sites in these zones, so search engines do not even try to index anything there.

You won’t find my blog on Google because of that :)

The other problem is that it is not quite stable: even the front page doesn’t respond sometimes. Also, one of my domains got deregistered for no reason, and I can’t get it back as it entered some weird state and disappeared from their system completely a few years ago 🤷

If you are willing to live with these handicaps, welcome!

🔗Hacks

One last problem is that by the web standards, any website should have a www. resource, but Gitlab doesn’t provide it. The solution is to host a web server somewhere that will do just one thing: redirect www.your-blog.com to your-blog.com. Not having this resolution will make your site even less favorable by search engines, so it’s a good idea to have it.

Once you have a web server, you could add a www A-record to a DNS service that will point to that web server. But where to find it?

Luckily, I was already running a server for my Telegram Bot (the post about it is coming soon!), so all I had to do is to change the Caddy’s configuration file a bit to add the redirect.

The server runs on Oracle Cloud, which gives you two VPSes for free. Take a looks at my terraform scripts, which create these resources.

🔗JavaScript ✋

You might have noticed that I try to avoid JavaScript as hard as I can. JS is a cool language with lots of great features, but using it on a simple static website seems like an overkill to me. I advocate for using it when it really makes sense: dynamic applications with intensive user interactions. My blog is definitely not in that category :)

Unfortunately, nowadays JS sticks out of everywhere, even CSS frameworks tend to depend on it, which is bizarre in my opinion. You still need to have JS enabled to view the blog properly, since iframes use it a lot (e.g. Google Maps, Youtube), but it is not required for basic functionality.

This also means that I have no trackers and I don’t know how popular this blog is, which posts are interesting and which ones need improvement. I could potentially check an access.log, but since the blog is hosted on Gitlab, I can’t do even that. However, I consider this as a good thing. I (imagine that I) write content mostly for myself and a few people that I’m familiar with. This takes a lot of pressure off, so I can relax and not think about views and being 100% accurate all the time.

🔗Conclusion

Overall, I’m pretty happy with the setup right now. The blog is lightweight enough to my taste, easy to maintain and hack on. It also costs absolutely nothing.

The editing process is enjoyable: markdown allows me to focus on writing and not spend too much time on technicalities. Once the post is pushed and draft is set to false in a preface, the job is done.