Handbook frontmatter

This page covers what frontmatter information is available on handbook pages, and their usage.

Format and title

At the top of the file, start with three hyphens, frontmatter entries, closing with three more hyphens:

1
2
3
4

---
title: "Page title"
other_attribute: "see other sections for what's valid"
---

Every page should have a title at minimum.

Description

A description is very useful to provide a summary and will be displayed in the list of leaf pages.

Whether a list of leaf pages is displayed depends on the layout. By default, the list is shown at the bottom of the page.

1

description: "Summary of page content."

Aliases

The aliases provide a list of other paths the current page should be for. Essentially, it’s providing redirect paths.

If a user visits one of the listed aliases, it will redirect to the current page.

1
2
3

aliases:
- /handbook/page/path/
- /handbook/old/page/location/

Controlled Documents

Controlled documents require the handbook frontmatter attribute controlled_document set to true. This attribute also renders the warning header, linking to controlled documents review section. Example:

1
2
3
4
5

---
title: "Controlled Document Procedure"
description: "GitLab deploys control activities through policies and standards that establish what is expected and procedures that put policies and standards into action."
controlled_document: true
---

Some pages might not need the warning banner which can optionally be disabled using the controlled_document_banner_disabled attribute.

1
2
3
4
5
6

---
title: "Public document without banner"
description: "..."
controlled_document: true
controlled_document_banner_disabled: true
---

Page Types (Layouts)

Note: To keep the handbook consistent, we discourage overriding the page type (aka layout).

You may notice that some pages have layout in the frontmatter, such as:

1
2
3
4

---
title: "Some page"
layout: default
---

The layout keyword was used in the old www-gitlab-com project and is no longer relevant. Please remove it if you see it.

We now use the docsy theme, which includes some provided layouts. By default, all handbook pages inherit the docs type specified in content/handbook/_index.md.

If you are adding a new top-level section to the site, we encourage you to do the same:

1
2
3
4
5
6
7
8

<!-- content/<new_section>/_index.md -->
---
title: New Section
cascade:
- type: docs
---

Welcome to this new section of the handbook site!

One exception to this is the “news” section of the internal-handbook which inherits the blog page type.

View page source - Edit this page - please contribute.