Building This Site — blog.papaya.sh

Bienvenue à tous et à toutes! Welcome to the obligatory “how I built this blog” post.

It seems like anyone who does a non-trivial amount of work to create what is essentially a few static HTML files floating around in the ether feels compelled to use their newfound platform to crow about what a difficult task it was. Fortunately, I am no different.

So, what are the existing options?

Building a blogging site is something that I have wanted to do for a long time. Historically, I have been put off by the permanence of purchasing a domain name; my taste in domain names evolves faster than it should (yes, I do think about this quite a lot) and I live in fear that I will impulsively buy something that I will later regret.

Anyway, in my mind, there are two services one can use to host a static site: GitHub Pages and CloudFlare Pages. I have used GitHub Pages before and I don’t particularly want to re-live that experience¹. As a result, this website is delivered to your browser grâce à CloudFlare—remember to say thank you the next time you have to complete a CAPTCHA.

Now, CloudFlare Pages benevolently provides documentation on how to use about 30 popular static site generators, including Zola and Hugo, which were the main two I looked at. Both frameworks seemed fairly mature and had an abundance of themes created by their respective communities. However, Pages also allows you to run your own script to assemble your content². For me, the choice was obvious: I’d rather hack something together myself than wrangle with someone else’s idea of “flexibility”.

What is a static site generator anyway?

The first step of any programming project is choosing a language. I chose Ruby because I have been trying to learn it recently and I think dynamically typed languages are fun to program in. Also, I don’t think there are a great many existing static site generators written in Ruby³.

After a quick consultation with my LLM of choice, I was introduced to Redcarpet and Rouge—Ruby’s answer to Pygments. It was fairly simple to throw together a working example using these libraries (Rouge even provides a plugin to interface with Redcarpet which I found cute).

require 'redcarpet'
require 'rouge'
require 'rouge/plugins/redcarpet'

class Renderer < Redcarpet::Render::HTML
  include Rouge::Plugins::Redcarpet
end

renderer = Redcarpet::Markdown.new(
  Renderer.new,
  fenced_code_blocks: true,
  tables: true,
  footnotes: true
)

markdown = File.read 'posts/building-this-site.md'

html = <<~HTML
  <!DOCTYPE html>
  <head>
      <title>Minimal example</title>
      <style>#{Rouge::Themes::Github.render}</style>
  </head>
  <body>
      #{renderer.render markdown}
  </body>
HTML

File.write('post.html', html)

I ran this code on the markdown used to generate this blog post. Here was the result.

A screenshot of this blog generated using the code above — It looks… about as alright as your browser’s default style can look.

Why Ruby feels so good to use

Okay, the first attempt is alright, but it’s not exactly what I was looking for.