Docs from the ground up

Our docs are just Markdown, but offer you more flexibility and styling options.

Getting Started

If you already know Markdown, this is going to be straight-forward. For our docs we use markdown, and we get some additions through the Hugo static website generator and the Docsy theme, which we are going to line out here.

If you are unfamiliar with Markdown, please see https://guides.github.com/features/mastering-markdown/ (it’s a good cheat-sheet) or https://www.markdownguide.org/ if you are looking for something more substantial.

Starting at the top

Hugo allows you to specify metadata concerning an article at the top of the Markdown file, in a section called Front Matter. The Hugo website has a great article about it which explains all the relevant options.

For now, let’s take a look at a quick example which should explain the most relevant entries in Front Matter:

---
title: Using Flux on OpenShift
linkTitle: OpenShift
description: "How to bootstrap Flux on OpenShift."
weight: 20
---

## OpenShift Setup

Steps described in this document have been tested on OpenShift 4.6 only. 

[...]

The top section between two lines of --- is the Front Matter section. Here we define a couple of entries which tell Hugo how to handle article:

  • title is the equivalent of the <h1> in a HTML document or # <title> in a Markdown article

  • linkTitle is the title to be used in the menu or navbar (usually you might want to pick something shorter and easier to spot)

  • description is shown in a list of documents - maybe the directory you are looking at has a _index.md document - this is where you would see the list of articles (and the short descriptions). Note you can write multi-line descriptions like so:

    description: >
  more text here
  here is even more description

  • weight indicates where in the list of documents this is shown. It basically imposes an order on the articles in this directory.

Linking to other docs

You can easily link to other places using either

  • Absolute URLs, for linking off to external sites like https://github.com or https://k8s.io - you can use any of the Markdown notations for this, so
    • <https://k8s.io> or
    • [Kubernetes](https://k8s.io) will work.
  • Link to markdown files in other you can link to the .md file, or the resulting path. So if you are editing e.g. article1.md in content/en/docs/section-a and want to link to article2.md in the same directory you can use the following:
    • [link](article2.md)
    • [link](../article2/)
    • [link](/docs/section-a/article2/)

Getting the readers attention

Sometimes you will need to get the reader’s attention and clearly point out an edge case, or the current state of things. A good way to do this is using Docsy’s alert shortcode. Here is a simple example:

{{% alert title="Warning" color="warning" %}}
This is a warning.
{{% /alert %}}

The title and color keywords are optional.

Please refer to Docsy’s documentation of the feature.

Media, illustrations and more

If you want to illustrate the documentation and make things easier to read, there are lots of shortcodes either inherited through Hugo or through Docsy. Here is a list of our current favourites: