Blogging is a common thing right now, you can start blogging using free services with zero configuration like Blogger or Wordpress. On the other hands, did you know that you can build your own blogging platform too — from the ground at no cost.
Introducing Hugo - one of the most popular open-source static site generators written in Go a.k.a Golang. It offers simplicity in building a website while maintaining good performance and flexibility. Unlike other blogging platforms, there is no database, no plugins requiring any permissions, and no underlying platform running on your server, there’s no added security concern.
How about styles? No worry with both the official ones that the Hugo team maintains as well as the community-contributed ones — has a wide range of selection that you can pick based on your need.
Some of the most popular choices include:
- Ananke - The intent of this theme is to provide a solid starting place for Hugo sites with basic features and include best practices for performance, accessibility, and rapid development.
- Kube - A professional and a responsive Hugo theme for developers and designers that offer a documentation section mixed with a landing page and a blog.
- Creative portfolio - A clean and elegant template mainly made for designers and creatives but can be easily transformed into a generic website.
In this tutorial, you will move through step-by-step to build your own blogging platform using Hugo. Starting with installing Hugo, adding themes, adding contents and deploy it with Github pages so everyone can access and read your awesome stories.
Before following this tutorial make sure you have:
- Git - You should have Git installed on your local machine. You can check if Git is installed on your computer and go through the installation process for your operating system by running
git --versioncommand. You’ll see git version running on your machine otherwise you have to install git by following this docs.
- Github account - This is mandatory in order to host your site later on. Make yourself a Github account signing up on the front page.
- Text Editor - You need a text editor such as VSCode, Atom, or Sublime to edit Hugo’s configuration file and add some content to your site. If you are using Mac or Linux and looking for some heat you can use
vimtext editor that comes out of the box.
Step 1 — Install Hugo
Using Homebrew, you can install Hugo with the following one-liner. It may take a while.
$ brew install Hugo
Linux (Debian/Ubuntu variant)
The easiest way to install Hugo on Debian/Ubuntu is by using the provided package via apt-get:
$ sudo apt-get install hugo
Using this method is easy but there is a catch, you might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo.
You can verify your installation with this command:
$ hugo version
Step 2 — Create a New Blog
Create a new site that will become your blog. The command below will create a new Hugo site in a folder named
$ hugo new site personal-blog
Step 3 — Theme Your Blog
Next thing is to add some themes to your blog. With Hugo, you can either theme your blog yourself or use one of the beautiful, ready-made themes. I choose
hello-friend because it is deliciously simple. To install it :
Make sure you are inside your blog directory:
$ cd delicious-blog
hello-friend theme into the
themes/hello-friend directory and copy
config.toml file from
hello-friend to your site.
$ git init $ git submodule add https://github.com/panr/hugo-theme-hello-friend.git themes/hello-friend $ cp themes/hello-friend/exampleSite/config.toml ./
Adjust your site configuration by opening
config.toml file using your favorite text editor. Fortunately
hello-friend gives a clear explanation line-by-line about this configuration.
If you want to add more themes, just repeat the above steps. For most themes, it will work flawlessly.
Step 4 — Add Some Awesome Contents
There are a couple ways you can create content for Hugo. The easiest way is to use Hugo’s cli:
$ hugo new post/how-to-build-a-spaceship.md
That command will create an
how-to-build-a-spaceship.md file inside
post folder (Hugo will create it automatically if it doesn’t exist) inside the content folder. Edit the newly created content file if you want.
--- title: "How to Build a Spaceship" date: 2018-04-09T08:51:07+07:00 draft: true --- ## Introduction A spacecraft is a vehicle or machine designed to fly in outer space. Spacecraft are used for a variety of purposes, including communications, Earth observation, ...
In case you’re curious, the generated file has a certain header, to begin with — it called Front Matter. You can read more details about this Front Matter in Hugo’s official documentation.
Step 5 — Run Your Site Locally
Now, start the Hugo server with drafts enabled to see what’s your site looks like :
$ hugo server -D
Navigate your browser to http://127.0.0.1:1313 and see the magic 🎉. Apply different themes, tweak the configuration file and add more content until you are satisfied with your result.
Step 6 — Deploy to Github
It’s not complete if your site just running on your machine, people still cannot access it yet. From their documentation, you can host your new Hugo website virtually anywhere. One of them is Github Pages, It’s free, easy to set up and supports HTTPS!
YOUR_PROJECT e.g (personal-blog) repository with your Github account. This repository will hold all of Hugo’s content, configuration, and other files.
USERNAME.github.io repository (Yes! You need two repositories). Make sure your
USERNAME is your real username, otherwise your site will not showing up properly. This repository will hold a fully rendered version of your site.
Make sure your baseurl key-value in your
config.tomlreflects the full URL of your GitHub pages repository.
Inside your site directory, create a new git project and add a new remote URL.
$ git remote add origin https://github.com/USERNAME/YOUR_PROJECT.git
Remove public folder and add git submodule. So when you run hugo command to build your site it will live on public folder but have a different remote origin.
$ rm -rfd public/ $ git submodule add https://github.com/USERNAME/USERNAME.github.io.git
Build your site and push everything to Github.
$ hugo -t hello-friend $ git add . $ git commit -t 'Initital commit' && git push origin master
Change directory to public, make a commit and push everything in it. Note, this will publish into
$ cd public $ git add . $ git commit -t 'Initital commit' && git push origin master $ cd ..
Your personal page should be up and running at
https://USERNAME.github.io within a couple minutes.
In this tutorial we downloaded, configured, and host a complete Hugo site. If you follow all the steps above you should see something like http://husnulhamidiah.github.io (this site). You can take a look it’s source code at my Github.
If you’d like to learn more about how to configure, customize your Hugo site even further and see what else Hugo can do, visit the official Hugo documentation. You’ll find a lot of resources starting from adding a static page, comment, create your own theme and many more.
And, if you have an issue or idea to make Hugo better, feel free to contribute to their Github repository.