December 27, 2017
Adding Blog Post
WORDS BY Tadej Borovšak
POSTED IN documentation | tutorial
In this post, we will go through the process of writing this post. Confused yet? Good ;) We will start by performing some one-time setup tasks, continue with authoring the actual content, and end with a grand finale: reviewing our work and creating a merge request.
Preparing environment
Before we can start writing this post, we need to setup the environment for
writing posts. We will need git
, our favourite editor, web browser, and
hugo
. First three should be already installed on our
workstation/laptop/abacus, so we will only cover hugo
installation here.
Since hugo
is distributed as a standalone executable, installation is really
simple. In order to avoid using incompatible hugo versions, blog repository
contains a wrapper script that takes care of downloading and running the
appropriate version of hugo. All we need to do is remember to tun ./hugo
instead of hugo
.
Now that we took care of the software side or prerequisites, we must sort out the blog repository access. In order to gain access to the repository, we navigate to the blog repository, click Request Access button and wait for one of the admins to check his email.

Access request button.
When we get access to the repository, we clone it somewhere by running
$ mkdir -p ~/tech-blog
$ cd ~/tech-blog
$ git clone ssh://git@gitlab.xlab.si:13022/tech-blog/blog.git
and pat ourselves on the back for the job well done, since that concludes our initial, one-time setup. Next time we get the urge to write something, we will be able to get straight to it.
Authoring the content
Before we start authoring the content, we should pull the latest master from remote and create new branch that will hold our work:
$ cd ~/tech-blog/blog
$ git checkout master
$ git pull
$ git checkout -b adding-blog-post
Next, we use ./hugo
to generate template for our new post:
$ ./hugo -e tech.xlab.si -c content-tech new blog/adding-blog-post/index.md
Now we use our favourite editor (also known as vim
;) to edit the
content-tech/blog/adding-blog-post.md
file. When we first open the file,
content will look something like this:
---
title: Index
date: 2017-12-27T17:32:04+01:00
authors:
- author1
- author2
tags:
- tag1
- tag2
- tag3
---
Short introduction that is also displayed in post summary.
<!--more-->
## Section title
More content here.
After we replace the placeholders and add some content, the same file looks like this:
---
title: Adding Blog Post
date: 2017-12-27
authors:
- Tadej Borovšak
tags:
- documentation
- tutorial
---
In this post, we will go through the process of writing this post. Confused
yet? Good;) We will start by performing some one-time setup tasks, continue
with authoring the actual content and end with a grand finale: reviewing our
work and creating merge request.
<!--more-->
## Preparing environment
Before we can start writing this post, we need to setup the environment for
writing posts. We will need `git`, our favourite editor, web browser and
`hugo`. First three should be already installed on our
workstation/laptop/abacus, so we will only cover `hugo` installation here.
...
To preview our work in browser, we can run
$ ./hugo -e tech-xlab.si serve
from the repository root, navigate to the http://localhost:1313/, and find our
post, which should be featured on the home page. Note that editing and saving
the markdown file will automatically update the browser page, so you can give
your F5
button some well deserved rest.
We should write post content in markdown, which means that if we can write
README.md
file for our Github projects, we can also write blog posts. If we
enclose our math stuff in $$
, we can avoid escaping the underscore (_
)
characters that have a special meaning in markdown documents. And of course,
math-y stuff also gets rendered properly, like this inline polynomial
$$p(x) = a_0 + a_1 x$$ or its fully general display cousin
$$ p(x) = \sum_{i=0}^n a_i x^i. $$
Hugo also adds some extensions to markdown in the form of shortcodes. One
that is commonly used is {{< figure >}}
shortcode that should be used in
place of regular markdown images, since this shortcode makes it possible to
add captions without writing whole bunch of HTML into our markdown.
When we are done with our content, we can proceed with the last part of the post creation.
Reviewing our work and creating merge request
Now we need to get our new content published. First thing we need to do is push the branch we were working on to remote by running
$ git push -u origin adding-blog-post
This will trigger the continuous integration machinery that has been setup for technology blog and build a preview site for us. To get hold of that preview link, we can navigate to tech blog environments, search for the review/branch-name environment and click the open button.

Location of the open button.
Reviewing our contribution is not mandatory, since this will be done by the person who resolves the merge request, but is a good idea anyhow, since this can catch some common mistakes (like forgetting to commit images that we use).
When we are happy with the result, we create merge request as usual and wait for one of the admins to resolve it.

Creating merge request.
Note that review site link is also included in the merge request, which makes it easy to check the site when resolving request.

Merge request and link to review site.
And this is how we add new post to the blog.
Extra: adding post online
It is also possible to create new post using Gitlab’s web interface. We will not go into details of this process, but the general steps that we need to take are:
- Create new branch.
- Create new file.
- Write content.
- (optional) Create folder and upload post assets.
- Review changes and create merge request as before.
Creating new post this way is a bit messier, since we need to create new
commit for every change that we make to the post (and we do not get the
template to begin with), but we can do it from the phone or tablet. And we can
still use some git rebase -i ...
magic later to clean everything up.