Front matter
The front matter is YAML code in between triple-dashed lines at the top of each file and provides important management options for our content. For example, the front matter allows us to ensure that existing links continue to work for pages that are moved or deleted entirely. This page explains the features currently available for front matters in Istio.
The following example shows a front matter with all the required fields filled by placeholders:
---
title: <title>
description: <description>
weight: <weight>
keywords: [<keyword1>,<keyword2>,...]
aliases:
- <previously-published-at-this-URL>
---
You can copy the example above and replace all the placeholders with the appropriate values for your page.
Required front matter fields
The following table shows descriptions for all the required fields:
| Field | Description |
|---|---|
title | The page’s title. |
description | A one-line description of the content on the page. |
weight | The order of the page relative to the other pages in the directory. |
keywords | The keywords on the page. Hugo uses this list to create the links under “See Also”. |
aliases | Past URLs where the page was published. See Renaming, moving, or deleting pages below for details on this item |
Rename, move, or delete pages
When you move pages or delete them completely, you must ensure that the existing
links to those pages continue to work. The aliases field in the front matter
helps you meet this requirement. Add the path to the page before the move or
deletion to the aliases field. Hugo implements automatic redirects from the
old URL to the new URL for our users.
On the target page, which is the page where you want users to land, add the <path>
of the original page to the front-matter as follows:
aliases:
- <path>
For example, you could find our FAQ page in the past under /help/faq. To help our users find the FAQ page, we moved the page one level up to /faq/ and changed the front matter as follows:
---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 13
aliases:
- /help/faq
---
The change above allows any user to access the FAQ when they visit https://istio.io/faq/ or https://istio.io/help/faq/.
Multiple redirects are supported, for example:
---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 13
aliases:
- /faq
- /faq2
- /faq3
---
Optional front matter fields
However, Hugo supports many front matter fields and this page only covers those implemented on istio.io.
The following table shows the most commonly used optional fields:
| Field | Description |
|---|---|
linktitle | A shorter version of the title that is used for links to the page. |
subtitle | A subtitle displayed below the main title. |
icon | A path to the image that appears next to the title. |
draft | If true, the page is not shown in the site’s navigation. |
skip_byline | If true, Hugo doesn’t show a byline under the main title. |
skip_seealso | If true, Hugo doesn’t generate a “See also” section for the page. |
Some front matter fields control the auto-generated table of contents (ToC). The following table shows the fields and explains how to use them:
| Field | Description |
|---|---|
skip_toc | If true, Hugo doesn’t generate a ToC for the page. |
force_inline_toc | If true, Hugo inserts an auto-generated ToC in the text instead of in the sidebar to the right. |
max_toc_level | Sets the heading levels used in the ToC. Values can go from 2 to 6. |
remove_toc_prefix | Hugo removes this string from the beginning of every entry in the ToC |
Some front matter fields only apply to so-called bundle pages. You can
identify bundle pages because their file names begin with an underscore _, for
example _index.md. In Istio, we use bundle pages as our section landing pages.
The following table shows the front matter fields pertinent to bundle pages.
| Field | Description |
|---|---|
skip_list | If true, Hugo doesn’t auto-generate the content tiles of a section page. |
simple_list | If true, Hugo uses a simple list for the auto-generated content of a section page. |
list_below | If true, Hugo inserts the auto-generated content below the manually-written content. |
list_by_publishdate | If true, Hugo sorts the auto-generated content by publication date, instead of by weight. |
Similarly, some front matter fields apply specifically to blog posts. The following table shows those fields:
| Field | Description |
|---|---|
publishdate | Date of the post’s original publication |
last_update | Date when the post last received a major revision |
attribution | Optional name of the post’s author |
twitter | Optional Twitter handle of the post’s author |
target_release | The release used on this blog. Normally, this value is the current major Istio release at the time the blog is authored or updated. |