Skip to main content

More about this blog

Written Nov 14, 2022, tagged under post

Today, I'm going to go into some more detail on how this blog works. Given time constraints, this is going to be more of a how-to than a detailed explanation of what's going on!

Setting the scene

As mentioned yesterday, this blog works by taking a set of text files that contain the blog content (static pages, blog posts, settings etc) and converting it into a set of HTML files comprising the target website. So the main bits I needed to sort out, based on work already done by others, to make this work were:

  • A place to store the files - in this case GitLab, which is a platform that uses git to store the files in a repository (which is basically a set of files and folders, whose history is tracked so changes can be reverted)
  • Some software to do the website generation - Jekyll, a very widely used and documented static site generator.
  • A theme that did most the work for me. Most static site generators (including Jekyll) have a concept of themes, as a way of taking the page content and making it look a particular way. My starting point was the very handy alembic theme which was designed for easy deployment in the way I needed
  • A place to run the program when the files were updated, to come up with the new website when I make new posts etc. This is where Netlify fits in.

Basically, the clever stuff at Netlify connects this all together to work nicely.

Here are a couple of walk-throughs of what we'll be doing, for reference. There's this one provided by the theme documentation, and also this one from Netlify.

Right, now on to some specifics...

Storage - GitLab

To follow this approach, you will need to have an account on GitLab. This is free, and you should be able to sign up here. It is within this account that the text files comprising your site will live. It is very easy to work with them locally too - git is used by authors as well as software people.

Glue - Netlify

You'll also be needing your (free) Netlify account, which you can sign up to here.

Using the theme to kick things off

On the theme page there's a link called "Vanilla Jekyll starter kit", which takes you through this launch process. Rather cleverly, that will ask for permission to use your GitLab account and Netlify account. It will:

  • Create a new repository based on the theme etc, that is on its own enough to create a website
  • Connect Netlify to the repository, so that it knows to rebuild the site when you make changes

After doing this, you will basically have a website, but with a fairly daft name generated by Netlify. It is easy to then point a domain name at the site if you have one, or get one through them, by going to Domain Management -> Domains in the Netlify website after signing in and launching the site.

Changing the site

So, you have a site set up in GitLab. Each repo has a path, which will be like https://gitlab.com/yourusername/reponame. For instance the reponame part for my blog is seity-blog. You need to get this repo cloned to your local computer. At this point, the site can be updated by editing the local files you cloned to your computer. I'm using a linux laptop here, but I think it's pretty similar on a Mac. Unfortunately I can't speak for Windows as I haven't used it for years, but I'm guessing there will be pointers online for that.

When you make changes locally, you run Jekyll locally (by running bundle exec jekyll serve in the root directory) to check the changes in a browser. Once they look good, you save the changes locally then push them back to GitLab - this is what git is really good at. At that point, Netlify takes over and rebuilds / publishes the updated blog.

A full description of how to use git is well beyond this short article! There are articles on this subject though, which you can research. And hit me up on Mastodon if you have questions, too.

How do the text files work?

Here's an example of a text file - the top of my post from yesterday, in fact:

---
title: Blogs
categories:
  - Blog
  - Wordpress
  - Jekyll
feature_image: "/assets/images/tom-hermans-9BoqXzEeQqM-unsplash.jpg"
---
My original plan for today was to describe in some detail how
I set this blog up ...

The top bit is metadata describing the post - title, categories, header image etc. Then the rest of it is my article, in Markdown. This is basically a way of writing text files that includes format; I use them for everything these days, as it is pretty easy to work with. For example, the above few lines, in Markdown, read as:

And [hit me up on Mastodon](https://mastodon.xyz/@mindshoot) if you have questions, too.

### How do the text files work?

Here's an example of a text file - the top of my post from yesterday

(This post is getting a bit circular!)

In the above Markdown, you can see how the link is embedded, and titles have a prefix etc. You can find out the specifics online, but it's pretty handy for sure.

Conclusion

This obviously is a bit sketchy, but the main thing is I've tried to drop in some links you can use for further research. The result will be more "manual" than WordPress - although my next step in the plan is to use Netlify CMS to put a front-end on the process so you can write posts in a browser etc, in which case this won't be an issue. Also, by defaults your site won't support comments. However it will be very fast and entirely un-hackable, and if you're comfortable working with text files etc then it is very easy to work with.

From my point of view, my daily blogging is now literally no more than:

  • Adding a text file to the _posts folder, suitably named and including the header stuff copied and edited from the previous day, with my blog post in it
  • Downloading a nice picture from Unsplash to make it a bit prettier, and putting it in the images folder
  • Checking it locally, tweaking if needed, then pushing my changes up to GitLab
  • Waiting about 1 minute and then seeing it published

Anyway, that's it for today, folks! Let me know any questions, and I'll see if I can help.

Photo by Sean Stratton on Unsplash