What This Guide will (not) Cover

This tutorial will teach you a quick way to get a basic blog post set up and published on hifis.net. If you plan to write something bigger that might take several days to write up and refine, Christian’s Guide is the better choice for you.

The guide will not go into the details of fancy formatting and styling, however you might want to check the Template Blog Post for examples of common blogging tasks. Additionally, the Kramdown Quick Reference may prove helpful.

Okay, enough chit-chat, let’s write a blog post!

Step 1: Create an Issue

By opening an issue you let the core team know what you are planning (which is a nice thing to do). It helps to gather the important information right from the start.

Open a new issue on the HZDR Gitlab now

Fill out the information as requested in the

1
2
3
>>>
  Quotation blocks
>>>

There is no need to set anything else, so you may now click the Submit Issue button. You will get redirected to the issue page that was just set up. Here you can lead a discussion with other contributors and the core team about your ideas or ask questions you have beforehand. It might be a good idea to bookmark it for later reference. Also note that your new issue has been assigned a unique issue number to identify it.

On this issue page you will find the Create merge request button. Click it to continue to the next step.

Step 2: Set up the Basis

Gitlab now has set up a merge request page for you and — even more important — created a new branch for your issue.

If you are not familiar with git think of a branch like your own version of the project, where you can do whatever you like without worrying about breaking anything on the live system.

To avoid chaos and confusion, specific ordering and naming conventions have been established, dictating which files go into which folders.

For that purpose you can click the Open in Web IDE button on the merge request page. This Web IDE is like a small file browser and editor in one and all you need for the rest of the tutorial.

Everything in the Right Place

Your blog post must be put into the folder /_posts/YYYY/MM/ where YYYY is the 4-digit year, MM is the 2-digit month (and later we need DD for the 2-digit day). If this path does not fully exist, you should now create it.

The dropdown-menu to create a new sub-folder becomes visible on hovering the parent folder.

This is the folder in which your blog-post per se will be located. If you want to include images, formulas or external resources a bit more has to be done. Please either refer to the Blog post template or ask @software-hifis-net for help in a comment on the merge request page.

Files

Within your (probably newly created) folder you now create a file with your blog post. The file must be named after the pattern YYYY-MM-DD-title-slug.md where YYYY, MM, DD is the same as above and the title-slug is — surprise — a slugified version of your blog post title.

If you do not know, what slugification is, do not despair: There is an online generator that can do that for you.

For comparison, the full path of this blog post looks like this:

1
/_posts/2020/01/2020-01-07-contributing-in-4-simple-steps.md

Frontmatter

When you select your newly created file in the Web IDE it will instantly open. Copy the following block into the first lines and replace the parts in brackets. The lines with a leading # are comments and can safely be removed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
title:  <Your post title as it appears on the website>
date:   <Desired shown publication date as YYYY-MM-DD>
authors:
  - <Your team member ID (usually the last name in lower case)>
# - <Repeat for each author>
layout: blogpost
title_image: default
categories:
  - <choose one of "blog", "announcement", "tutorial", "report">
# You can come up with a new category if none of the above fits,
# but please consult the team beforehand
tags:
  - <Short free text>
# - <Repeat for each tag>
excerpt:
  <One or two lines that serve as a preview text in the blog post overview>
---

This chunk of text is called the frontmatter and helps our website backend to recognize the following text as a blog post and generate all the nice things around it.

Step 3: Add Content

Leave an empty line behind the frontmatter and then write to your heart’s content. While the gitlab Web IDE only highlights the vanilla Markdown syntax, our blog system actually understands the far mightier Kramdown dialect, so you can use everything in The Kramdown Quick Reference.

Once you started to make changes the Commit button appears. If you click it, the view changes:

• The Unstaged Changes and Staged Changes appear on the left side
• A comparison view occupies the center and right side

1. Your file appears in the unstaged changes.
2. Double click it to move it to staged changes (Double clicking it again will move it back to unstaged changes).
3. Click Commit once more and enter a meaningful message what your last changes were.
4. Click Commit a final time.

Your changes are now stored as a commit (think of it as a permanent checkpoint) on your branch in the repository.

Side Notes

If you want to continue editing (or abort making a commit), you can switch back to the editing view with the button on the far left side under the project logo.

The whole staging changes mechanic seems a bit excessive if there is only one file involved, but becomes a boon in more complex scenarios. You can abbreviate the process a bit by leaving out step 2. The button for step 3 then is called Stage & Commit.

Please end your document with one(!) empty line. It will not show up in the final result, but makes a lot of tools involved in the review process very happy.

Step 4: Get it Reviewed

So you finished your work, and now it is time for it to be presented to the whole wide world.

But wait! Have you missed anything? Is everything as it should be?

To make sure, it is customary to have your blog post reviewed beforehand. You can start by going to the merge request page.

The super-fast way of triggering the process is to simply leave the following magic comment:

1
2
3
4
@software-hifis-net: Review please.
/label ~"Progress::Can review"
/assign @software-hifis-net 
/wip

Adding Emojis for accelerated response time is optional.

A core team member will get back to you and start looking into the matter. They might suggest changes and will help getting the visual appearance right. Your blog post will soon see the light of day.

Well done!