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/)

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:

Code snippets

You can embed code snippets from a file.

language is any language supported by GitHub flavored markdown.

file is the path to the file you want to use in the code block.

{{% codeblock file="/static/snippet/example.yaml" language="yaml" %}}
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/stefanprodan/podinfo
  ref:
    branch: master
  ignore: |
    # exclude all
    /*
    # include charts directory
    !/charts/    

Tabbed sections

You can create tabbed sections that contain both markdown and code snippets.

{{% tabs %}}
{{% tab "codeblock and text in a tab" %}}

cool sample text

{{% codeblock file="/static/snippet/example.yaml" language="yaml" %}}

{{% /tab %}}
{{% tab "codeblock in a tab" %}}

{{% codeblock file="/static/snippet/example.yaml" language="yaml" %}}

{{% /tab %}}
{{% tab "text in a tab" %}}

cool sample text

{{% /tab %}}{{% /tabs %}}

cool sample text

apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/stefanprodan/podinfo
  ref:
    branch: master
  ignore: |
    # exclude all
    /*
    # include charts directory
    !/charts/    

apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/stefanprodan/podinfo
  ref:
    branch: master
  ignore: |
    # exclude all
    /*
    # include charts directory
    !/charts/    

cool sample text