We’ve decided that instead of starting with boring “hello world”, we can give a glimpse on how our website is set up!
antfarm.it is built using static site generator
hugo, and runs on Gitlab infrastructure. Thanks to that,
every commit and push to git repository automatically regenerates our website,
and deploys a new version.
Hugo generates static pages from Markdown files, so we don’t have to write or style html by hand. It has a variety of available themes, ready to be installed for almost any kind of project.
Work flow is very simple. Once Hugo is installed on a system, it’s a matter of
creating an empty Markdown file in
/content/posts, with following contents:
--- title: "Example Post" date: 2020-06-29T09:00:00+01:00 draft: true ---
Notice we mark this post as a “draft”. This means it will not show up on our production website until it is ready. Draft posts are only visible when run locally on our machine.
There are lot more post parameters we can use. Check them out in Hugo documentation.
Now we are ready to write our blog post!
To see a preview of our work, we run local server with
hugo server -D, and
point our browser to
-D option allows us to see “draft”
After we make sure our website looks perfect, it’s time to build it on Gitlab!
Gitlab pipelines turn Markdown files into html assets. What we need is
.gitlab-ci.yml file, with instructions on what our pipeline should do.
Here is a config file from our repository:
image: registry.gitlab.com/pages/hugo:latest variables: GIT_SUBMODULE_STRATEGY: recursive test: script: - hugo except: - master pages: script: - hugo artifacts: paths: - public only: - master
To better understand it, lets go line by line.
We start our config with defining docker image that Gitlab will use to build our blog. Since we use Hugo, the image needs to have hugo binary installed. For simplicity we went with hugo:latest, which as the name suggest, will build our website with the latest available version of hugo.
After that we have a variable:
variables: GIT_SUBMODULE_STRATEGY: recursive
Since our base theme (hyde-hyde) is included as a git submodule, we want the pipeline to pull that along with our repository. Without this, our website will not build.
test: script: - hugo except: - master pages: script: - hugo artifacts: paths: - public only: - master
Last two sections define pipeline tasks, which Gitlab will execute upon commit.
Note “except” and “only” keywords. Task
pages will execute every time we push
code to master branch, while
test will run only for branches that are not
master. Both of them execute
hugo script, which will generate static assets.
The only difference between
pages is the latter exports
path (our built assets), so Gitlab can deploy them.
Finally we can host our website for everyone to see!
Gitlab Pages will setup
*.gitlab.io address for us. However, you can add
your own custom domain. All it takes is a new DNS record. Forcing HTTPS
is a single check box, and Gitlab takes care of generating required
This website is open source
To understand setup and file structure, look at our repository. Available here.
If you are looking for help in setting up your own website, don’t be a stranger, reach out to us!