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 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. We just need to download latest release from Hugo releases page, extract the archive and place it somewhere in the $PATH. Sequence of commands that will accomplish this:

$ cd /tmp
$ hugo_zip=https://github.com/gohugoio/hugo/releases/download/
$ hugo_zip+=v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz
$ wget $hugo_zip
$ tar -xf hugo_0.31.1_Linux-64bit.tar.gz
$ sudo cp hugo ${PATH%%:*}

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.

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. And while we are at it, we will also create accompanying folder for post resources such as images. If your post is text-only, you can omit the second command:

$ hugo new posts/adding-blog-post.md
$ mkdir content/posts/adding-blog-post

Now we use our favourite editor (also known as vim;) to edit the content/posts/adding-blog-post.md file. When we first open the file, content will look something like this:

---
title: Adding Blog Post
date: 2017-12-27T17:32:04+01:00
markup: mmark
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-27T17:32:04+01:00
markup: mmark
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 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 dialect called mmark, which means that if we can write README.md file for our Github projects, we can also write blog posts. One welcome addition in mmark is support for latex math. 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 or its fully general display cousin

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.

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.

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.

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:

  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.