Benoit J - My mostly tech blog

Blogging Setup

2020-05-24

In this second post, I’ll go over my thought process to create / publish a blog using markup languages and couple of tools.

The objective of my setup was to be done quickly so I can write something else than software configuration :)

My hopes for my blogging setup:

  1. something I can use from day one, get out of the way, and allow me to improve at a later time
  2. automated build and deploy
  3. use a markup language like commonmark/markdown, org-mode, or Asciidoc. Preferably org-mode since I want to use org babel with code blocs.
  4. simple
    1. presentation in a super simple CSS
    2. use HTML5
  5. learn something I haven’t done before

Spoiler alert: it’s possible to get up and running in one day, if you accept some compromise and don’t get stuck on trying to make everything perfect.

Disclaimer: There are much easier way to get started using platforms like Wordpress or write.as. This solution is tailored to what I’m comfortable doing, it may not be the right solution for you.

Disclaimer2: This is not a howto guide, but hopefully source of inspiration.

Build the site

Couple of options I’ve looked at:

  1. use something like pandoc with couple of shell scripts or Makefiles Great to convert single files. Could have worked for a 1 day setup, but not necessarily easy to get going on a free CI platform. Also a I bit too custom to my liking if I want to create templates, archetypes. All possible, but I suspect too needy.
  2. use org publish with plain org files Not too convinced with this one. It feels like pandoc, but in Emacs :). Easy to start, but would not be great to integrate with a CI platform.
  3. use the great export plugin ox-hugo - Org to Hugo exporter from Kaushal Modi Would work better for me since this is a bridge between Emacs/org-mode and a static site generator. The main downside to me is that I did not used Hugo before, and this creates abstraction on top of Hugo. Would Be a good addition once I know Hugo.
  4. use a static site generator like Jekyll or Hugo Since I have some hope to use ox-hugo in the future, I did try to get Hugo working for my blog. Hugo also support org-mode in addition to markdown.

Prototyping

Followed the Hugo getting started and got a two dummy post created.

This is really easy to get started. Here are the main steps:

  1. create a site
  2. associate a theme
  3. create some posts
  4. run Hugo in server mode and open up your browser to http://localhost:1313

That’s all you need to get started.

The hardest part is yet to come. Teeming and Rendering.

I really like clean and simple. Now there are many nice clean/simple theme on Hugo site, but the ones I liked had big CSS and many even made use of JavaScript. Also, none made use of simpler elements defined in HTML5.

What I was looking for was in the spirit the opinionated thebestmotherfuckingwebsite.

Found this now unmaintained Hugo theme: https://github.com/mpcsh/hugo-theme-motherfuckingwebsite

Made my own version to be able to make it work:

The templates and CSS are quite simple but not HTML5.

At this point, it’s good enough visually, on my laptop… No time to waste, next step!

Deployment

Some hope for deployment:

Couple of options comes to mind:

  1. github pages
  2. gitlab pages
  3. netlify

Here, my objective is to get it done ASAP. so no A/B comparison of which on is best. The first hit that seems to work is king :).

Search string from the first thing that comes to my mind: hugo publish netlify github First hit: Host on Netlify | Hugo

That’s it, I have my solution :)

Followed the guide, starting with the dummy site above. I ended up swapping it with this a new github repository benoitj/blog.benoitj.ca: my blog sources.

Now each time I push new changes, I can see it on the generated netlify domain.

domain name

Now, lets get a custom domain setup.

I already own one, so after a bit of research found the Netlify guide to Configure external DNS for a custom domain | Netlify Docs

Finding the doc was the hardest part, Netlify appears to sell domains in addition to website hosting. So the first few guides are over setting up Netlify DNS.

If you are in the same situation, you will have to setup a CNAME pointing to the Netlify domain name assigned to you. Don’t forget this will take time for the DNS entry to propagate over the Internet and work (from minutes to hours).

Improvements since the first post

Someone spotted a broken link in my about page. Turns out the default version of Hugo used on Netlify does not properly support org-mode.

I updated with success the ENVIRONMENT variable HUGO_VERSION to 0.71.1 and it did fix the issue.

I ended up creating a netlify.toml in my site root to control the Netlify build.

Here is the minimum setup in netlify.toml:

1
2
3
4
5
6
7
8

[build]
publish = "public"
command = "hugo --gc --minify"

[context.production.environment]
HUGO_VERSION = "0.71.1"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

It’s now possible to enable checklinks plugin on netlify.

Since I already have a netlify.toml config to control the build, it’s just a matter of adding this to it:

1
2

[[plugins]]
package = "netlify-plugin-checklinks"

Site improvements TODO

Here is my unsorted list of things I may improve:

Some reflection

I did managed to get out of the software / technology faster than I thought.

The danger for me was to spend all my time customizing tools and not writing a single post. I would have learned something for sure, but missed other learning opportunities.

I hope others can find this helpful.

I’m thinking, if I reach 10 posts in the next 2 months, I’ll be on the right track :)

Coming next

Some topics I may write about

This is day 2 of my #100DaysToOffload. You can read more about the challenge here: https://100daystooffload.com.