Help:Docs

Create a wiki page.

Location

Directory	Description
content/<Language>/docs/	The base directory for the docs
content/<Language>/docs/prologue	The “Prologue"section of the docs
content/<Language>/docs/tutorial	The “Tutorial” section of the docs
content/<Language>/docs/code_of_conduct	The “Code of Conduct” section of the docs
content/<Language>/docs/help	The “Help” section of the docs

For an documentation page the menu structure is:

menu:
  docs:
    parent: "<the parent>" # e.g. "prologue", "tutorial", "help", ...

By convention, <the parent> is the directory name of the last directory in the directory path the file is created in, if the path was not inside a page-bundle . This is because of our directory structuring convention. If this doesn’t work, the directory structure is wrong and must be corrected. Either in the directory structure or in the config/_default/menus.toml.

To follow our convention we go on with weights. The weight sets the order, the docs are shown to the user. You find our order (weight) convention in config/_default/menus.toml For example the Tutorial has the weight = 20 in the config/_default/menus.toml, so the weight of the tutorial starts with 2 (ignore the 0 in 20, we are only interested in the 2). Then the first entry will get the weight = 200. The one after that will get weight = 210, then weight = 220 and so on.

Create a New Docs Page

To create a new page, use the command npm run create -- 'docs/<section>/<pageName>.md'. After that you can edit your newly created page, which is located in content/en/docs/<section>/<pageName>.md.

Example

Create a new page foo:

$ npm run create -- 'docs/tutorial/foo.md'

>[email protected] create
> exec-bin node_modules/.bin/hugo/hugo new "docs/tutorial/foo.md"

Content "/home/username/path_to_repository/repository_root_directory/content/en/docs/tutorial/foo.md" created

Front Matter

Every Markdown file contains a header section, called front matter, in the YAML format to configure parts of the page or website. A documentation page needs the following variables in the front matter.

Variable	Type	Description
`title`	`str`	The title of the page or ressource
`description`	`str`	The page description, normally for SEO
`lead`	`str`	The page description shown after the title or in cards
`date`	`datetime`	The datetime the page was created
`lastmod`	`datetime`	The datetime the page was modified. Should be the same as `date` when the creating a new page
`contributors`	`list` of `str`	A list of contributors
`draft`	`bool`	`flase` shows the page, `true` hides the page, as it does not exist
`images`	`list` of `str`	Images, which will be converted and moved to the static directory. Remember to add every image you used here
`math`	`bool`	This page contains LaTeX math. This option preloads the font and includes the KaTeX script in the script footer.
`menu`	`structure`	A structure which describes the path to the parent menu
`weight`	`int`	The weight, or priority of the page for page sorting
`toc`	`bool`	`true`, when a table of content should be created for that site; `false`, when not

You will find a complete list and how to use them inside the site in the Hugo docs →

The Datetime Type

The date and time according to ISO 8601 . The following table shows the extended format specified in ISO 8601 we use for our website to specify, when e.g. a page was created or edited. It has three parts:

the date
the time, including it's designator T
the timezone offset

We would prefere if you would use your local time together with the timezone offset (in this case it is mandatory), but you can also enter the time in UTC without the timezone offset.

Value	Optional	Description
`2021`	No	Year
`07`	No	Month
`08`	No	Day of the month
`T`	No	`T` is a designator, which indicates the start of the time representation
`12`	No	Hour
`34`	No	Minute
`56`	No	Second
`+` or `-`	Yes	`+` for a positive or `-` a negative timezone offset
`01`	Yes	Timezone offset in hours
`02`	Yes	Timezone offset in minutes

Formatting Examples

The following example uses the values from the table to show the format. It does not use the actual UTC. If you are not using the timezone offset, you must calculate UTC yourself.

Example with timezone offset: 2021-07-08T12:34:56+01:02
Example without timezone offset: 2021-07-08T12:34:56

Header Example

Remember, the front matter is a YAML structure embedded into the Markdown file. The --- delimiters signal Hugo that this is a front matter in the YAML format. Here is a generated example, how the front matter might look like:


---
title: "MyTitle"
description: "A description of the page content"
lead: "A lead to the page content"
date: 2021-10-08T14:48:42+01:00
lastmod: 2021-10-08T14:48:42+01:00
contributors: ["UserA" "UserB" "UserC"]
draft: false
images: ["avatar.svg" "foo.svg" "bar.svg"]
math: true
menu: [...]  # see below
weight: 50
toc: false# This is an example for a comment in YAML
---

Code

Below you find the implementation of the layout.

HTML

Single Page Layout

Defined in layouts/docs/single.html.

This code is licensed under the MIT license.

