How I Made This Blog

Published: June 15, 2023

I am happy to announce that I finally got around to making a technical blog! Regardless of the utilitarian benefits we get from recording what we learn (e.g. Zettelkasten, Second Brain, etc.), to create is such a supremely human experience and avoiding it has made my fingers quake with anticipation. Another aspect is that I’m an extremely curious person with an embarrassingly wide range of interests and while Obsidian has certainly filled some of this void, creating a public blog provides a way to share things I’ve learned with others–which is guaranteed only to be read by people who care about the subject matter!

Folks, I gotta tell you that there are few things more disheartening than meandering down an exciting tangent only to discover from your periphery the anxious, darting eyes of your audience who have been accidentally taken prisoner by your conversation.

You read more about his endeavors here where you can read the scripts he wrote.

Going forward into this post, I’m going to assume you know all about Obsidian and why it’s the Bees Knees. Also, I’m also assuming you are aware that Hugo is a fantastic Go language based framework static site generation (SSG). While I’ve used other static site generators like MkDocs, Hugo permits so much customization that it’s not even in the same league.

Anyways, while I did follow a lot of what Network Chuck did, I did it slightly differently.

Creating an Obsidian > Kate > Gitlab > Netlify Pipeline

Inside my vault, I created a “PUBLIC” folder, where I placed the folder for my project. I simply dragged and dropped my .md files there.

In my code editor (I use Kate – I’ll explain why later), I then followed Hugo’s installation instructions, found here. One can pick a theme and they’ve got plenty to choose from, but in my case, I wanted to do it the hard way and created my own theme. It took two days straight for me to understand how everything went together, but in the end, I found it incredibly enjoyable. While it isn’t anything spectacular, I’m happy with it. In case you’re wondering, I used the Bulma CSS framework to help me out.

Once I finished my styling, added content, and run it locally using hugo sever to my satisfaction, I performed

git init
git commit -m "Initial commit"

to commit locally.

Features to Consider If Using a Custom-Theme

Also, before I forget, there were two other features that I also added which really helped improve the site. I create a very simple Cognito form, to permit anyone wanting to receive my newletters to easily sign up (which I hope to improve with a custom software solution in the future).

However, another important thing that end users need to do is be able to search a site; many themes already have this built in, but because I created my own theme, I needed a way to make this happen. I ended up selecting pagefind which already provided a JavaScript script and CSS styled HTML. You can install it with npx, but I chose python. I created a virtual environment: pyton -m venv venv and completed the installation as the documentation states. However, there is one little catch. Pagefind’s UI doesn’t currently account for dark mode, so I needed to add the following to my CSS:

@media (prefers-color-scheme: dark) {
  :root {
    --pagefind-ui-scale:.8;
    --pagefind-ui-primary:#aaa !important;
    --pagefind-ui-text:#aaa !important;
    --pagefind-ui-background: #152028 !important;
    --pagefind-ui-border: #152028 !important;
    --pagefind-ui-tag: #152028;
    }
}

Note that I only added the !important tags since I wanted to override pagefind’s utility classes and that it’s generally not something I recommend. Once all the styling was complete, I commited locally again.

Setting up Netlify and Gitlab

In Netflify, I logged back into my account (it had been a while, unfortunately) and created a new site. I grabbed my site ID and created an access token. Then in gitlab, I create a new private repository and declared two project variables NETLIFY_SITE_ID and NETLIFY_TOKEN and added the respective values.

Now, going back to the code, I needed to add a .gitlab-ci.yml file (not .yaml –found that out the hard way) to tell Gitlab how to carry out it’s CI/CD process. Here’s the contents of mine that I admit I heavily borrowed from Jamie Tanna’s blog as not many sites cover this. It seems netlify wants to handle your CI/CD or use Github Actions. Well, I like gitlab, so I guess I’ll be THAT weirdo that makes things more difficult. Anyway, here are the contents of my file:

image: ubuntu:latest
stages:
  - build
  - deploy
build:
  stage: build
  before_script:
    - export DEBIAN_FRONTEND=noninteractive 
    - apt-get update && apt-get install -y git-all python3 python3-pip python3.12-venv hugo
    - python3 --version
    - python3 -m venv venv
    - source venv/bin/activate  
    - pip3 install --upgrade pip  
    - pip3 install 'pagefind[extended]'
  script:
    - timeout 30s python3 -m pagefind --site public --serve || true
    - hugo --verbose  
  artifacts:
    paths:
      - public
deploy:
  stage: deploy
  script:
    - apt-get update && apt-get install -y curl
    - curl --version
    - curl https://github.com/netlify/netlifyctl/releases/download/v0.4.0/netlifyctl-linux-amd64-0.4.0.tar.gz -LO
    - tar xvf netlifyctl-linux-amd64-0.4.0.tar.gz
    - ./netlifyctl deploy -s $NETLIFY_SITE_ID -P public -A $NETLIFY_TOKEN
  
  artifacts:
    paths:
      - public
  only:
    - master

What does it do?

1. Image & Before Script: It declares that your docker image should be the latest version of ubuntu and installs the dependencies needed for the project. Note that I needed a virtual environment for python to install pagefind, which only permits python 3.9+.
2. Build Script: I ran the indexing command for 30 seconds (it will keep running unless you do a timeout), which in my case has always ran very quickly. Then
3. Deploy: A brand new container will be pulled for deploying and ubuntu doesn’t always come with curl, so I installed it here–adding netlify’s CLI. Then, the netlify CLI is called to deploy the site. Artifacts points to the “public” folder which is where hugo built the static contents on your site; this needs to match your hugo.toml file.
4. Last thing is the last two lines, this pipeline ONLY runs when you push to the master branch. I did that to permit pushing to a working branch without worrying about accidental publication.

When I ran:

git push origin master

The build and deploy pipeline ran as intended and created this pretty cool blog! :-)

Happy coding!