A Developer's Guide to Blogging

15th August 2023

So you’re a developer looking to start a blog? In this guide I’m going to take you through running your own blog site, from domain names & site creation to SEO & syndication.

Table of Contents

Section 0 (optional) - Start writing on blog platforms

If you want to warm up a bit before going through the effort of setting up your own site, the easiest & simplest thing to do is to just get writing and contribute your work to existing blogging platforms.

Ultimately the hardest thing about blogging is the actual writing - at least, that’s usually the case for us developers! So it doesn’t hurt to get a feel for it first to see if you enjoy it. Also, as we’ll see later, these are still useful to make use of even if/when you set up your own separate blog site.

Dev.to

You’ve probably heard of dev.to already - it’s still the biggest developer blog platform and it’s where I recommend you start. You can easily start writing using their simple markdown editor, and it has a large readership so you’ll get a good number of eyes on your work straight away.

It has great built-in analytics, which can help you see how many people are reading your posts, and even how they found them - e.g. Reddit or Twitter. This helps you see what’s working best when you share your work.

Its design contains a lot of social media style elements, with likes & reactions to posts, as well as message-board style discussion threads. (This could be a pro or a con, depending on your tastes.)

If in any doubt, start here!

Hashnode

Hashnode is a newer dev blog site. In my opinion it has a much more professional feel than dev.to. It feels much more blog-oriented than dev.to, and less like a social media site; it gives you a separate blog subdomain, giving your blog a bit of its own separate identity within the site. If you want to you can even hook it up to your own private domain name if you wanted.

Sadly though it’s a lot less popular than dev.to, and in my experience I hardly get any traffic through it. If you like its cleaner style it could be worth a look, but expect to do more legwork to get your posts noticed.

HackerNoon

HackerNoon is very different to dev.to & Hashnode in that any article you submit there has to go through a human editor who works with you to ensure your article is at its best before it is published. However, they may choose not to publish your article at all.

This has its tradeoffs; on the one hand this is a great learning experience, but on the other it limits your freedom to simply post when and what you want. Therefore I would recommend submitting work to HackerNoon for the learning experience it will give you, but consider keeping the primary home for your blog elsewhere.

Section 1 - Buy a domain

Sadly, creating your own blog involves one of the most dreaded developer tasks - naming things! Though not very difficult from a purely technical point of view, it’s worth looking into and thinking about up-front; think it over while you’re getting your site set up.

What domain name to choose?

There are two main choices here:

  1. Name your blog after yourself
  2. Give your blog its own identity with a separate name

I’ve come across varying opinions on each; for my own blog I’ve simply named it after myself. My thinking is that if you’re using a blog to help get your name out there, why not use your name in your blog? (If this logic is good enough for Will Smith, it’s good enough for me! 😅)

Whatever you choose remember that your domain is a bit of a pain to change, so it’s worth taking the time to find one you’re confident with. However you may have to rethink or adapt your domain if the one you’d like is already taken, so check if it’s available before you get your heart too set on it.

Where to buy a domain name?

You’ll probably have heard of many domain registrars already, such as BlueHost, Hostinger, GoDaddy, and Namecheap.

However, a key one to check out is Google Domains, because this is the only registrar which sells .dev domains. My advice is that .com is still the best if you can get one, so if there’s one available that you like then go for it, but if not then .dev could be a great alternative.

Domain costs

Note that domains cost varying amounts, and moreover you have to pay up every year to keep them. Domains can be as cheap as $10 per year, so unless you’re buying a domain for business purposes, think hard before shelling out for an expensive one.

Section 2 - Create a simple site using a Static Site Generator

What is a Static Site Generator?

A static site generator - or SSG - will template & generate the content for a website such that it can be served up as static files held on a web server. After setting up the main structure of the site - such as your home page, posts index, ‘about’ page, etc. - you can generate complete pages simply by adding markdown files.

Why use an SSG?

