File structure

Pages that include images

Important note

We recommend using this structure even for pages that do not contain images, for several reasons:

• It is quite common to add images later on. Using this format right away saves time not having to switch structure.
• Consistency and convenience when working on multiple pages.

Directory structure

A page of documentation that includes images must be organised as a subdirectory that contains a file named index.md and the image files that are embedded in that page. The name of the subdirectory defines the name of page in the URL; that name should only use alphanumeric characters or the - (hyphen) symbol.

For instance, create a sub-directory named new-topic, and within it a file named new-topic/index.md.

YAML header

The file index.md for each page must start with a YAML header that include a certain set of fields.

For instance:

---
title: "First connection over SSH"
description: "Users connecting to the CCB cluster for the first time must use the username and password send to them by email when their account was created."
lead: "Users connecting to the CCB cluster for the first time must use the username and password send to them by email when their account was created."
date: 2020-10-06T08:48:57+00:00
lastmod: 2020-10-06T08:48:57+00:00
draft: false
images: []
menu:
  docs:
    parent: "ssh"
weight: 210
toc: true
---

The field title defines the title displayed at the top of the page.

The fields description and lead are typically given the same information, a one-sentence summary of the section. In particular, the field lead defines the text displayed under the title on the page.

The fields date and lastmod can be left out of date, as they are not currently used nor displayed.

The field menu: docs: parent: must be set to the same value for all pages that belong to the same section of documentation. The value of that field is typically set to the name of the directory directly above the subdirectory that contains the page.

The field weight: must be set to a unique value that controls the ordering of pages within and between sections. The ordering of pages controls the automatically generated links at the bottom of each page, to the previous page and the next page.

Notably:

• Smaller values of weight appear earlier in the earlier pages of the documentation.
• The strategy so far uses the same digit in the hundreds for all the pages in the same major section, the sane digit in the tens for all the pages in the same minor subsection, and the digit of the unit to order pages within each minor subsection.

The field toc controls the presence of a table of content within each page of documentation.

Images

Image files embedded in the page must be placed inside that same directory (e.g., new-topic/screenshot.png).

In the file new-topic/index.md, the image new-topic/screenshot.png can be embedded using the Markdown syntax below:

![Figure caption.](screenshot.png)

• The square brackets contain alternate text that will be displayed if the image cannot be displayed for any reason.
• The round brackets contain the relative path to the image file to display.

Pages that do not contain images

At a minimum, a new page of documentation can be created as an arbitrarily named Markdown file.

The name of the Markdown file defines the name of page in the URL; that name should only use alphanumeric characters or the - (hyphen) symbol.

The Markdown file must contain a YAML header, following the same rules as that of a page that includes images.