Editing#

The articles in this KB are written in markdown.

Quick Changes: The “Edit this page” button on the bottom right of each page directly opens the corresponding file in GitHub (if you have the correct repo permissions).

The GitHub / Cloudflare CI automatically deploys pushed commits to this site (No need for local dependency management).

Advanced: The website is build from static markdown files using the hugo framework. With installed hugo and cloned repository, the page can be previewed locally with the hugo server command at localhost:1313.

• The different pages live as markdown files under /content/docs, simply add/modify the plain text.
• The left menu bar is automatically updated based on the file tree
• The right menu bar is automatically generated from markdown headlines (no manual action required) and can be disabled with bookToc: false in the header of each article.

URLs#

If you use the ref and relref shortcodes, hugo can tell, when links are broken (e.g., if an article was moved). So instead of [This page](/docs/editing-this-kb/), you can use:

• [This page]({{< ref "/docs/other/editing" >}}) (ref example) or [This page]({{< ref "/docs/other/editing-this-kb.md" >}})
• [This page]({{< relref "./editing-this-kb" >}}) (relref example) or [This page]({{< relref "./editing-this-kb.md" >}}).

Hugo will refuse to build the website, if a referenced page is missing.

Theme#

This knowlegebae uses the Hugo “Book” theme. Settings for this theme are in /config.toml, the theme itself in /themes/book/. Our custom html and css goes in the /assets and /layouts folders (of the full project, not the ones inside /theme). To update the theme: clone the GitHub repo inside /themes and optionally remove some of their devel stuff (.git, npm files, etc.) to save space.

Header Variables#

Header variables in each article file allow for setting some additonal parameters. In YAML (---) or TOML (+++) format:

---
title: "" # Title of the page
description: "" # Short description, displayed in summaries amd listings
bookCollapseSection: true # Collapes section in left-side menu (see all sections with arrow next to them)
bookFlatSection: true # Hide main section page (see e.g., "Other" in left menu)
bookToc: false # Hide right-side table of contents
weight: 1 # Order of pages (lower number -> higher in order)
---

+++
title = "" # Title of the page
description = "" # Short description, displayed in summaries amd listings
bookCollapseSection = true # Collapes section in left-side menu (see all sections with arrow next to them)
bookFlatSection = true # Hide main section page (see e.g., "Other" in left menu)
bookToc = false # Hide right-side table of contents
weight = 1 # Order of pages (lower number -> higher in order)
+++

Shortcodes#

Shortcodes are short commands in the form of {{< shortcode >}} in Markdown files. They allow for including some HTML elements and additional styling.

Buttons#

Buttons are styled links that can lead to local page or external link.

{{< button relref="/" [class="..."] >}}Get Home{{< /button >}}
{{< button href="https://github.com/alex-shpak/hugo-book" >}}Contribute{{< /button >}}

Columns#

Columns help organize shorter pieces of content horizontally for readability.

{{< columns >}} <!-- begin columns block -->
# Left Content
Lorem markdownum insigne...

<---> <!-- magic sparator, between columns -->

# Mid Content
Lorem markdownum insigne...

<---> <!-- magic sparator, between columns -->

# Right Content
Lorem markdownum insigne...
{{< /columns >}}

Details#

Details shortcode is a helper for details html5 element. It is going to replace expand shortcode.

{{< details "Title" [open] >}}
## Markdown content
Lorem markdownum insigne...
{{< /details >}}

{{< details title="Title" open=true >}}
## Markdown content
Lorem markdownum insigne...
{{< /details >}}

Expand#

Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.

{{< expand >}}
## Markdown content
Lorem markdownum insigne...
{{< /expand >}}

With Custom Label

{{< expand "Custom Label" "..." >}}
## Markdown content
Lorem markdownum insigne...
{{< /expand >}}

Hints#

Hint shortcode can be used as hint/alerts/notification block. There are 3 colors to choose: info, warning and danger.

{{< hint [info|warning|danger] >}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}

Markdown content Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa

Markdown content Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa

Markdown content Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa

Tabs#

Tabs let you organize content by context, for example installation instructions for each supported platform.

{{< tabs "uniqueid" >}}
{{< tab "MacOS" >}} # MacOS Content {{< /tab >}}
{{< tab "Linux" >}} # Linux Content {{< /tab >}}
{{< tab "Windows" >}} # Windows Content {{< /tab >}}
{{< /tabs >}}

Example#

Our custom shortcut. Similar to hint for good / bad / neutral examples.

{{< example [good|neutral|bad] >}}
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< example >}}