I’ve thought about having a place to write for a while, but nothing really jived with me so much — until recently. This is a collection of thoughts and a reference on how this blog is setup and alternatives I considered.

I don’t expect my motivation to last very long, but hey, at least this is another excuse to put in some writing exercise. If nothing else, it serves as future reference for me once I return to it in 3-5 years.

Warning: This might be an pretty boring read if you aren’t actively trying to build a blog and you have the same requirements. You have been warned ⚠

Contents

• Requirements
• Approach
• Solution
• 1. Authoring
  • Markdown
  • Code
• 2. Building
  • Astro web framework
  • Extensions
  • Video and animation
  • Analytics
• 3. Deploying
• Conclusion
• Annex
  • HTML output comparison
    • Astro
    • Ghost
    • WordPress
    • Drupal

Requirements

• Ownership - if I am to put in some time and effort into this, I should have a reasonable amount of control over it
• Simple - if I need to manage databases or anything in the vicinity of that, I’m out
• No vendor lock-in - content is ideally plain text with maybe some extra bells and whistles - plain text has existed for 50 years, and will likely be around for the next 50
• Low maintenance - if I forget about it for weeks, months, years, it should still be up with no issues or vulnerabilities
• Easy to write - if the authoring experience sucks, I will never write anything
• Flexible - if I want to extend it with my quirky ideas, it shouldn’t be unnecessarily hard to do so
• Community support - yes, I can write a hundred bash scripts myself, but it’s better if I benefit from standing on the shoulders of giants
• Cheap - I’m cheap, so it helps if the solution is too

Approach

Before jumping into the solution I chose, I’ll list a few alternatives I considered and why I didn’t go for them.

• Medium, dev.to, Ghost, Blogger, WordPress - these are fine if you just want to write, but I don’t like the ownership, lock-in, flexibility, or cheapness aspects
• Self-hosted Ghost, WordPress, Drupal - not very simple or low maintenance, I don’t want to have to keep fiddling with them too much, also have varying levels of lock-in
• jekyll, hugo - neat static site generators, but I don’t often use Ruby, Go feels awkward for HTML
• Ad-hoc Markdown scripts - very low level, will get annoying quick, no community support

Solution

I am using the solution described in the next sections as of the time of writing. As it’s not just a single piece of technology, so it can serve as a reference of all the parts that go into authoring, building, and deploying the blog.

In short, it’s based on Astro and some surrounding support tools and machinery.

1. Authoring

It always felt like if I wanted a visually pleasant editing experience, I had to use a WYSIWYG¹ or a block-based (think Notion) editor. That brings along all kinds of annoyances having to get used to the quirks of the editor, plus the saved content is often also some messy JSON/HTML soup stored in a hard-to-access place.

On the other side of the spectrum is using a code editor to edit raw Markdown², which gives you a lot of control, but then you have to stare at raw Markdown all the time. I mean, that’s not so bad, but having to keep jumping back and forth to have any semblance of what it would look like at the end is a bit annoying.

Markdown

I still like Markdown a lot as a format as it’s simple and widespread, so I was happy to discover MarkText. It has its own quirks, but it’s very simple, has a very nice WYSIWYG editor, and is completely native to Markdown. It even goes beyond just simple Markdown to provide a good editing experience for a bunch of extra stuff, like equations, behold: $F = m \times a$

Code

Of course, for anything beyond writing text, pasting images, and writing equations, I fall back to the trusty VS Code. Here are some extensions that come in handy in this case:

• Astro - language support for Astro files
• Manim Sideview - video/Image live previews and code snippets for manim
• Markdown Preview Github Styling - I don’t have a big need for the in-editor preview, but it’s nice to have a similar style if I do open it

2. Building

Astro web framework

I read a lot about folks using Astro, but I never knew what it was or why I would use it. I assumed it was like one of those heavy-weight “do everything” CMS management framework system management platforms, where you need to spend 3 months of research to understand how to configure it to build a blog and 6 months to extend it slightly, with the result being terrible HTML div soup. See HTML output comparison.

I was pleasantly surprised that it wasn’t, mostly. I say mostly, because there are still some quirks, but the default example Markdown blog setup is really nice.

Extensions

• Expressive Code - fancier code blocks
• remark-math - $f_{ancy} * m_{ath}$
• rehype-figure-title - image captions
• rehype-autolink-headings - self-link headings
• reading time - Adding reading time to Astro without the hassle - Jahir Fiquitiva
• remark-video³ - custom plugin for embedding loopable videos
• remark-email-me³ - custom plugin for adding “email me” links

Video and animation

For Photofield: Origins I used Manim Community Edition to produce the animations and OBS Studio to record the screen, plus some custom plugins and scripts to post-process and embed all of this into the blog post³.

Analytics

In my shameful vainness I will admit that I am interested in traffic counts and referrers, so I set up some analytics for this purpose. GoatCounter seems to be the most no-frills simplest privacy-preserving solution I’ve found. Currently I am using the free hosted version, which seems fine. @me if you find this outrageous.

3. Deploying

I already knew I wanted a static file host and there are many great and free options, GitHub Pages, netlify, vercel, probably others. I’m sure any of these would be good enough, but I’ve had some more experience with netlify, so I just went with that.

They make it extremely simple for Astro sites. You connect a GitHub repo and netlify builds and deploys the site from the main branch. A few more clicks to get a custom domain going and you’re done. Probably ~10min tops. Easiest part of it all for sure.

Conclusion

That’s it. I’ll try to keep this post up to date as I change things, but no promises.

Send me an email or toot if you have any ideas, comments, or questions.

Annex

HTML output comparison

This may be a dumb way to evaluate a framework, but what I usually do is open an example page and look at the HTML it generates.

Astro

Ignoring the data-* attributes, pretty much as stripped down and semantic as you could make it. Look at those tags, those ids, that perfect level of nesting 👌

Let’s compare it to some other frameworks. This is not representative, it’s just a few random blogs I picked from a brief search, but hopefully you can squint and see what I mean.

Ghost

WordPress

Drupal

Footnotes

1. What You See Is What You Get - Wikipedia - do people still use this term? It’s fun to say wizzywig anyway. ↩

2. …or LaTeX? Do people use Latex to write blogs? Probably a frustrating experience if so, lol ↩

3. I’ll probably publish a separate blog post expanding on this 🤔 ↩ ↩² ↩³