Context

It could be interesting to start by explaining how this blog is built.

There are many ways of creating a blog these days…​ From classic Wordpress to static website generators, you really have many choices.

I love to write with Asciidoctor, and I’m using it a lot to write my personal notes (about various topics, including programming).

So I wanted something simple ( ⇒ I can see results in less than 15 minutes[1]) that supports Asciidoc/Asciidoctor. It didn’t took long to stumble upon this page that lists a few static site generators supporting Asciidoc.

I chose Hugo, because I liked the name.[2]

Although my blog is not yet fully customized, it was really easy to create a new project and start writing. While I was thinking about all the very interesting topics I’m going to write about, I thought that describing the full process could be interesting.

Creating your Hugo project

Basically, I followed the instructions at https://gohugo.io/getting-started/quick-start/ to create my project. I don’t know your OS so check yourself how to install Hugo.

Then follow these few steps to bootstrap your project.

# Create the project
hugo new site awesome-blog

cd awesome-blog

# Init git
git init
git add . && git commit -m "Init project"

# Add theme
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> config.toml

# Add your first blog post
hugo new posts/hello.adoc  # or hello.md if you don't use asciidoc

# Start the server and go to http://localhost:1313
hugo server -D

Alright, you have a new blog. You can start writing! The next step is to share your amazing blog to the web.

Hosting your blog

If you check the hosting section on the Hugo website, you will see there are several ways of hosting your Hugo static site.

I was kinda lazy to be honest, so I choose Gitlab pages for hosting, just because I already had a Gitlab tab open.

The process is very straightforward and the instructions at https://gohugo.io/hosting-and-deployment/hosting-on-gitlab/ are very clear.

You obviously have to create a Gitlab account and a new project.

I will not go into details of the .gitlab-ci.yml file right now, because I plan to write a few posts about Gitlab CI later. You can however check my .gitlab-ci.yml in the next section.

After a few minutes, your blog will be available at https://<YourUsername>.gitlab.io/<your-hugo-site>/

It took between 15 and 20 minutes for my blog to go live the first time, so be patient if you try it yourself.

Problems with hugo and asciidoc

Well, actually, I had some problems with asciidoc and Hugo on Gitlab CI. My first commit did not have any content, so the first build passed successfully. After I wrote some content (this post), I noticed a problem.

After some research, I found this issue. It was interesting because it works locally because I have asciidoctor, but not on CI. So I just added the installation of asciidoctor on the CI and it fixes my problems :-)

gitlab-ci.yml
image: monachus/hugo

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
    - apt-get update
    - apt-get install -y asciidoctor
    - hugo
  artifacts:
    paths:
      - public
  only:
    - master

Creating a domain and using it

Now, you will agree that it would be better to have a nice DNS for your blog, like orkhon.dev, instead of a gitlab subdomain.

There are many options for registering a domain name. I already bought the domain orkhon.dev on Google Domains a few days before. So, how to configure Google Domains and Gitlab to connect them?

Everything starts here, where Gitlab gives all information about adding your custom domain to gitlab pages.

I will not enter into the www[3] or not[4] debate, but I choose to host my blog at www.orkhon.dev, and redirect orkhon.dev to the www subdomain.

  • Google Domains

    • Add a DNS CNAME record set from www.orkhon to aykut_acikel.gitlab.io.

    • Configure a redirection from orkhon.dev to www.orkhon.dev (301)

  • Gitlab

    • Go to https://gitlab.com/<username>/<project>/pages and click on "New domain"

    • Add the domain name you want to serve your blog (so in my case : www.orkhon.dev)

    • You can provide your own TLS certificate, but it’s easier to enable automatic certificate management with Let’s Encrypt

  • Google Domains

    • Then, you will need to add a DNS record in Google Domains to verify domain ownership

  • Gitlab

    • Save

    • Be patient while Gitlab is obtaining your certicate from Let’s Encrypt…​

If after several hours, you still don’t have your certificate, try removing the domain from Gitlab pages, and follow these steps :

  • Add the domain without certificate

  • Add the validation record to your domain

  • Wait until Gitlab verifies it

  • Edit the domain, and add certificate management now

  • Wait…​

I had this problem once, and I "solved" it by following these steps.

Conclusion

In the end, it was quite easy to build my blog with Hugo and Gitlab pages. I had some problems with DNS, but overall it was not that hard. Next workshop would be to look at something like Netlify or Cloudfare.


1. Well, to be honest, it took me more than 15 minutes to build this blog…​ Mainly because of problems with DNS
2. Later I saw that Antora could be an interesting choice too. Maybe I will test it later for some documentation.