Standing up Blogs

AstroWind + NetlifyCMS = Match Made in Heaven

Context

In an attempt to “build in public”, I figured it can’t hurt to discuss my experience with standing up blogs for Edu-rrhaphy.

Our ambitious vision for Edu-rrhaphy is become a central hub surgeons can rely on to deepen their expertise. To support that, standing up a blog in which we can collect and share our insights seems prudent.

I had three important considerations that I wanted to keep in mind:

  1. It should be well optimized for SEO
  2. It should connect easily to a CMS that a non-technical individual can use to author content.
  3. It should be cheap and easy to customize (i.e., reasonable to self-host using an open-source template and fairly easy to understand the codebase, modify, skin with Tailwind.css to make it look like the main application)

I’ve spun up a few blog over the past few years using different templates. Some have been easy to grok, but using different CSS frameworks (e.g., Bulma), making it more difficult to map from the main app’s styles to the blog’s. Others, like the 11ty blog template, are super optimized for SEO, but honestly wrapping my head around yet-another-templating-language (YATL) like nunjucks made reasoning about the codebase that much more challenging.

Enter Astro

So with those experiences behind me, I started searching around and decided to give the AstroWind template a shot (thank you, onwidget!). Gosh golly, did it pull through and then some!

First, their pagespeed insight scores are phenomenal. 100s across the board on both mobile and desktop. SEO optimized? Check!

I was apprehensive about working with Astro, but I found modifying the codebase to be a joy. Writing an .astro file was something between writing standard markdown and utilizing existing components. It was so straightforward, I could look at existing code examples without referencing the documentation to get my code up and running.

For example, I saved the Edu-rrhaphy logo in an assets directory. Hooking it up to the <Logo> component and replacing the template’s content was as simple as using existing syntax I was familiar with from React:

 ---
+const { default: innerHTML } = await import(`/src/assets/logo.svg?raw`);
 ---

-<span class="self-center ml-2 text-2xl md:text-xl font-bold text-gray-900 whitespace-nowrap dark:text-white">
-  🚀 AstroWind</span
->
+<Fragment set:html={innerHTML} />

The code in between the --- would be my JS logic, including imports. Anything outside of that is html or jsx. When I messed up, the dev server errors were easy to follow and change. Astro is batteries included, no magic and no B.S. Awesome.

Within a couple of hours of starting to work with the template, I had it entirely re-skinned and deployed on netlify (nothing crazy, just followed the standard deployment process for an existing repo on github). *** CHEF’S KISS ***

What about that CMS?

So, last thing — the CMS that my cofounder can use to draft and publish blog posts without writing a line of code. Yep, they thought of that too! :muscle: :muscle: :muscle:

They have a very straightforward package, tutorial, and other resources that they link to on their official page that, even if they’re not created by the Astro team, work as seemlessly as the official Astro library.

Aftab Alam’s tutorial has updated instructions for working with the Netlify side of things (though I couldn’t figure out how to get OAuth login to function, more on that later).

I settled on adding the package and doing my own config (see code snippet below). A few gotchas I’ll mention, though they’re not too hairy.

The tutorial referenced above has everything in a yaml file, but the astro-netlify-cms package abstracts that all away from you in a single config option. So for me, I just had to remember to add all my configuration into the NetlifyCMS integration.

The config below is suited to the vanilla AstroWind file structure. Importantly, I needed to figure out the correct path for the media_folder and public_folder lines so that I could upload and serve images from the NetlifyCMS.

import NetlifyCMS from 'astro-netlify-cms';

export default defineConfig({
  integrations: [
    NetlifyCMS({
      config: {
        backend: {
          name: 'git-gateway',
          branch: 'main',
        },
        media_folder: 'src/assets/images/', // Folder where user uploaded files should go
        public_folder: '~/assets/images/', // Folder where the files should be accessible from the web
        collections: [
          {
            name: 'posts',
            label: 'Blog Posts',
            folder: 'src/content/post',
            create: true,
            delete: true,
            fields: [
              { label: 'Title', name: 'title', widget: 'string' },
              { label: 'Description', name: 'description', widget: 'text' },
              { label: 'Body', name: 'body', widget: 'markdown' },
              { label: 'Tags', name: 'tags', widget: 'list' },
              { label: 'Author', name: 'author', widget: 'string' },
              { label: 'Featured Image', name: 'image', widget: 'image', required: false },
              { label: 'Publish Date', name: 'date', widget: 'datetime' },
            ],
          },
        ],
      },
    }),
  ],
});

Once I had that configured and pushed, all I needed to do was configure netlify for authentication and git backend. The steps were straightforward and, bam! We’re off to the races.

Authors

So for us, we want to restrict who can write blog posts on our site. Therefore, we set it up to be invite only. I couldn’t figure out how/why to get the admin page to show the OAuth options for registration/login, but I saw in the docs that I could also invite content authors via email. I know that Chris doesn’t mind logging in with email credentials, so :shrug:

I found this to be a bit confusing, since I wanted to send content authors email invitations and I couldn’t see in Netlify’s options a way to do that. Thankfully, I found that I could send email invites on the https://app.netlify.com/sites/YOUR-APP-NAME/identity page. Once I accepted my invitation, I was good to go!

Conclusion

Most of this was a bit of a love letter to the Astro team, since they made it so easy for me to get up and running. However, if you do use my exact setup (AstroWind + NetlifyCMS), hopefully you find this blog post in time and save yourself some trial and error hooking everything up!

Share:
Back to Blog