Starting a Developer Journal

- 5 mins read

Why post a public journal?

I want to keep a dev journal to articulate my thoughts throughout the problem-solving process as well as to download new ideas (usually side quests) from my brain to keep my focus. There are plenty of other benefits to writing a developer journal and there is no better time to start than right now.

I want to publish this journal publicly on my personal site to:

  • Show others how I think and work through problems.
  • Not be afraid of showing mistakes or misunderstandings which are part of the development process.
  • Actually have some content for the site which has been mostly empty since I created it years ago.

I currently keep a TODO page in OneNote as I work, but I delete items as they get resolved. With this dev journal, I want to persist the daily tasks and build a habit writing things down as my part of my work flow.

How to build a blog?

Having a dev journal on my personal site will require getting my thoughts from my brain to some files on the VPS that hosts my site. What are some of the options to accomplish this goal?

My constraints:

  • I don’t want to spend (more) money - There are plenty of free options available and I’ve already got a place to host the content.

  • I want to be able to write from any device - I quite enjoy writing from an IDE on my computers, but sometimes it is nice to jot down thoughts on my phone while I’m working through a problem on the go. My first thought is to stick the content into a git repo and host it in GitHub.

  • I don’t want to spend too much time on styling the site - I know there are plenty of off-the-shelf tools that I can offload the task of making things look pretty. I have plenty of experience creating beautiful UIs, but I’ve got other projects I’d rather dedicate my time on right now than fiddling with CSS/Tailwind. I’ll want to find something that I can insert my content into a templated framework and just stick it where it needs to go.

  • Deploys don’t need to happen often - Automated deployments are something I usually prefer to do very early in a project to get software into production for fast feedback, but in this case it’s not something I need right now. However, I’m fairly certain I’ll end up setting up a GitHub Actions deployment sooner rather than later. If I’m hosting the content in a public GitHub reop, the Actions minutes should be free. For the start of this project, a manual deploy should be just fine.

GitHub Pages or self-host?

After ruminating on the idea of deploying site updates automatically on a merge to the main branch in GitHub, I’m wondering if using GitHub Pages to host the site will simplify things versus pushing changes to my personal VPS. I’d rather have full control of the data by keeping on my server, so I’ll stick with my original plan.

Hugo, I choose you!

After searching online for popular tools to generate static site content, I ended up choosing Hugo which seems to be pretty hot right now. It is very customizable and there are plenty of open source themes available. I spend way too much time going through the theme gallery, but eventually I decide to stick with Poison for the built-in light/dark mode toggle and the simple, clean look.

I run through the quick start guide for Hugo and plug in the Poison theme following the well documented setup instructions. I run the command hugo server -D to test out the sample site I created in the quick start, but I run into an error:

ERROR render of "page" failed: "/home/cork/blogsite/themes/poison/layouts/_default/baseof.html:1:3": execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "head/head.html" .>: error calling partial: "/home/cork/blogsite/themes/poison/layouts/partials/head/head.html:16:7": execute of template failed: template: partials/head/head.html:16:7: executing "partials/head/head.html" at <partial "head/meta.html" .>: error calling partial: "/home/cork/blogsite/themes/poison/layouts/partials/head/meta.html:23:13": execute of template failed: template: partials/head/meta.html:23:13: executing "partials/head/meta.html" at <.Scratch.Add>: error calling Add: runtime error: invalid memory address or nil pointer dereference

The issue seems to be on line 23 of the template partial file: themes/poison/layouts/partials/head/meta.html. Let’s see what it’s doing in there:

21 {{ if .IsPage }}
22  {{ .Scratch.Set "title" ($.Site.Params.brand) }}
23  {{ .Scratch.Add "title" " - " }}
24  {{ .Scratch.Add "title" .LinkTitle }}
25 {{ end }}

There is a reference to a Param named brand on Line 22. Hugo is pretty straightforward with its theme options being configured in the top level hugo.toml file. I set the value for this parameter and the Hugo dev server starts up!

[params]
  brand = "CorkBits"

I check the Poison docs, searching for brand and sure enough its the first entry under [params] in the example hugo.toml config file. I suppose I might have avoided the issue by fully reading the docs first, but I prefer to “lean on the compiler” in this exploratory phase of using a new tool to figure out what is the bare minimum configuration needed to get started.

I’m writing this first journal entry in OneNote until I get the skeleton blog site running. Hopefully, I’ll finish laying the foundation in the next day or two to start my new journal writing workflow!