In short, SSGs

  • give you fast sites
  • let you publish using a GitOps workflow
  • are secure (no database to hack into!)
  • let you take advantage of your tech skills, rather than being limited to what platforms can provide

As developers we use something pretty much every day which does something very similar: GitHub. In our code repos we’ll write readmes & other documentation in markdown, and GitHub nicely formats it for viewing on a webpage.

An SSG can let you follow much the same GitOps workflow for your own blog. When I got started writing on dev.to I managed my drafts in a Git repo. This was fine up until wanted to publish, at which point I needed to transfer the contents into their web editor. This was fine, but when I found out that SSGs can let you use the same workflow as for updating a readme in GitHub, that was enough for me to want to find out more.

A common way to set up a blog is to use something like WordPress; this has plenty of advantages for sure, but it stores all your content in a database. A statically-generated site doesn’t need one, which for one thing means it will be much faster. Speed isn’t everything of course, but Google cares about how fast your site loads, so why not take advantage of the speed that an SSG-generated site can give you?

Creating a basic site with Hugo

For creating a static site I recommend Hugo. In short this is because it is popular, well-supported, fast, and allows you to get up and running quickly with premade templates.

(For details on alternative SSGs, see the Comparing SSGs section in the appendix.)

The quick start page of Hugo’s official docs gives a great description of getting a basic Hugo site set up. Follow the steps it provides, but when you reach its ‘create a site’ commands, I recommend changing them instead to the following:

hugo new site quickstart
cd quickstart
git init
echo "/public/" >> .gitignore
echo "/resources/_gen/" >> .gitignore
echo ".hugo_build.lock" >> .gitignore
git clone https://github.com/leafee98/hugo-theme-flat themes/flat
rm -rf themes/flat/.git/ themes/flat/.github/
echo "theme = flat" >> hugo.toml
hugo server

This has the following differences to the official guide:

  • Sets up a .gitignore file
  • Uses the excellent ‘Flat’ theme instead of the Ananke theme
  • Sets up the theme as code within your own repo rather than as a git submodule; this makes it a lot easier to tweak the theme to your own taste later

When creating your GitHub repo, make it private - this is for SEO reasons, which we’ll explore later.

Once you’ve followed the guide then you’ll have a site ready to host! At this point there will most likely be aspects to the site that you’ll want to change. However, you don’t need to let that stop you from getting hosted. The main thing that you want to avoid changing later is your URLs; everything else can be changed later on.

Section 3 - Get your blog hosted

As the Hosting and Deployment section of the Hugo docs describes, since you’ve got a static site it can be hosted virtually anywhere, and almost certainly for free too. Of course there are plenty of free/cheap hosts for WordPress-based sites as well, but any particular host will only give you so much bandwidth; in general, a static site gives your more bandwidth for your buck, even if you haven’t actually handed over any money.

Hugo’s hosting guide lists plenty of possibilities, but personally I can agree with Bryce Wray’s recommendation to go with CloudFlare Pages; its free tier is possibly the fastest out there, and it’s easy to use. Simply follow their guide from ‘setting up a GitHub repository’ onwards. At this point your site will be online! But you’ll have an ugly domain like my-blog-xyz.pages.dev. Simply follow CloudFlare’s guide on setting up a custom domain to get your site live on the domain which you bought earlier.

Section 4 - Analytics

Vanity of vanities, all is vanity!

— Ecclesiastes 1:2

Now strictly speaking this is an optional step, but at this point it’s worth setting up analytics for your site. Perhaps I’m just vain, but for me a lot of the fun of blogging is being able to see that people actually see and care about what you’ve written.

One limitation of setting up a static site is that you can’t host analytics yourself since that would require some sort of database. But that’s not too much of a problem anyway since there are plenty of good third-party analytics providers available. The biggest one which you’ll likely have heard of is Google Analytics.

