Skip to main content
  1. Posts/

The Ordeal of building my own personal abode

·6 mins

By abode, of course I meant my personal website 🥸

•    •    •

It all started with a need for learning web technologies. The new adventure I have been on needed web development, and I postponed it for as long as I could, we being in early bootstrapping state and the lack of funding. Finally, I had to commit and get chiseling myself.

I wanted to pick and project to accompany and guide me on this journey, and it was staring right back right in front of me 🥺

  1. A mountain of Post-Its / Idea-Cards where I used to scribble my stream of connected thoughts on varying subjects, which seem to pile up on my desk first and then over to my plastic bag and then into oblivion ….
  2. A desire to have a navigation journal of the learning paths I journeyed along, and the context (the What and Why) behind what I picked up.
  3. A way to be able to re-member and re-join and accomplish an abandoned partial journey.
•    •    •

I started with wondering if I should re-learn HTML/CSS/JS, given that that’s what pretty much all websites are made of.

Seeing how basic the capabilities of HTML/CSS/JS are and wondering how much of the wheel do I have to reinvent, I then ventured to checkout if I might benefit from learning any of the JS frameworks like ReactJS / AngularJS or the newcomers like VueJS (batteries included — like vue-router for URL routing, Pinia for state-management etc. … hmmm, I guess sometimes being opinionated IS A good thing 🤔).

Eventually, realizing that it was going to become a full semester project, I started looking for something a bit faster to build + adapt + maintain, and of course fun too.

WordPress has the mindshare in this realm, but I didn’t have a good experience with it in the past, with a constant need for high maintenance (updates/patches etc.). Also, who learns PHP anymore.

Moving away from database driven CMS systems (WordPress/Drupal), make the decision a bit easier for me — Static Site Generators (SSGs). 

Start with your Strength! #

Even within SSGs, there is a lot of choice.

As the saying goes

Start with your Strength!

So, I started with Pelican — a python based SSG. Thanks to a few simple tutorials, I was able to hack up something, but I soon realized its pain points.

  • Non-standard templating language
  • Seriously lacking learning content or active community (of my liking)
  • Ecosystem

After struggling on some minor needs for days, I had to look for an alternative.

As much of a pain Pelican was, it gave me an understanding of the landsape of what is possible with SSGs. Also, while I thought my know-how of python will give me an edge, but it was minimal and only related to ease with toolchain. I wondered if all tool-chains drink from the same waterhole these days, thus adopting similar goodness — so what’s the big deal.

So, my journey with HUGO started.

Journey Log #

Decisions and Installation #

  1. I started with Quick start | Hugo (gohugo.io) — as always, installation was a breeze with homebrew on MacOS — and the number of steps in quick start was indeed short.
  2. HUGO has a lot of theme options to pick from, and every one of them had a GitHub download location and a GitHub demo site built using the theme — see Congo theme for example.
  3. Also, it was interesting that HUGO supported not one, but three configuration formats — TOML, YAML and JSON. While the docs say, all three are given equal priority, I found TOML to be more prevalent.
  4. After considering Ananke, PaperMod, Gruvbox and Hugoplate, I finally settled on Congo, for a few reasons.
  5. Congo is an — extensively templatized theme (leveraging a ton of HUGO provided functionality), and most of the common blogging/website needs are available through simple TOML configurations.
  6. Congo is well documented (with even links to external tools — like https://favicon.io/ etc.)
  7. Congo is an —  actively maintained theme with a strong community.
  8.  I like the design of Medium blogs, and do I plan to continue to publish my blogs on Medium. I found a Medium to HUGO export script, which made bringing my old Medium drafts a bit simpler — though it did need some tinkering.
  9. HUGO Community is very active and very helpful.

CI/CD for Deployment Workflow #

  1. As learning web technologies was the main reason behind this whole ordeal, it was not acceptable to keep manually updating the site.
  2. Most hosting sites have an option to replicate a GitHub repo to a configurable folder within one’s hosting site, via a webhook to be triggered on events like push or pull-request etc. But the problem with this is that source code and assets will also get copied, which is unnecessary. So, I had to think of alternatives — only to realize that the scenario is exactly what we do with software building and deployment.
  3. The choice between Makefile vs GitHub Actions was simple and yet hard 😶.
  4. Did you know that you don’t always need GitHub to run your GitHub Actions Workflows — sounds crazy, but that’s exactly what Casey Lee’s Act project is. While GitHub Actions are cool, I wanted the flexibility to run it locally too. But but but … there are always caveats.
    1. When run locally using act, the workflow is executed in a linux docker container with root privileges and hence do not need to be run with sudo. In fact, it becomes a chicken and egg situation as the default Linux docker containers for MacOS Arm64 didn’t have sudo, but when a workflow is runs on GitHub’s runners, the code does not run with admin privileges and needs sudo. And, dealing with multi-line SSH pvt keys in act environment was a headache to deal with. So, after having successfully executed GitHub Action of deploying to my hosting site triggered off of push operation to main branch, for local execution, I am settling down with my makefile
    2. Ensure that .env file with any secuirty info is not committed into git repo by using .gitignore appropriately. On GitHub, use GitHub’s Secrets
    3. You can see my GitHub Action workflow yaml file at my publicly shared GitHub Gist: GitHub Actions Workflow to build Hugo static site and deploy (using rsynch) over to your hosting site

Looking forward to seeing what new clearings this journey will open for me.

Regards.

Additional Resources #

Pelican Resources #

Medium to Hugo/Md #

Md to PDF #

  • How-To - see GH-Gist-list
  • Pandoc fails to handle unicode chars (emojis etc.) - see SO-link
  • Bulk conversion into single PDF file - see SO-link
  • Replacement for missing pdflatext - see SO-link