This site is created using the Jekyll Project, a resource that allows me to maintain the site construction as templated html and css while leaving the content to be edited more dynamically using Markdown, a common writing format that makes editing and maintaining HTML content simpler and straightforward.

Some time ago, I had a self-hosted implementation of Wordpress. Ambitiously and naïvely I thought that to have more legitimacy as a tech professional I ought to maintain the site myself. But I encountered many issues with upgrades and some problems accessing and updating files via FTP. To simplify my life greatly I moved to a wordpress.com account, hosted in the cloud. Migrating the content over was really easy. It was easier for me to manage just content instead of worrying about the technology side (lesson learned). But a web-based content management system still left me with a lot of issues as I started to revamp my content. Because I wanted full control over my content (and its appearance), and be able to create the right structure for what I wanted to share, Medium.com and other blogging sites were not a good fit:

• I wanted to own and control what I put into the world
• I wanted to combine work and writing in a single place with different formats
• For displaying my work I wanted to highlight all types of content to reflect my work accurately, not focusing visual outputs

I ended up switching to Jekyll, very simple platform that allows me to do what I need and not get in the way. Admittedly at first it felt like a geek project where I might switch to some new tooling because it’s fun or interesting. And it can require using the Terminal, MacOS’s command line interface. And it requires you to work in Markdown, which was a prerequisite for me. But this new system has already paid dividends, making it easier and more natural for me to organize and develop content out of old projects and posts.

The reason the Jekyll setup works for me are these:

1. Maintains files in a single source of truth
2. Allows for quick and easy iteration
3. Supports my learning goals
4. Enables Future modularity

I’ll go deeper on each of these below:

1. Maintains files in a single source of truth

I can compose, edit, tweak content in the same location and original format. No need to copy/paste content or maintain it in multiple places.

When using Wordpress.com I had to upload my content, both the words and the images or other assets, which effectively duplicates it. When found a spelling error or needed a formatting change, there was no simple path I found to tweaking in my site and changing my local copy at the same time. The version I kept for myself would forever be dated, no longer the “real” version that I published. It’s just a draft regardless of how close it might be to the final version.

It was also tedious to organize and understand the files and assets I had available. With local files used by Jekyll and checked in to Github, I could rely on my computer’s file system to organize

This also means I have a backup and version control integrated into my workflow, so I never have to worry about that again as I used to when I managed the Wordpress technology for myself.

2. Allows for quick and easy iteration

I can quickly make small or large changes and have them update instantly in the browser.

Wordpress does not have a code editor, and the only way to add CSS is by pasting into a single text box. It doesn’t support variables or any real way to iterate, so it requires a clean and bug free version stored somewhere else to iterate on and copy from. I’m not fluent in CSS yet so being able to see a real class structure and edit styling in a typical way helps me get a tighter development loop. When you start up a local build of Jekyll it will automatically update any saved changes to a file, so I can see my changes . This is the best way to learn when using code: being able to quickly see the output of your work and tweaking it. It allows experimentation and is quite reassuring when working with technology you don’t know perfectly well yet.

For publishing final content, I currently use Vercel to host the site itself. The service automatically publishes a new version of the site in minutes whenever I push new content or changes to my gitHub project.

3. Supports my learning goals

Minimal complexity to start and any additional complexity is opt-in. This allows me to stretch myself in the right way and only as-needed.

As a software design professional I know a lot about software as a medium, especially web tools. But this is a broad field and while I’ve studied basic programming (and have coded in Java and ActionScript) and I understand the general principles and constraints, I would like to bridge some of my skill gaps when designing content layout, information architecture, and page styling. Jekyll allows modular creation of HTML widgets, fully customizable CSS, and ways to build up information structures over time (e.g. categorization, tags, etc.) Also, I can run the site locally on my laptop and check in code and manage versioning through Github, so it handles needs for backup and version control while keeping me trained on github concepts as well.

While the MacOS terminal is not a particularly familiar interface (though I’ve run and iterated on local builds at my previous company), I’ve found copy/paste is a perfectly fine workaround, and I’m not ashamed to say so. Understanding and manipulating HTML and CSS is much more appropriate and interesting for my line of work.

4. Enables Future modularity

I can rest assured that if I want to update or transform my site or parts of the content in the future, my content is stored in the most simple and adaptable format.

In technology it’s convenient to adapt to future changes if the data storage format is more universal and malleable. Markdown and native HTML are the most straightforward for future adaptability of content. Markdown is stored in plain text and HTML is the standard technology that powers internet browsers. So I can easily or even transfer content to a completely different technology, reducing the lock-in that comes with investing in a platform

If I choose to make incremental or overhauling changes to the site, its structure, or interactions, I can do so with little pain. HTML can be inserted directly in the markdown, so they can coexist nicely. And javascript can be added to HTML if I really decide to get fancy.