Setting up analytics with a third-party provider generally involves

  1. Setting up an account
  2. Adding a javascript snippet or link to your pages.

In the Hugo template I recommended, you would simply add something like the following to your head.html template file:

{{/* Include analytics,
  but only in production */}}
{{- if hugo.IsProduction |
  or (eq site.Params.env
         "production") }}
<script
  defer
  data-domain="yourdomain.com"
  src="/link/to/script.js">
  </script>
{{- end }}

If you want to set up GA for your site, follow Google’s official docs.

The analytics provider I’ve gone with is Plausible. Sadly it’s not free - about $9 a month - but it’s easy to use, lightweight (the script is less than 1kb), and respects privacy, so it’s worth a look IMO.

Section 5 - Basic SEO

If you build it, they will come

— Field of Dreams

There is some truth to the above quote; there’s not too much you need to do to get your blog on Google, and thankfully the days of keyword-stuffing shenanigans are over; what ultimately matters is writing good content, which is good news for independent bloggers such as us.

That said, there are a few things you can do to make sure that your site is up to scratch for search engines.

Letting Google know you exist

Google’s web crawlers will find your site eventually, but it certainly helps to give Google a head start and get your site set up on Google search console. You’ll want to do the following:

  • Sign up
  • Register your domain address (this will be greatly simplified if your bought your domain from Google Domains)
  • Submit the URL for your site’s sitemap.xml on the sitemap tab. Thankfully, Hugo will have generated one for you at https://yourdomain.com/sitemap.xml.

Once this is done then Google will at some point over the next few days start a crawl of your website. Note that there’s a bit of a lag of a few days to the search console though. The most reliable way of seeing what’s indexed on your site is to google using a site: query, e.g. site:yourdomain.dom.

Another useful benefit to getting set up on the search console is that under the ‘Pages’ tab you can see any reported issues about why Google can’t or won’t index your pages.

Checking for issues

Hugo and the template we’re using should cover most of the bases for good SEO practices. But still, it doesn’t hurt to check your site on Google’s PageSpeed Insights tool. (This will become more important if/when you start making your site more to your own liking by tweaking the template files.) This will give you a good overview of the performance, accessibility and any SEO issues (such as missing meta tags) for the page.

Canonicalization & Canonical URLs

One SEO concept that is key to understanding as a blogger is canonicalization & canonical URLs. Basically the idea is that the same content can be accessed via different URLs, but you don’t want Google to split the page ranking for a single page across multiple URLs. Therefore you can have a page declare what URL search engines should consider as being the URL for the page.

Remember that CloudFlare also generates an “ugly” domain like my-blog-xyz.pages.dev alongside your custom domain. Most (if not all) hosting providers don’t allow you to turn off this basic domain, but so long as you have canonical URLs set up on your pages this won’t be a problem - Google will only list under your custom domain, not the “ugly” one.

One of the reasons that I recommend the Flat theme for Hugo is that (unlike the recommended default of Ananke) it already includes a canonical link. However if you want to use a different theme you can add this simply to your header template like so:

<link rel="canonical"
  href="{{ .Permalink }}" />

You can check that this is set up correctly for any given page by checking it in the PageSpeed Insights tool mentioned above; you’ll see whether a page has a canonical URL as a checklist item under the “SEO” section.

We’ll explore canonicalization further in the section on republishing, further below.

Private GitHub repo

You’ll recall earlier that you made your GitHub repo private. This is because (at time of writing) you can’t add canonical URLs or noindex tags to the markdown documents, and so this serves as another subtle code duplication issue. A private repo works around this issue.

Backlinks & domain authority

You’ve likely heard that one of the factors in Google ranking a site is how many other sites link to it; this is known as domain authority, and such links from one site to another in this context are known as backlinks.

I’m not going to talk about how to “farm” backlinks to make your blog rank higher on Google; for one thing Google has got wise to such schemes, and besides one of the benefits of creating your own site is that you can help make the web a better place rather than further filling it with such douchebaggery.

