I’ve used Tumblr for many years to host this blog. Tumblr can be used for that purpose, but it also provides some other social features like follow, like, reblog, links and video sharing, etc. Moving my blog to a static site generator was in my backlog for a long time, and the main reason is to not have my content dependent of any 3rd party service like Tumblr, Medium, Wordpress, etc. Nobody knows what these services will do in the future with our content. Look for example at Medium, it’s very annoying every time I need to read an article on Medium to be asked to upgrade to a paid plan to continue reading, and forces me to navigate incognito to workaround that. Anyway…
There are many static site generators, and some of them that are very popular (Jekyll, Hugo, etc.). So, the question is, “which one should you use?”. Well, there is no right or wrong answer. I’ve chosen Gatsby, and here are the reasons:
- it uses React as templates
- it uses GraphQL to query data sources to generate the site
- it has gained a lot of attention recently
- it’s easy to learn if you know node and React
- it has a lot of plugins to integrate with
- it has a lot of starters that you can use as a starting point for your blog, portfolio, company, or e-commerce site.
Here is the requirements list for my blog migration:
- The content of old posts should be migrated to Markdown files (to be hosted locally in my git repo)
- The design should be very simple and clean, allowing me to have an “About” page
- It must be able to integrate with Disqus, to allow readers to comment my posts.
- Old URLs must be kept (no broken links), including the RSS URL to keep the subscription of my blog in feed readers.
- All the typical requirements of a blog about software development: tags, categories, code snippets displayed friendly, google analytics, etc.
The first step was to get the content of my blog posts as markdown files,
including images used in posts. Tumblr provides a REST
API that I can use to grab my content. I
used a python script,
from someone that had the same need. It worked great, generating a markdown file
for each post, and downloading all the images embedded in posts. Each markdown
generated contains a YAML front matter with metadata that will be processed by
Gatsby. I just needed to do some small changes in the python script to include
more metadata, in particular the
slug field to be set as the same URL used in
Tumblr. (more on that later)
Here is an example with my first post, written in 2012.
--- layout: post template: post date: 2012-01-28 title: "Welcome to my blog" slug: /post/16629534467/welcome description: "Welcome to my blog" --- <div> <p>One of my resolutions for 2012 was back to blog . I decided to kill <a href="http://www.agilior.pt/blogs/bruno.camara/" target="_blank">my old blog</a> (in fact, it was already dead), which is hosted in the <a href="http://www.agilior.pt/blogs/" target="_blank">Agilior's corporate blog</a>, the company where I work and I was a co-founder (right now, I already haven't any part of the company's capital) and create a new blog with a personal touch,associated with the bfcamara.com domain.</p> <p>The most of the content that I will publish is certainly related to my work, software development.</p> <p>As one of the founders of Agilior, I hope also to share some of the stories that were part of my life as founder, and some of the mistakes I made along this route. There will be space also to personal subjects, however with lower frequency.</p> <p>In <a href="http://www.agilior.pt/blogs/bruno.camara/archive/2007/12/02/3300.aspx">one of my posts</a> at the old blog, I explain that my life has been done of cycles. My perception is that a new cycle is about to come. I do not expect an easy time, and certainly I will have to leave the comfort zone. But "freedom" is one of the things that I value most, and to be honest, I like to be the leader and the captain of the ship", deciding where to go and when.</p> <p><span>I hope I can maintain some activity in this blog.</span></p> </div>
As you can see, the content hosted in Tumblr is not very clean, probably because I was using a rich text editor in Tumblr to write my posts, but in the end, what is important is that posts are being displayed correctly in the new blog.
The next step was to choose the design for my new blog. I wanted a simple and clean design. I started to look to the Gatsby starters library, and I’ve tried some of them.
I ended by choosing the gatsby-v2-start-lumen starter starter. The design is simple, clean, and it’s already prepared to integrate with Disqus. However, in terms of code, I did some changes and I removed some features that I didn’t want to use:
- Removed docker files
- Changed the Prismjs theme to Okaidia. Prismjs is a syntax highlihter that this Gatsby starter uses to make code snippets embedded in my posts to look great.
Finally, I just needed to set some settings: Avatar, Google Analytics key, Twitter handler, etc, and I had my blog up and running.
Next I needed to choose which platform to use to serve my blog. I had simple
requirements: free, support custom domains, and support automatic deployments.
By automatic deployments I mean having a new deployment triggered whenever I do
git push in my master branch.
There are many others. I started with Netlify due its popularity, and I must say that the experience was awesome. So, I decided to go with Netlify. But from what I’ve seen from documentation of other platforms, I would risk to say that I wouldn’t have any issue if I had chosen one of them.
In the end, I’ve created my site in Netlify, configured with my custom domain (bfcamara.com), and configured with automatic deployments from my git repo hosted in GitHub.
One of my main requirements was to keep the old URLs. Basically I didn’t want to loose all the links out there pointing to my old blog, including the RSS link that people were using to subscribe to my blog.
Part of the problem was solved during content migration. Each markdown created
during migration was generated with a front matter key, the
slug key, with its value
set to the URL used in Tumblr. Gatsby uses this key to determine the URL of a
post. For example, for my welcome post I have
The issue is that Tumblr has configured automatically some redirect rules:
/post/16629534467 is configured to be redirected to
And Tumblr does this for all posts, so the post ID is enough for a post to be visited.
I needed to the same in my new blog by using redirects.
Netlify supports redirects, and I just
needed to add a new file
_redirects to my repo with some rules. For
the welcome example above, it’s just as simple as
You can check here the file with all the rules.
Finally, I also wanted to keep the RSS subscription URL. In the old
blog I was using
/rss and the new blog is using
/rss.xml. I just needed to
add a final redirection rule
With this rule, RSS readers doesn’t need to change my blog subscription URL.
In conclusion, I am happy with the final result, mainly because now I have full control and I own the content of my blog. I also took advantage of this process to learn Gatsby. I hope it helps anyone that needs to migrate a blog to a static site generator. You can check the git repo in GitHub.