Skip to main content

Blog Updated

· 6 min read
Peter Dyer

It has been a while since there were new posts here at FullsApps. The plan is to change that. I have been off working on a variety of projects and want to share some of the things I have learned. Let's start with this blog itself; which if you have been here before you will have noticed has been updated to something a little less embarrassing.

Background

When I originally created FullsApps (I think something like 5 years ago) I did a little bit of research into where I could create a blog. I looked at a bunch of different options. For some reason I just couldn't find a solution that looked like what I was after. I landed on Google Blogger (formerly Blog Spot I think) for no other reason than I had used it before. It provides a decent user experience for the blog creator. You have some customization options and you have some control over what the site looks like. It also integrates pretty well with Google Analytics to understand how the blog is being used. It also integrates with Google Ads but that creates a pretty terrible user experience (which past users can confirm).

Two things became an issue with using Blogger.

  1. I ended up having to write posts in html to create something that looked close to reasonable (and most would say it still looked awful). In particular the ability to create code snippets and diagrams was really bad. The ability to add images was also painful.
  2. The Lighthouse score with Blogger, and the performance in general, was terrible.

Not really an issue, but it did bother me that as a developers I didn't have a hand in the actual technology used to create the blog.

Solution

In my work as a consultant, depending on the stage I join a project, I often need a solution for documentation. Someplace to for diagrams, API docs and general solution discussion. I often use solutions like Confluence or Sharepoint if the team I'm working with uses them currently. However, sometimes the team I am working with doesn't have a solution in place. One group I worked with was fond of using Sphinx (a Python based documentation solution) in those situations but where my primary programing language is Typescript (sometimes Javascript) and my primary front-end framework is React I thought something a bit more aligned with my tech stack might make sense.

After some research I became aware of Docusaurus. It is a popular solution from the Facebook Open Source team and is used for the React docs. If you have read anything else in this blog you likely know how I feel about the open source projects from Facebook - I am a fan. I almost exclusively use React for front-ends (I have done a tiny bit of work in Vue and raw Javascript but don't prefer either). Also, I have done quite a bit of work with GraphQL.

With that I started using Docusaurus as my go to solution for project documents. The ability to write in markdown and the ability to integrate with Mermaid for diagrams and plugins for both GraphQL and OpenAPI where key features. Also, the ability to logically layout and navigate the docs I created was perfect. The one feature I didn't really use was the ability to create a blog.

At some point, I had some free time and explored the ability to create a blog in Docusaurus and I was sold.

Requirements

When I think about the things I care about in a blog today, these are the things that come to mind:

  • Ease of creating content
  • Ability to track activity (so I can understand what content is useful)
  • A good Lighthouse score (for SEO - so the content can be found)
  • Ability to customize, perhaps grow into a proper website

This led to what you see today.

Docusaurus

The user/developer experience with Docusaurus is excellent. It is a reasonable mix of out-of-the-box functionality and developer control. There is a tiny bit of config to create a blog specific Docusaurus project. The Docusaurus docs are excellent and cover everything you need to know.

Blog posts are written in Markdown in the projects repo (following some guidance from the Docusaurus docs on specific Markdown formatting). Markdown files are created with a specific name and placed in a specific directory. They can be approved like a typical Pull Request (for easy review and editing). I author posts in VS Code with help from extensions: Code Spell Checker and markdownlint.

With Docusaurus the Lighthouse score is excellent. The Desktop score is very close to perfect. There a handful of issue with links that could be resolved to bump it higher. The Mobile score has some performance issues - I believe due to sub-optimal images (something I may try to address in the future).

I am using the Google GTag Plugin provided by Docusaurus. This provides me some usage data in Google Analytics. It is dead simple to setup and seems to work as expected.

Netlify

When working on consulting projects all of my Docusaurus deployments were to AWS (following static site hosting practices using S3 and CloudFront). I could have used AWS to host this blog but I wanted to try out another solution, particularly so I can grow into possibly using something other than Docusaurus in the future, so I chose to use Netlify.

My experience with Netlify has been extremely positive so far. If you haven't used it I would encourage anyone to take a look. You point Netlify to your Git repo (in my case GitHub) and it will automatically deploy a preview of your site (for both web and mobile) when you create a Pull Request on an identified branch. When the Pull Request is approved Netlify automatically deploys to Production.

The only other things I did were to update my domain to use the Netlify DNS and to create an environment variable for my Google Analytics Tag.

The usage tier I'm currently using is 100% free, no credit card required.

Future

I really like Docusaurus and it provides a lot of great features for zero effort. However, the one thing I'm still missing is maximum flexibility. At some point I may move to a Remix, possibly NextJS, solution - I have been trialing both. This would allow FullsApps to grow into a complete website where I have total control.