{{/*<!-- 

  Docs Layout
  ===========

  Contributors: Michael Sasser
  Maintainer: Michael Sasser
  License: MIT
  Version: 1
  Type: Single

  LAYOUT: /layouts/docs/single.html
  DOCS:   /content/<language>/wiki/Help:Layout_Docs.md
  STYLE:  /assets/scss/layouts/_docs.scss

  Description
  -----------

  The single layout page for the docs.

  Changelog
  =========

  Version 1
  ---------

  Initial release

-->*/}}

{{ define "main" }}
  <div class="container">
    <div class="row flex-xl-nowrap gap-1">
      <div class="col-md-12 col-lg-2 col-xl-2 docs-sidebar{{ if ne .Site.Params.options.navbarSticky true }} docs-sidebar-top{{ end }} d-none d-lg-block">
        <nav {{ if eq .Site.Params.menu.section.collapsibleSidebar false }}id="sidebar-default" {{ end }}class="docs-links" aria-label="Main navigation">
          {{ partial "sidebar/docs-menu.html" . }}
        </nav>
      </div>
      {{ if ne .Params.toc false -}}
      <nav class="docs-toc{{ if ne .Site.Params.options.navbarSticky true }} docs-toc-top{{ end }} d-none d-xl-block col-xl-2" aria-label="Secondary navigation">
        {{ partial "sidebar/docs-toc.html" . }}
      </nav>
      {{ end -}}
      {{ if .Params.toc -}}
      <main class="docs-content col-md-12 col-lg-10 col-xl-8">
      {{ else -}}
      <main class="docs-content col-md-12 col-lg-10 col-xl-8 mx-xl-auto">
      {{ end -}}
        {{ if .Site.Params.options.breadCrumb -}}
          <!-- https://discourse.gohugo.io/t/breadcrumb-navigation-for-highly-nested-content/27359/6 -->
          <nav aria-label="breadcrumb">
            <ol class="breadcrumb">
              {{ partial "main/breadcrumb" . -}}
              <li class="breadcrumb-item active" aria-current="page">{{ .Title }}</li>
            </ol>
          </nav>
        {{ end }}
        <h1>{{ .Title }}</h1>
        <p class="lead">{{ .Params.lead | safeHTML }}</p>
        {{ if ne .Params.toc false -}}
        <nav class="d-xl-none" aria-label="Quaternary navigation">
          {{ partial "sidebar/docs-toc.html" . }}
        </nav>
        {{ end -}}
        {{ .Content }}
        {{ partial "main/docs-navigation.html" . }}
      </main>
    </div>
  </div>
{{ end }}

List Page Layout

Defined in layouts/docs/list.html.

This code is licensed under the MIT license.

{{/*<!-- 

  Docs Layout
  ===========

  Contributors: Michael Sasser
  Maintainer: Michael Sasser
  License: MIT
  Version: 1
  Type: List

  LAYOUT: /layouts/docs/list.html
  DOCS:   /content/<language>/wiki/Help:Layout_Docs.md
  STYLE:  /assets/scss/layouts/_docs.scss

  Description
  -----------

  The list layout page for the docs.

  Changelog
  =========

  Version 1
  ---------

  Initial release

-->*/}}

{{ define "main" }}
  <div class="container">
    <div class="row justify-content-center">
      <div class="col-md-12 col-lg-10 col-xl-8">
        <article>
          <h1 class="text-center">{{ if eq .CurrentSection .FirstSection }}{{ .Section | humanize }}{{ else }}{{ .Title }}{{ end }}</h1>
          <div class="text-center">{{ .Content }}</div>
          <div class="card-list">
            {{ $currentSection := .CurrentSection }}
            {{ range where .Site.RegularPages.ByTitle "Section" .Section }}
              {{ if in (.RelPermalink | string) $currentSection.RelPermalink }}
                <div class="card my-3">
                  <div class="card-body">
                    <a class="stretched-link" href="{{ .RelPermalink }}">{{ .Params.title | title }} &rarr;</a>
                  </div>
                </div>
              {{ end }}
            {{ end }}
          </div>
        </article>
      </div>
    </div>
  </div>
{{ end }}

Archetype

Defined in layouts/docs.md.

This code is licensed under the MIT license.

---
title: "{{ replace .Name "-" " " | title }}"
description: ""
lead: ""
date: {{ .Date }}
lastmod: {{ .Date }}
contributors: []
draft: true
images: []
menu:
  docs:
    parent: ""
weight: 999
toc: true
---

Categories	Contributors
Help, Contribute and Layout	Michael Sasser

Help:Docs

Location #

Create a New Docs Page #

Example #

Front Matter #

The Datetime Type

Formatting Examples

Header Example

Code #

HTML #

Single Page Layout #

List Page Layout #

Archetype #

Categories

Contributors

Location

Create a New Docs Page

Example

Front Matter

Code

HTML

Single Page Layout

List Page Layout

Archetype