The main takeaway instead is simply that it’ll take time before you can rank well on Google; you won’t have much domain authority to start with, but that will grow over time. As ever, your focus should simply be on writing the best posts you can.

Section 6 - Sharing your work

Advertising is only evil when it advertises evil things.

— David Ogilvy

As much as I would love to say that Google being able to find your blog is enough, realistically it really helps to do a bit of self-publicity and share your posts online.

Use Reddit

The best way to do this is by post links to your articles on Reddit. Posting on social media doesn’t hurt, but the key advantage with Reddit is that its voting system means that good posts (as I’m sure yours will be) can stay on a subreddit’s front pages for a while, rather than immediately getting swept along down the timeline.

Post on specific subreddit(s)

Post to a specific subreddit such as the programming language or technology which you’re writing about. The bigger the subreddit the more people will potentially see your post, but the catch is that big subreddits like /r/programming can often have a lot of people tactically downvoting good posts simply to bury them, in order to help keep their own posts on top.

Instead, you’ll have more luck by sticking to the most specific Reddits that apply to your post; such communities are more likely to care and read your post, and they’re more receptive to self-publicity.

Check the rules for each subreddit

If you’re unfamiliar with a subreddit always check its community rules before posting. Each subreddit will have different rules, in particular different tolerances to linking to your own articles. This can vary between total bans on self-publicity, an expectation that you don’t self-post too much, or no restrictions at all.

Another key rule to watch out for is undesired post topics with possibly a redirection towards a more appropriate subreddit instead. For example /r/programming’s rules ask you to redirect technical questions towards r/learnprogramming instead, and similarly job listings towards /r/forhire.

Be part of the community

Regardless of the rules for the subreddit you’re submitting to, it’s always a good idea to be a part of the community rather than only using Reddit as a tool for your own ends. Post links from other blogs you enjoy, engage in discussions and just have fun.

Read through the “Reddiquette” once in a while to check that you’re taking part in a responsible way.

Section 7 - Republishing on blog platforms

As rewarding as it is to have your own separate blog it’s still useful to republish posts on dev blogging platforms such as dev.to. You might wonder why we’d come back around full circle after taking the time to set up your own blog.

Ultimately all that matters is getting your thoughts read and appreciated by other developers, and republishing helps you do that simply by adding another way for people to come across your work. Another key benefit though is that it helps you build up domain authority for your own blog through backlinks - but in order for your site to be credited with those backlinks, you need to republish in the right way.

Canonicalization for republished articles

Remember the concept of canonical URLs that we discussed earlier? When reposting your articles elsewhere, ideally you only want to post on sites that let you indicate that the canonical version of your article is the one on your blog. That way you get the exposure benefits of republishing but any resulting backlinks build up the domain authority of your own blog.

Canonicals for dev.to

As detailed in dev.to’s editor guide, you can add a canonical URL simply by adding a canonical_url property to a post’s “front matter” properties.

Canonicals on Hashnode

You can set a canonical URL on a Hashnode article under the “Are you republishing?” section on the “Article settings” view for an article. (See their docs for further details.)

Canonicalization on HackerNoon

As covered in HackerNoon’s docs, you can set a canonical URL in the “First Seen At” in your post’s settings.

You can’t canonicalize on FreeCodeCamp!

As noted by this Hashnode article, think twice before republishing your work on FreeCodeCamp since they don’t let you set a canonical URL. Indeed, this dev.to post details the negative impact this has made on certain bloggers because of this.

Publicity done for you

Another benefit of republishing is that some of the legwork for sharing your work on Reddit & other social media will often be done for you. Bots and bloggers who curate articles for particular communities will often find your work through particular tags on blog platforms, and share it on social media.

Republishing drawbacks

