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.

Page title¶

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

---
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:

---
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:

---
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:

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

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:

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

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:

---
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.

Page template¶

You can use the template metadata attribute to set a custom template 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, which needs to be configured before you can use it.

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

---
template: my_homepage.html
---

# Page title
...

Hide page elements¶

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

---
hide:
  - navigation
  - toc
---

# Page title
...

The following values are supported:

To exclude a page from search, see Search exclusion.

Customization¶

Use in templates¶

You can add further custom data to the front matter and use it in your template overrides or 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.

The first thing you would need to do is to copy main.html to your overrides directory and add a block override for the extrahead block that adds a robots meta tag:

{% 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:

---
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.