Adding Blog Post

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.

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.

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.

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

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:

1. Create new branch.
2. Create new file.
3. Write content.
4. (optional) Create folder and upload post assets.
5. 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.