Why I built this site

A new beginning

I've had a site on GitHub Pages for a while, but never felt quite happy with it. I'm not sure whether it was the fact I didn't really understand how it worked (it was a Jekyll site with a template I found online), or the fact it wasn't particularly configurable, or maybe just that I hadn't built it. Either way, I needed to replace it.

Also, I'm a software engineer. I'm supposed to have a nice site, with my own domain - it shows I know what I'm doing, right? (spoiler: I don't know what I'm doing)

GitHub Pages had its place - it was super easy, but lacked control and flexibility. I also didn't really want my own site hosted on GitHub. I have all my code there, so it's not like I'm abandoning them entirely, but somehow adding another egg into the same basket felt less than ideal.

Pages also was a crutch for me on my journey as a developer - it meant I could avoid looking at hosting, at domains, at proper web development. I needed to remove that crutch, even if it meant limping for a bit.

But... how do I fullstack?

I've spent most of my career thus far mucking around in 'backend' - Java, Scala, Python, then a stint working as a Data Engineer. I've done little bits and pieces of web development here and there (I somehow ended up as Team Lead for a bunch of web developers at one point, don't ask me how :D), but generally speaking, websites are unknown territory. I've done the basic mucking around in HTML, JS and CSS that many people do - make a single page, make everything horrific colours and retire, knowing the job was well done.

However, last year I was hired as a Data Engineer at an early-stage biotech startup. How early stage? Well, I was software engineer number one. When I left, nearly a year later, I still hadn't done a bit of data engineering. I had, however, had to rebuild their internal web tools (amongst many other tasks), and in the process had a bit of a crash course in modern web development (I managed to learn enough to hire someone better than me, which I'll count as a win!).

The modern front-end world has fortunately settled down from a few years back (the days of what seemed like a new JS framework every week are past us, I hope!), and now, if you want to dive in, you're generally presented with a three-way choice: React, Angular, or Vue. I had no clue, so asked a friend who knows such things better than me - he recommended Vue for a beginner - a recommendation I was happy to embrace.

Fast-forward to now - I've wanted to build my own website for ages, but now I feel like I might actually have the skills to pull it off without creating a horrific mess - I know what I don't know, so to speak! I'm also at a junction in my life - quitting my job to try and work for myself - where being able to build websites and pick up new skills fast would be extremely useful. Right, let's dive in!

Implementation details

Well, having played around with Vue last year, it seemed like a good idea to capitalise on that, so I went with Vue this time as well. However, unlike last time, I wanted to use tools like npm and Webpack properly. Fortunately, the guides on the Vue website are excellent, and I was up and running pretty swiftly. I'd spent a bit of time sketching out roughly what pages I wanted, and some basic layouts, so the next step was just laying out dummy pages in the right places, putting in links, that sort of thing. With Vue Router that sort of thing is pretty easy, so it only took a few hours to get that in place. Next came content, which was the hard bit.

To MarkDown or not to MarkDown

At this point the complexity increased a little. I had a bunch of content from the old GitHub Pages site, written in MarkDown. I wanted to preserve this, and avoid translating it into something else, and I also wanted to be able to write new posts in MarkDown (years of writing READMEs has drilled MarkDown into my brain - it's very intuitive to write in for me).

However, I also wanted the site to be static, as I'd heard about Netlify as a hosting option for static sites - not only are they easy to use, they're also free for individuals for personal use. This meant I needed a way to render the Markdown into HTML server-side, or pre-render it somehow. However, I was also operating within the confines of Vue. To the Google-mobile!

I read many links, and almost all of them mentioned some framework called Nuxt. At first I was a little relunctant to throw away all my newly created pages, but Nuxt seemed to be just what I was looking for - a higher-level wrapper around Vue, that handled a lot of the common wiring, and was focussed on static websites. Perfect!

A day later, and my existing skeleton was now in Nuxt. Excellent. But what about that MarkDown? At this point, things got a little complicated. I'll leave the full ins-and-outs of the implementation for a dedicated post, but what I ended up doing was following this post, which pointed me to a GitHub repo which backs a pair of statically generated sites, that did exactly what I wanted - Markdown rendered into Vue components! Helpfully, the author open-sourced the code behind his site, which was immensely useful - although it was in Typescript, I was able to reverse engineer how the various elements connected together, and replicate it, then modify it to serve my own needs. What I end up with is Webpack pulling in MarkDown files, which are then read into a Vuex store, parsed using frontmatter-markdown-loader (by the same author as the static sites mentioned earlier), which converts each MarkDown file into a Vue Component, which can then be loaded in however you like. Well, no-one said it would be easy... However, now that I've got it working, it's pretty extensible, and allows for a lot of control over how the content looks and where it ends up.

Deploying - done is better than perfect

Once I had the basic page layout running, and markdown rendering working, I made a quick list of everything I felt I needed to fix about the site before going live. Because I was in the MVP mindset, it was actually shorter than I expected (handy, as everything took longer than planned - the ninety-ninety rule wins again). I worked through them, one by one, deliberately cutting a few corners where yawning great rabbitholes appeared. Finally, I had a working site locally. It's deploy time!

As I mentioned earlier, I'd had my eye on Netlify for deploys for a while. It turns out, all the good things I'd heard so far have been completely accurate - Netlify is pretty awesome. They have really nice GitHub hook integration - it'll deploy from a branch you specify, it'll run test builds from PRs to that branch - as well as simple custom domain integration, and seamless Let's Encrypt integration - making HTTPS a doddle! I poked around a little on their dashboard, and they also offer a Functions API (think AWS Lambda), Forms, Auth, and more. Super nice bonuses, considering I just wanted a static site host - I'm definitely going to play around with these in the future!

My deploy was fairly pain free, as the deploys give logs of the deploy command you specify, so you can generally see what's going on/going wrong. I did get slightly tripped up by a silly mistake on my end, where I was relying on various empty content directories being created (for sections of the site that don't yet have content), but of course git doesn't have those directories, as it only sees files. Doh! Once I figured that out, it worked like a charm.

Where/what next?

There's still plenty to do on the site, but now I've got it released, I can start spreading my time onto other projects as well. As mentioned in a previous post, I'm looking to start a business around mitigating climate change, and I'm also potentially collaborating with someone else on another project in that space. However, in between those, there're still a bunch of improvements to the site I'd like to make:

• Improving the main logo (it's pretty yucky at the moment - I think I need to break out the Wacom tablet!)
• Adding syntax highlighting to code blocks. This proved non-trivial during development, as the code blocks are rendered from MarkDown into HTML, so figuring out where/when to apply something like PrismJS was a big yawning rabbithole. I hope to tackle that soon though.
• A general restyle and tidy-up of the CSS. It works as is, but there's a few tweaks and shiny bits I'd like to add here and there.
• Dynamic routing - I will go into more detail in a dedicated post on the MarkDown rendering, but I essentially have to hardcode some of the page routes for now, rather than generate them dynamically from the MarkDown posts. This feels emminently fixable, but I need to figure out more about how Nuxt and Webpack integrate.