I Made My Own WordPress Theme

I made my own WordPress Theme for this blog. In this article I'm going to describe the development experience, and some interesting things that happened along the way.

Even though the source code repository is currently private and nobody else can see it, I named it Upekkha, since I have a deep appreciation for Buddhism and its teachings. This is the concept of equanimity, which is something I try to consistently incorporate into my life. Also I thought it sounded cool 😉.

Key Features and Challenges

Here are some random facts or insights about the development process, in no particular order:

• I had some trouble with the WordPress API. I found it extremely quirky. It truly feels like it was made 20 years ago.
• The look & feel is about the same as my previous theme. I used my previous theme as inspiration, and copied most of the design. There are some notorious differences, particularly the homepage has a more compact view, showing a grid of posts (my previous theme had a long list instead).
• I used TailwindCSS and AlpineJS.
• I implemented dark mode.

The Development Experience Was... Interesting

Some people consider PHP as a language you use when you want to get hacked. I personally think PHP is a great language, even though I don't frequently use it for things other than WordPress. However I did have a moment where I misconfigured the web server to start serving raw PHP files instead of executing them. That was my fault, and probably a skill issue, but nevertheless, most other technologies would prevent something like this from happening.

On the other hand, I also had a moment of nostalgia while coding this project. PHP is one of the first languages I ever learnt, and used it a lot during my teenage years, but I stopped using it in my early 20s.

As a full-stack engineer, do I think WordPress is still worth using in 2024? A lot of people prefer to create their blogs using more modern technologies, or whatever, but for me my blog is for writing, not for implementing. I want to write without having to think about coding the site. As a content management system (CMS), WordPress fits this purpose pretty well, so I'm content with it.

The Importance of Content Portability

As you may know if you have used WordPress, the native text editor is a block based editor, which allows you to display things like paragraphs, images, code blocks, quotes, etc.

It was a bit of a nightmare to write the styles to each individual block in my CSS file, since some blocks can have variations, like centering/justifying, and so on. Maintaining the CSS for every single possible block type proved to be very tedious.

After pondering about this issue for a bit, I took the decision to ditch the default editor, and start using Markdown as much as possible from now on. Markdown forces you to use simple formatting, mostly just headers and paragraphs, but it also supports images and quotes. I'm still not sure if I'll continue to use MathJax (for math formulas) or whether I should use a different library/plugin for displaying code blocks.

I also want to make sure my content can be ported to other platforms such as Medium or other blog CMS, if I decide to stop using WordPress in the future.

Learning About Accessibility

Accessibility is a topic most front-end developers ignore, but I wanted to fill this gap in my knowledge, so I took a few online courses and implemented some of what I learnt in my blog theme.

I'm by no means an expert, but I was able to implement a decent TAB key-based navigation, and fix some color contrast issues I initially had.

As a person who mostly browses the web using a keyboard, I find it pretty annoying when a button isn't focusable or clickable unless you use the mouse. I mainly use the Vimium Chrome extension, which allows you to scroll up/down, click on links, and do many other things using just the keyboard.

Using a text-only web browser or screen readers is a good way to check if the important parts of your content are properly being extracted. Using semantic HTML and proper labelling helps a lot here, and I guess this has the potential of indirectly improving SEO as well, since the content can be parsed by the scraper in a more precise way. For a text-based content website, such as a blog, it's important to have screen readers extract the text properly. Even if you don't use screen readers, having a clearly defined content structure would make it easy for apps like Pocket to parse the content properly and save articles for a later read.