⚛️ No CMS? Writing our Blog in React

Blogs are important. Everyone's got one, and everyone's got an opinion about how to do them best. Standing up a blog can be a fair amount of effort -- you have to host content, link between pages, create directories, make it all searchable, available for SEO crawlers, surface all the right SEO metadata, and so forth. It's no easy feat, and if you're doing it for corporate (SEO) purposes, then there's a fair amount that you can mess up. For that reason, most folks use a Content Management System (a CMS) and/or a static site generator (an SSG) to generate their blog posts for them and take care of all the busywork. Isn't it great just to write Markdown, and then deploy it with everything taken care of? Yes, absolutely.

But it turns out that it's not so easy to "just use a CMS." Like many others, we initially looked into popular ones like Ghost, Hugo, Jekyll, and Publii. (I especially liked Publii because it's a rare great piece of Linux Desktop software.) These platforms are fantastic in their own right, offering great designs, all the SEO-stuff done for you automatically, easy interfaces for writing markdown, and straightforward processes for deploying them to production. However, we quickly realized that despite their appeal, they came with a set of challenges that didn't align with our specific needs.

The primary issue was integration. These CMS platforms are designed to be all-encompassing, creating not just blog posts but entire websites. While this is great for many, it meant that the blogs they produced, though pretty, had a distinct look and feel that didn't mesh with our existing website. Specifically, sure we could write a Ghost blog that used our preferred font and colors, but it still wouldn't have the GetWaitlist navigation header or footer or "look and feel" of the rest of our website. Plus, if we wanted production deployment to be easy at all, then we'd have to host it on a subdomain. Putting our blog on a subdomain presented its own set of technical complexities and SEO considerations. We'd have to maintain and keep in-sync two XML sitemaps, and there's always the fear that even though Google says that a subdomain can be just as good as the parent domain, a lot of folks (us included) just doubt whether that's really true.

We recognized that a full-on SSG wasn't going to do the job. But we didn't really need a static site to be generated -- I'm a technical person, so all I really wanted was to be able to write Markdown, and then get some React Components that were styled well enough to use in my blog. Looking for a solution, I was searching for CMS and SSG systems that fit that mold and output React Components. My idea was that surely it's possible to write a bunch of markdown, and then have that get wrapped in a bunch of JSX tags that come pre-styled, using the styles of your existing repo? For example, what I expected was to be able to write (Markdown for bold) and then get a component that looked like

where is a library-defined React component that utilizes the existing CSS styles of my website. With Tailwind CSS that's super easy, the component would really be something like , and that would be defined somewhere in my Tailwind Configuration. We thought this would be a no-brainer and that there would be some CMS/SSG libraries out there that made this Markdown conversion process easy and facilitated integration with any number of frontend frameworks.

Turns out, no dice. The thing I described above? Super-simple Markdown conversion to pre-defined React Components that use your website's styles? No such thing. We were baffled. This seemed so useful. The Static Site Generation market is super crowded with tons and tons of players; We thought someone would've done it. But nope. So, we concluded we had to do it ourselves. We've taken an unconventional approach to frontend development before ("Rewriting our core React App in Vanilla JS") so we weren't above getting our sleeves dirty and taking on a frontend engineering job that seemingly no-one else wanted to do.

We wanted a solution that allowed us to maintain our website's unique branding and user experience without compromise. And so, we started building. The first question was how we were going to model the actual content itself. This turned out to be easy: it's all structured data, so JSON would do just fine. Below is an example (this very blog post!) of how our structured data looks:

From there, you can imagine how it works. We have about 50 lines of code that iterate over every single blog entry, and that wrap all the in some custom-defined React Components. The whole list is then expanded inside a general blog-specific layout (I call it ), that spaces all the paragraphs, etc. correctly. Our blog homepage at https://getwaitlist.com/blog is generated by iterating over all the , and then constructing a little component from the JSON metadata for every blog post. That same metadata is then also rendered in each blog page for SEO correctess purposes: for example, the is both used on our /blog page for the content card, but it also is used as the OG Image when you link to a given post. The same applies for , which naturally populates the visual title of this page, but also the HTML field and the OG Title. It was actually very, very easy to implement.

But is it a pain to write? Well, it's a little harder to write than Markdown. I don't have the luxury of writing links like . I write them like this: and that is a little bit grating, but it's ultimately not such a huge difference. I could write the entire entry in pure Markdown and then write one more step to transpile it into these JSX components, but it hasn't been necessary. (Our documentation is written in Markdown -- the pages are saved as files in our repository, and we've set up that transpilation step. It took a little bit of work, but wasn't too difficult.) Overall, this works well, and the biggest barrier to writing blog posts is not technical, but just overcoming my own laziness to actually sit and write a few hundred words.

The result is nice. By developing our own components, we could tailor every aspect of our blog to fit seamlessly within our website's existing architecture and design styling. This level of customization ensured that our blog felt like a natural extension of our site, rather than a vestigial add-on. As a plus, this setup gives us much more control over the look and feel of our blog content than we would have with a Static Site Generator or Ghost/Jekyll/Hugo/etc.-style CMS. All of those pieces of software eventually hit some barriers in terms of what you can do in them, and for us -- well, we can always just code it up ourselves if necessary.

Another big advantage is that we can now handle all of the SEO stuff ourselves. You might be wondering why I'm bringing this up, since at the start I mentioned that having a CMS handle it for you is such a big plus? Well, sort of. Playing around with a couple of these CMSes, I actually don't know whether they handle all the SEO characteristics as well as you want them to. They abstract too much, and I don't entirely trust them to do the job right. With my setup, I know exactly how all the SEO metadata, etc. is getting set, and I have the inspection tools to verify it, too. Taking charge of SEO myself instead of outsourcing it to a third-party blogging platform has felt like a good decision to me. In the end, it was just very easy to set it up such that all the right fields populate automatically.

My experience doing this has been pretty good and easy. I'd recomend it to you, too. Every time I want to contribute to the blog, I can get started immediately. There's no subdomain to configure, nothing to deploy (other than my standard frontend repo), no software updates or user account or dashboard of miscellaneous crap that I have to administrate -- I just open up VSCode and make a new JSON blob and start writing. Everything behaves exactly as you'd expect, with none of the pains of fiddling with third-party-software behavior mysteries. Writing all your custom React Components for your blog might sound like a huge drag at first blush, but it's really not a big deal. All of this took me maybe a few hours, tops, to set up. The next time you want to integrate a blog into a website and you're trying to figure out which of Ghost or Bubble you want to pay for, consider saving the money and just doing it yourself.