Making a Blog with Astro and WordPress REST API

So I went on a ✨journey✨ over the past few months trying to figure out the best way to start a personal blog site! I built my last personal site with Vue.js/Vuetify and attempted to build out a new one in pure HTML/CSS/JS before I realized that it would not completely suit my needs. I could have went with any of the reputable website builders out there but I wanted customizability, speed, and simplicity. And most important of all, not spend hundreds of dollars per year to maintain the site.

I found my answer in Astro, a fast and newer web framework that pairs well with many different headless CMS options. If you want to build your own blog site, this is a great tutorial that I followed which shows you how to build one with posts written in markdown.

What intrigued me the most what that Astro serves no client-side javascript by default. You can add client-side javascript if you wish or any modern framework you wish. It’s super flexible.

I chose to pair Astro with WordPress, since I already had experience with using WordPress and the public availability of their REST API was a huge plus. However, WordPress’ REST API — as I’ll describe later on this page — can be a bit tricky to work with, so there is a plugin made to simplify managing blog data called WGraphQL. It’s completely free but to integrate it without going through the official way (paying for a WordPress Business plan), can be a bit of work! If you’re going the free route, check out “Learning from Mistakes” section below, and this great tutorial on how to integrate it.

1. Tech Stack
2. Learning from mistakes
3. WordPress Rest API
4. Other features
5. Summary
6. Next Steps

Tech Stack

• Astro
• WordPress REST API
• Netlify CI/CD deployment

The Pros — with this tech stack I’m able to:

1. Have full control over the look and feel of my site
2. Leave the post management to WordPress instead and not have to worry about coding a blog from scratch
3. Have the flexibility of writing simple posts in markdown files (this is an option great for devs so you don’t have to wrangle with a specific CMS).
4. Conversely, using WordPress means that I can move all posts to another site in the future, if I decide I want to rebuild my site (instead of all my posts being held in this one site)

The Cons:

1. Building your own blog site means there are some hoops you have to jump through before you can really start writing. The process would have been way worse if I didn’t use a framework like Astro though.
2. There is lot of more learning and hoops to jump through when using WordPress API or WPGraphQL. I think creating posts in Markdown is the most straightforward method but I prefer looking at a CMS for writing instead of a code editor.
3. CSS hierarchy in Astro — it can be confusing to work with at first but you do get used to it.
4. Not great if you want to build a single page application.

Learning from mistakes

TFW I spent so much time trying to get a decoupled WordPress set up with WPGraphQL and realized it wasn’t working for my purposes:

Images

The main issue that I ran into was image hosting. If you are fine using a separate image host for the images on your blog, or if you’re fine paying for hosting for your WordPress backend site, I think that WPGraphQL would be a great way to go. But since I was already writing and uploading images onto my local WordPress blog, it was another extra step that I wasn’t willing to do.

Note on images: Astro handles images a little bit differently. If you want to display images on your site, you’ll want to process locally-stored images the way Astro likes or link to an externally hosted image. Processing the image, thankfully is pretty simple and just requires you to use the astro <Image/> component (which requires an alt tag — woo accessibility) and importing the image file path.

WordPress Rest API

Of course, I chose the harder, more headache-inducing but 🤑FREE🤑 route for my blog. The downside of the REST API is that you have to learn the specific architecture for it, as you’ll see below.

Retrieving Posts

• The Astro integration with WordPress page here does a good job at outlining the basics.
• For posts, I think it’s pretty straightforward on how to get certain data. However, for pages it was not as clear. For example, posts return a featuredmedia field. A featured media can also be added to a page, but when you are retrieving multiple pages and want to access the field, you have to look under the _embedded object instead.

Styling

• You can customize things like font, color, size, etc. of the data that you receive but I found applying styles outside of that to be challenging. This is because WordPress allows a lot of customizability with their themes. So it’s kind of a given that the REST API response itself won’t include specific styling.
• So then what to do if you want to style the content from the API response? Well according to the CSS hierarchy of Astro, you can create a global CSS file and apply your styles there, which is what I did. Here’s a case on where I had to apply styles globally.
• Case: Image and Embed Alignment
  • By default, images and embeds come in left-aligned. Even if you apply alignment within the WordPress editor, there are no styles being carried over since it’s styled by the class (e.g. aligncenter for center alignment as seen in the screenshot below). So this functionality is dependent on the CSS of your own site.

Smoother page loads – rendering custom fonts

• I’m using a custom font from dafont on my site and I noticed that the text with the custom font would flicker when the page loads. The text is getting set to the fallback browser font and then gets set to the custom font.

• This is jarring and definitely not ideal. But even though this is handled by the browser, there were things that I could do to make the page load a bit more smoothly.
• 1) Optimize text rendering speed
• 2) Change how the fonts are downloaded and displayed through font-display (inside font-face) — guide here
  • This worked for meee!
• 3) Preload the font — this probably works in most cases but I had tried using this to no avail with the custom font. It was difficult to figure out how to reference the font within the styles, because you aren’t specifying its name, whereas with font-face, you can give any name to the font.

Other features

Web browser card component

If for some reason you wanted a little web browser card component like the one on my Projects page, I’ve recreated it here.

Blog comment section:

• Cusdis: A free alternative to Discus. It can either be self-hosted or use their host, which has a limited free plan. But it works for my small little blog. 🙂 Super easy integration, the only downside was the color and fonts aren’t customizable — just has a light and dark version.

Reading time:

• Reading-time: also compatible with markdown, html, etc.

Summary

Astro is one of those frameworks that offers a lightweight build with tons of options for customizability — you can choose what other front-end frameworks and CMS to use. It did take a bit of learning curve, especially with regards to CSS, but overall, I think this is a great framework to get a blog up-and-running for beginners and more experienced coders alike!

FYI, it took me like a week to get all the pages set up, and then subsequent on-and-off working on it for a few more weeks to fine tune and add in more features. So if you decide to create your own blog, Astro is definitely the easiest but it’s still going to take some time. If I were to go back in time and give myself advice, it would be to not be discouraged whenever I ran into an issue that set me back. 😤

Next Steps

Besides what I’ve already implemented, here’s one thing still on my mind:

• Fetching new posts and updates

Since Astro pages are static by default, all data is fetched at build time and not updated automatically. In Astro, there’s a few ways that you can tell the page to fetch new data:

1. Astro has a Server Side Rendering (SSR) feature that can be enabled for the whole site and then configured on a page-by-page basis. This method would work great except it doesn’t work with dynamically generating pages (which is what I use to create my blog pages). But a key function that dynamically generates pages is getStaticPaths(), which in the docs, the only way for you to get this working is if you define the routes beforehand — which is not convenient to do if you’re dealing with several blog posts.

2. Include a front-end framework that allows for dynamically fetching data — like React. We can use React in an Astro project due to its “island” architecture.

3. Include data-fetching in the client side. This may cause a bit of delay in rendering content, since it’s done after build time.

To me, this is not a huge priority for my site since I can easily re-build and re-deploy it but I’ll likely explore this more when I play around with some front-end frameworks.

But here are some of my next areas of exploration:

• Assigning Categories to posts
• Add in an RSS feed
• Add in some basic SEO
• Exploring Astro’s island tech: adding in a modern framework like React, Vue, etc.
• Figure out the best way to display images — am planning on building a gallery page with all my art, comics, and more!