Writing an Article
5 minute read 11 Jan 2017

Articles are the most important content and each article represents a page. They are located in the _articles/ directory and are written in Markdown.

An article is comprised of two things:

  1. article header
  2. article content

Article Header

title: Markdown Elements
category: Writing on Site Stacker Docs
tags: documentation,markdown
date: 2015-11-06 00:00:00
readtime: 5

Every article must include a Jekyll Front Matter header with the following information:

  • title (required) The Article title. This is very important to get right!
  • category The article category.
  • tags Article tags.
  • date The date when the article was last modified.
  • readtime Article read time.

Article title

The article’s title is also the page title and should be as descriptive as possible. This is the only required field in the article header, although it’s highly recommended to set all the fields.

Important: Article title should be unique!
Every article title should be unique throughout the entire site, even if the file is added in a subdirectory in _articles.

Article file

The title dictates the name of the article’s file in _articles/. The file name is a slug1 of the title, suffixed with the .md extension.

Article file name rule

To find the slug1 of an article take its title and:

  1. lowercase all letters
  2. replace all special characters (non alphanumeric) with a single - (dash)

After you determined the slug1, add the .md extension to it and you have the article file name.


Article title Article file name
Writing on Site Stacker writing-on-site-stacker.md
2. Configure the server 2-configure-the-server.md
Ask Questions !!! ask-questions.md
No more system_repository.xml no-more-system-repository-xml.md

Note: The article file can be placed directly in the _articles/ folder, or inside another directory. The extra directory it’s only for organization purposes and can have any name, but it’s recommended to name it by its category slug, as the article file name.

Article category

Every article should have a category, although if you don’t specify one the article will be added to the Uncategorized category (not recommended). Besides that a category offers better organization, it also helps finding the article in the search results.

If you specify an existing2 category for an article, you don’t have to do anything else. However if you specify a category that doesn’t exist yet, there’s one more thing you need to do, which is to add the new category file (see below).

Adding a new category

Each category has its own page (e.g. Writing on Site Stacker Docs ). If you want to add a new category, you need to create a new file named using the same rules as the article file name, but with the .html extension, in the _categories/ folder.


Category title Category file name
Writing on Site Stacker writing-on-site-stacker.html
Install Site Stacker (on production) install-site-stacker-on-production.html

The file should contain the following:

title: Writing on Site Stacker Docs
{% include category.html category=page.title %}

Note the Jekyll Front Matter as in the article header that contains the category title. You should change it to whatever your category is called.

Important: Be consistent
When specifying categories, make sure you’re consistent and always use the same case for a category.

Article tags

Articles can have tags. Tags are optional but if present are used to improve the article’s discoverability in the search results.

Tags can be specified as a YAML list or as comma-separated values (no spaces). See tags on jekyll docs for more details.

Tags as a YAML list

  - first tag
  - second tag

Note: tags can contain spaces in this format.

Tags as comma-separated values

tags: development,model,strategy

Note: tags cannot contain spaces in this format, any space will be transformed into a tag.

Article date

It’s highly recommended to specify a date for every article. The date is the last time the article was modified and it is a valuable information for a user reading an article.

The date can be given in the following formats:

  • YYYY-MM-DD HH:MM:SS (assuming UTC)
  • YYYY-MM-DD HH:MM:SS +/-TTTT (to specify a time zone using an offset from UTC. e.g. 2008-12-14 10:30:00 +0200)

Note that you cannot omit the time part. You can only leave it zero, e.g. 2008-12-14 00:00:00, not 2008-12-14.

Important: Update the date
When you edit an article, don’t forget to update its date.

Article read time

It’s a good idea to specify how long does it take to read an article, in minutes. Generally you should keep it at or under 5 minutes, but greater values might also be appropriate for more complex guides.

The expected value is always the number of minutes, e.g. readtime: 5.

Article Content

The article content is what comes after the header and is what is displayed on the site.

See Markdown Elements for a comprehensive guide that includes all the Markdown elements you can use in an article.


You can add external or internal links in an article. See Markdown Elements #Links for the syntax.

You can link to other articles in the documentation by simply using the other article’s slug1 as the link.

To reference the Markdown Elements article, use:

[Markdown Elements](markdown-elements)

To reference the Markdown Elements Links header in the Markdown Elements article append the header slug1 like this:

[Markdown Elements Links](markdown-elements#links)

Link to headers within the same article

If you want to link to a header inside the current article you can omit the article title from the link.

To link to Article Header, use:

[Article Header](#article-header)

To link to other pages that are not articles, you need to use an absolute url prefixed with {{ site.github.url }}.

For example, to link to the Contributing to Site Stacker Docs category page, use:

[Contributing to Site Stacker Docs]({{ site.github.url }}/categories/contributing-to-site-stacker-docs)


To include images in an article you need to upload the images somewhere. The recommended way is to head over to the Site Stacker Docs repository on Gitlab and upload your images in an existing issue, or create a new issue if none exists for that article. See sitestacker/docs#1 for an example.

Every article should have one and only one issue, so make sure you search for it first before creating a new one. Once in an issue, simply drag and drop the image, save the issue and grab the image url to be used in the article.

See Markdown Elements #Images for the syntax to include images.

  1. What is a “slug” in Django?  2 3 4 5

  2. You can find all existing categories on the site homepage