Docs from the ground up

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/flux/section-a and want to link to article2.md in the same directory you can use the following:
  • [link](article2.md)
  • [link](../article2/)
  • [link](/flux/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:

• pageinfo for quick “banner type” info boxes
• tabpane for pieces of text that go in different tabs
• cardpane and card for adding cards and card panes
• gist, youtube, tweet and more: lots of shortcodes we get from Hugo itself.

Code snippets

You can embed code snippets from a file. Please refer to https://www.docsy.dev/docs/adding-content/shortcodes/#include-code-files for hot to use the readfile shortcode.

Tabbed sections

You can create tabbed sections that contain both markdown and code snippets. Please refer to https://www.docsy.dev/docs/adding-content/shortcodes/#tabbed-panes for how to use the tabpane and tab shortcodes.

Gallery shortcodes

You can use gallery shortcodes to easily create and display photo galleries or image sliders within your posts or blogs. Please refer to https://github.com/mfg92/hugo-shortcode-gallery for how to use the hugo-shortcode-gallery tool.