Docs from the ground up
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:
titleis the equivalent of the
<h1>in a HTML document or
# <title>in a Markdown article
linkTitleis the title to be used in the menu or navbar (usually you might want to pick something shorter and easier to spot)
descriptionis shown in a list of documents - maybe the directory you are looking at has a
_index.mddocument - 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
weightindicates where in the list of documents this is shown. It basically imposes an order on the articles in this directory.
Mixing Front Matter and top-level headingsPlease note: Everything below the Front Matter entry is just the regular Markdown article as you would normally write it. Please note that headings start with
## <..>, as the title is defined in the Front Matter. Mixing Front Matter and
# <..>headings will trip up Hugo and it might error out or not show the article.
Linking to other docs
You can easily link to other places using either
- Absolute URLs, for linking off to external sites like
https://k8s.io- you can use any of the Markdown notations for this, so
- Link to markdown files in other you can link to the
.mdfile, or the resulting path. So if you are editing e.g.
content/en/flux/section-aand want to link to
article2.mdin the same directory you can use the following:
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:
pageinfofor quick “banner type” info boxes
tabpanefor pieces of text that go in different tabs
cardfor adding cards and card panes
tweetand more: lots of shortcodes we get from Hugo itself.
You can embed code snippets from a file. Please refer to
hot to use the
You can create tabbed sections that contain both markdown and code snippets.
Please refer to
for how to use the
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