So you’ve dicided to start a blog. I’ve just done that, as you can probably tell by this being the first post on my own blog. In this series of blog posts I’m going to guide you through my process, talk about the decisions I made and my reasoning behind them, starting with the framework I’m using.
Why Hugo?
The first decision you have to make is what framework to use. My first thought was to use Svelte, a single-page application framework, and implement all the features I need myself. I soon realized that’s much more work than I thought - I probably wouldn’t finish the blog in a reasonable amount of time and would soon abandon it due to lack of time for maintenance.
Fortunately, there’s a surprising number of great frameworks that do just what I needed. After looking through some of them, including Gatsby, Jekyll and Eleventy, I’ve decided on Hugo - it’s very simple, doesn’t require any other software to be installed, is blazingly fast both for development and delivering the content and has all the features I might need and more. The only downside I found is that Go templating is a bit clunky, but it does the job nevertheless. I’m yet to regret this decision, so I’m going to show you how to start your own Hugo blog below.
Getting started
First things first - you need to install Hugo. You can find out how to install it for your system, but getting it on Windows with Chocolatey is just one command:
choco install hugo -confirm
This is all it takes to install Hugo on your machine. Starting your blog is just as easy:
hugo new site {{site\_name}} -f yml
I’ve added an option to choose yaml as the type of config files as I find it easier to work with than toml, which is the default. You can also pick JSON if you’re more comfortable with it.
You could start a Hugo server now and see what we’ve created, but you’d be greeted with a Page not found error. That’s because you can’t run a Hugo site without a theme, and it doesn’t come with a default one. We could create a theme from scratch, but for now let’s pick one from the hundreds of themes available on the official Hugo website.
Getting a theme
I’m going to go with PaperMod. As all themes are installed a bit differently, if you decide to go with a different one follow the steps in it’s description.
As we’re going to install the theme by using a Git submodule, let’s set up a git repository and push it to GitHub. That’ll make it easier for us in the future, and version controll is always good to have in case things go sideways. First, create a repository on GitHub. Then you need to open a terminal in your new blog’s directory and execute the following commands:
git init -b main
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/{{your-github-username}}/{{your-repository}}.
git push -u origin main
Before we move on, let’s also take a second to create a .gitignore file with the following content co we don’t accidentally commit unnecessary files:
# Generated files by hugo
/public/
/resources/_gen/
/assets/jsconfig.json
hugo_stats.json
# Executable may be added to repository
hugo.exe
hugo.darwin
hugo.linux
# Temporary lock file while building
/.hugo_build.lock
Okay, now we are ready to install the theme. It’s also done through the command line by adding a submodule with the theme to the correct directory:
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
Now that we’ve got a theme in our themes directory, we have to tell Hugo to use it by adding the following line to the config.yml file:
theme: "PaperMod"
Reaping the fruits of our labor
That’s it! Now you can run this command to start your site:
hugo server -D -p 3000
If everything went according to plan, you should be able to see your blog by navigating to localhost:3000 in your browser. Well, there’s not much to see yet - we haven’t gotten around to creating the content for our blog, but we’re going to take care of that in the next post. See you there! If you’d like to see the code, you can find it here.