# Front matter

Zensical supports the inclusion of metadata in the front matter of a Markdown file that is stripped from the file contents before the rest of the content is handed over to the Markdown parser. It can be used in templates to customize rendering per-page.

> [!TIP]
>
> **Centralize metadata**
>
> You can also provide metadata through the [meta plugin](<https://zensical.org/docs/compatibility/mkdocs/plugins/#meta>), which lets you define metadata in `meta.yml` files instead of repeating it in each page's front matter.

## Page title

This property overrides the page title in the navigation and in the `title` tag:

```yaml
---
title: Lorem ipsum dolor sit amet
---

# Page title
...
```

## Page description

A Markdown file can include a description that is added to the HTML head `meta` tags of a page:

```yaml
---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---

# Page title
...
```

## Page icon

Each page can define an icon that is displayed in the navigation, which must come from any of the [included icon sets](<https://zensical.org/docs/authoring/icons-emojis/#included-icon-sets>):

```yaml
---
icon: lucide/braces
---

# Page title
...
```

## Page status

A status can be assigned to each page and displayed in the navigation sidebar. First, associate a status identifier with a description by adding the following to your configuration:

```toml
[project.extra.status]
<identifier>: "<description>"
```

```yaml
extra:
  status:
    <identifier>: <description>
```

The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a status `Recently added`, you can set `new` as an identifier:

```toml
[project.extra.status]
new = "Recently added"
```

```yaml
extra:
  status:
    new: Recently added
```

The page status can now be set with the front matter `status` property. For example, you can mark a page as `new` with the following lines at the top of a Markdown file:

```yaml
---
status: new
---

# Page title
...
```

The following status identifiers are already defined:

- – `new`
- – `deprecated`

You can define a custom page status this way. To give it an icon other than the default, also configure it in your [`extra.css`](<https://zensical.org/docs/customization/#additional-css>).

## Page template

You can use the `template` metadata attribute to set a [custom template](<https://zensical.org/docs/customization/#custom-templates>) for a page, which will be used instead of the default `main.html`. Note that you need to place the template you want to use in your [overrides directory](<https://zensical.org/docs/customization/#configuring-overrides>), which needs to be configured before you can use it.

For example, to apply the `my_homepage.html` template to the page:

```yaml
---
template: my_homepage.html
---

# Page title
...
```

## Hide page elements

Use the `hide` front matter property to hide one or more elements of a page:

```yaml
---
hide:
  - navigation
  - toc
---

# Page title
...
```

The following values are supported:

| Value | Element |
| --- | --- |
| `navigation` | [Navigation sidebar](<https://zensical.org/docs/setup/navigation/#hide-the-sidebars>) |
| `toc` | [Table of contents](<https://zensical.org/docs/setup/navigation/#hide-the-sidebars>) |
| `path` | [Navigation path](<https://zensical.org/docs/setup/navigation/#hide-the-navigation-path>) |
| `footer` | [Previous and next page links](<https://zensical.org/docs/setup/footer/#hiding-prevnext-links>) |
| `feedback` | [Feedback widget](<https://zensical.org/docs/setup/analytics/#hide-the-feedback-widget>) |
| `tags` | [Page tags](<https://zensical.org/docs/compatibility/mkdocs/plugins/#tags>) |

To exclude a page from search, see [Search exclusion](<https://zensical.org/docs/setup/search/#search-exclusion>).

## Customization

### Use in templates

You can add further custom data to the front matter and use it in your [template overrides](<https://zensical.org/docs/customization/#template-overrides>) or [custom templates](<https://zensical.org/docs/customization/#custom-templates>). A common use case is to add metadata to the HTML `head`. Say you want to control whether a page is indexed by search engines by adding a [meta robots `nofollow` tag](<https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag>).

The first thing you would need to do is to copy `main.html` to your [overrides directory](<https://zensical.org/docs/customization/#configuring-overrides>) and add a [block override](<https://zensical.org/docs/customization/#overriding-blocks>) for the `extrahead` block that adds a robots meta tag:

```html
{% extends "base.html" %}

{% block extrahead %}
  {% if page and page.meta and page.meta.robots %}
    <meta name="robots" content="{{ page.meta.robots }}" />
  {% else %}
    <meta name="robots" content="index, follow" />
  {% endif %}
{% endblock %}
```

Note that the block override uses an `else` branch to set a default when the page metadata does not specify a value. Now, you can specify the robots meta tag content from the page header:

```yaml
---
robots: noindex, nofollow
---

# Page title
...
```

### Use in plugins

Plugins can make extensive use of page metadata. For example, the tags plugin reads tags from page metadata, and the meta plugin can provide metadata for multiple pages at once.