Republishing isn’t without some costs, however:

  • It can be a bit of work to repost on these sites, especially in contrast to the nice GitOps flow when publishing to your own site. (Some automated & semi-automated solutions are available to help things here though.)
  • It’s possible for republished work to outrank your originals on search engines. Ideally canonical URLs will mean that the republished work is unindexed altogether, but this isn’t guaranteed (especially for Bing, in my experience)

Therefore it’s worth considering republishing some time after you publish the original (say, one or two weeks, but it’s up to you). This has the following benefits:

  • Reduced duplication of work making corrections & additions across your original & republications; inevitably, despite your proofreading efforts, you or your readers will spot issues or things you missed - better to have to do this while the article only exists on your own blog
  • Search engines have time to index your site first

Appendix

Why blog?

Improves your writing & communication skills

While thankfully Agile means that software development rarely involves producing reams & reams of documents like it may have done in previous eras, I think that the pendulum has swung a bit too far the other way and so good documentation which helps to introduce newcomers to a system or repo is sadly neglected. And as you progress in your career as a developer you’ll have more and more need to distil your thinking and explain complicated concepts & systems in a clear & concise way.

Blogging gives you a great way to practice these skills. In particular, having an audience is a great motivating factor!

Gives you a way to prove you know what you’re talking about

It’s one thing to have a list of technologies you know listed on your resume; it’s quite another to prove that you really understand them by being able to link to articles you’ve written that clearly demonstrate that you know your craft inside & out.

Helps you market yourself & creates opportunities

Jeff Atwood met Joel Spolsky in part through his blog, Coding Horror, and they then went on to create a little thing called Stack Overflow.

You can’t guarantee such things will happen simply through creating a blog, but it certainly doesn’t hurt either. And especially in niche technology areas, you might find your name might stick out to someone through them having read an article of yours in the past.

A quick comparison of SSGs

Here are my thoughts on a few popular SSGs, and how I came to settle on Hugo. See jamstack.org for a much bigger list.

Jekyll

Jekyll used to be very popular but it is less so now. It powers GitHub pages and is very blog-oriented. I initially considered it, but was put off by its strict URL structure which insists that blog pages have a date component embedded within the URL, which is something I wanted to avoid for my own blog.

This can be avoided by making writing posts as part of a more abstract “collection” type, but then that would lose many of the benefits of working within its own blog posts abstraction.

Eleventy

Eleventy is an SSG that has been gaining a lot of popularity. It is powered by node.js, and is very flexible; you can customise the templating engine and markdown renderer, even allowing you to use different options for different pages within the same site.

The main drawback I found with this is that it doesn’t come with any built-in templates, so you can’t easily just generate a blog straight out of the box. Also of note is that runs on node, making its installation more complicated; not a deal-breaker by any means, but not as convenient has Hugo.

Gatsby

Gatsby is also becoming very popular lately. However, it generates react-based single-page apps rather than static sites. This is a valid option, I wanted the simplicity of pure HTML & CSS when creating my blog. Moreover, I’ve seen that this writer has had a poor experience using it, recommending Hugo instead.

Hugo

Lastly, we get to Hugo, the SSG I use for my own blog. It is written in Go meaning that using it means installing a single binary. This has advantages from a hosting point of view; you can just specify the Hugo version on my provider, and you can be sure that it will behave just the same way as it would locally.

It is blazing fast. While this makes little difference when your blog contains just a few posts, it’s good to know that the build time will remain reliably fast as your site grows.

It is the most popular SSG (judging by GitHub stars), meaning that it is well-used & documented, and well-supported by pretty much any static site hosting platform.

Above all it has templates to get you started. Though you will likely want to create your own templates at some point (or at least modify them to your own taste) - it at least gives you something to get started out of the box.

Its main downside is that it uses Go’s templating language; it’s not terrible by any means, but it’s a little clunky compared to some, and if you’re keen on another template language then you’d be out of luck here. If this is a problem for you then Eleventy might be worth a look.