Years ago, I had a vision for my personal site that involved designing purely around content. The idea was to make it easier and more natural to use images in writing. It was definitely a situation where my hopes exceeded my skills. It got the job done, but I was never happy with it. It wasn’t just the site though. It was the process of writing, producing, and publishing. It was tedious.

Over the years, I had chipped away at improving it all, but after going independent again, I wanted to get back to sharing more. So that meant fixing it once and for all. Whether that was code samples, ideas, or other projects, I wanted to have a rich set of options for sharing different kinds of content. I had been working on something like this ever since writing the Software Quality Academy for Sifter, but I hadn’t really followed through with it on my personal site.

For the first time in literally years, I genuinely look forward to writing and sharing. The process has become enjoyable again.

I wanted my personal site to be truly designed for content and sharing ideas. There’s no decoration. There’s not even a logo. And every page is really just content. And, the writing and production process had to be convenient for longer and more complex posts as well as shorter simpler posts. Unfortunately, those two goals don’t mesh well.

Some posts are involved enough that writing and editing in a text editor helps. However, the friction for doing that often outweighs the value for publishing shorter posts. Static-site generators just aren’t super-easy to add new posts and publish.

Writing by hand in a text editor also means remembering all of the rich markup options for figures, asides, footnotes, code, and the variety of other elements that the site supports. So I created a simple single-page guide to help me craft posts. It’s a work in progress and constantly evolving with new posts and new things I’d like to share. It has extensive options for embedding figures, block and pull quotes, asides, code samples, and more. My post sharing ideas behind how my office is configured is a good example of the end result with lots of images in a post.

The Style guide is also great for making adjustments to the CSS. It provides a test bed with examples of all possible configurations for each type of content. So it serves as a sort of framework for manually testing visual elements and avoiding any regressions or issues with responsiveness.

The one thing that really got in my way with a static-site generator was the friction of starting a new post. It was rather manual. You have to start the local server. Generate the new post file. What’s the current date? That needs to go in the post file. Where do the images go? The list goes on. It’s just tedious enough that I didn’t write as much. So I’ve automated it a bit.

The process used to look something like this…

  1. Get the current date for the post filename.
  2. Generate a new file in the _posts directory.
  3. Open the new post file in Sublime Text.
  4. Go to an old post and copy the YAML front-matter over.
  5. Start the server with bundle exec jekyll serve --watch
  6. Open a browser and navigate to the new post page to preview it.
  7. Open the images folder and copy the filenames of all of the images into the new post file.
  8. Generate the figure markup for each image.

…but now I type…

bundle exec ruby write.rb -t "New Post Title" -i

…and everything just happens. I could probably slim down the length of that command a bit, but it’s simple enough for now.

The post file is generated with the current date. It’s populated with the front-matter. With that optional -i or --images flag, it even opens the folder for the images in Finder so I can just drag and drop the images into the correct folder for the post. If there are images, it grabs all of the images in that directory and generates the base markup for them so they look right, and I only have to copy and paste to move them around. Then it opens the newly generated file in my text editor and starts the site generator so the site is viewable. It opens the new post in a browser for previewing as I edit as well. Basically, it removes all of the tediousness so I can focus on the content part.

The script includes some other options and shortcuts, but it’s usually that simple. Here’s the full script in case it’s useful. It’s pretty personalized to my workflow, but there’s likely some ideas to borrow from in there. For publishing, the site automatically gets built and deployed to Netlify whenever I push the repo.

Behind it all, it’s just a normal git repository. So I’m able to move between using SiteLeaf and editing locally without any hassle, and I can always use the right tool for the job.

As convenient as the script is for starting new posts, sometimes I just want to fire off a short post about an idea that’s floating around in my head without having to spin up a new post locally. For those cases, I’m using SiteLeaf. I can hop online and write a short post or share an idea without the friction of dealing with coding locally. That way, I have an advanced option for longer posts with media and code samples and a convenient option for quickly sharing shorter posts. It’s the best of both worlds.

SiteLeaf also comes in really handy when there’s typo to fix or a small change to make. Behind it all, it’s just a normal git repository. So I’m able to move between using SiteLeaf and editing locally without any hassle, and I can always use the right tool for the job.

It has taken a lot of iteration to find a good mix of tools and process that work for my approach to writing, but it’s been worth it. While I occasionally wonder if this process is way over-engineered, the results let me know it’s not. I’m writing more and having more fun doing it. It has completely upgraded the process for me. Regardless of what I’m sharing, it’s covered. It’s easier and more natural to create richer content, and it’s easy to update the documentation or use it to test new ideas. It’s all designed so that I can write in Markdown by default but can easily embed HTML where I need richer formatting.

Naturally, this kind of process isn’t for everyone. It’s certainly not perfect, but it’s been fun to tune, and it enables more writing and richer sharing. For the first time in literally years, I genuinely look forward to writing and sharing. The process has become enjoyable again. Add in the fact that I ditched analytics, and it’s all more focused. Just share things that might be useful, and keep doing it. There’s no more friction or distraction. Just sharing. It only took 15 years of intermittent blogging to figure it all out.