Front matter reference

Front matter is the block of YAML at the top of a Markdown file, between two lines that hold only ---. This guide lists every key Osirion.Blazor reads, what each does and what happens when it is missing. It is for anyone writing pages for a site built with the library.

Before you start

Read How content is organized first: it covers slug, order, published and redirect_from in context. The keys below are the ones the YAML parser of Osirion.Blazor 4.1.0 maps onto its front matter model.

1. Write the block

---
title: "Hello, world"
date: 2026-10-17
---

The page text, in Markdown.

Keys are snake_case (last_modified, not lastModified). Unknown keys are ignored: the parser maps the YAML onto the front matter model and skips what it does not know, without a warning. A typo in a key name therefore disappears silently. To keep values of your own, put them under custom_fields (step 4).

A file with no front matter block still loads: its title is its file name, its language comes from its folder, its date is the creation time of the file and every other value takes its default.

2. Use the keys

Write lists as YAML lists, or inline as [a, b]. A single value where a list belongs (tags: foo), and a value of the wrong type (order: abc, published: maybe), stop the file from loading. The provider logs the reason and goes on with the other files.

A value that contains a colon, or starts with a character YAML reads as syntax, needs quotes: title: "Setup: step one".

3. Write dates the parser can read

date and last_modified are read as text and parsed with the invariant culture. Use ISO form, with or without a time:

date: 2026-10-17
last_modified: 2026-10-17T09:30:00Z

A date without a time zone is taken as UTC. A page without a date key is not an error either: it gets the creation time of its file (the date of the file's last commit with a GitHub provider, which costs one more request to GitHub for each undated file the first time it is read), the same as a date that cannot be parsed and a file with no front matter block. This arrives in the release after 4.1.0; in 4.1.0 a page with front matter and no date key gets the day the content was loaded, so it changes on every restart, and the GitHub provider still does. Even with the fix, a file's creation time changes with a fresh checkout or deployment, and the date of a last commit moves when the file is edited, so an undated page can still jump to the top of newest-first lists and move its sitemap lastmod and feed date. Always write date.

last_modified is what search engines and feed readers see as the change date. When it is missing, the page was last modified on its date. The file's write time is not used, because a fresh checkout gives every file the time of the checkout. If you edit files in place and want write times, set UseFileWriteTimeAsLastModified on the FileSystem provider (it is off by default and applies only to that provider). Bump last_modified when you make a change worth telling a crawler about.

4. Keep your own values in custom_fields

custom_fields:
  group: guides
  badge: new
  related:
  - /docs/content
  - /docs/seo

Read them from the item in code:

@using Osirion.Blazor.Cms.Domain.Entities

@if (Item.Metadata?.CustomFields.TryGetValue("group", out var group) == true)
{
    <span>@group</span>
}

@code {
    [Parameter, EditorRequired]
    public ContentItem Item { get; set; } = default!;
}

Values arrive as the YAML parser's plain objects: a scalar is always a string, even 5 or true (parse it yourself), a list is a List<object> and a map is a Dictionary<object, object>. The library reads none of them. The documentation site of Osirion.Blazor groups its sidebar by custom_fields.group.

5. Control search and social tags with seo_properties

seo_properties overrides what SeoMetadataRenderer writes for the page. Every key is optional.

These defaults apply to every page. A page with a front matter block has type: Article unless it sets another, so it gets Article; a file with none gets WebPage for the schema type, and og:type follows the schema type for both.

The page components pick their own schema types (DocumentPage uses TechArticle, ArticlePage takes the types you pass), so type matters mainly when you call the renderer yourself. See the SEO guide for what the renderer writes as a whole.

6. Put it together

A complete page, with the effect of each key in a comment:

---
id: 'guide-deploy'                  # pairs translations of this page
order: 4                            # position in an order-sorted list
layout: docs                        # stored on the item; your code may read it
title: "Deploy the site"            # heading, link text, base of the <title>
permalink: /docs/deploy             # the page's address (release after 4.1.0)
description: "Publish the site to a web host."   # meta description, summaries
author: Your Name                   # byline and structured data
date: 2026-10-17                    # publication date
last_modified: 2026-10-20           # change date for crawlers and feeds
featured_image: /images/deploy.png  # card, hero and Open Graph image
categories:
- Guides                            # category pages, article:section
tags:
- deployment                        # tag pages, keywords
is_featured: false                  # featured lists
published: true                     # false hides the page everywhere
slug: deploy                        # address: docs/deploy
series: Build a site                # series navigation
series_order: 3                     # position in the series
redirect_from:
- /docs/publish                     # redirects here with UseOsirionRedirects
lang: en                            # language of this page
custom_fields:
  group: guides                     # your own values
seo_properties:
  title: 'Deploy an Osirion.Blazor site'   # <title> before the site name
  description: 'Publish a site built with Osirion.Blazor to a web host.'
  canonical: 'https://example.com/docs/deploy'
  robots: index, follow
  og_title: 'Deploy the site'
  og_description: 'Publish the site to a web host.'
  og_image_url: /images/deploy-social.png
  og_type: article
  twitter_card: summary_large_image
  type: TechArticle
---

Check that it works

Copy the block into a file in your content folder and open the throwaway /content-check page from the content guide. The page should be listed with the address you expect and the status Published. If it is missing, read the application log for Error processing markdown file: the message follows with the line and column of the value that could not be read, or the field that was refused (Slug, Title), and why. To see the tags a page writes, open it in the browser, choose View Source and look for <title>, rel="canonical", og: and application/ld+json in the head.

Next steps

• How content is organized: addresses, order, drafts and redirects
• Localization: lang, id and language folders
• SEO: what the library writes for search engines and what stays your job
• SeoMetadataRenderer: the parameters behind seo_properties
• CMS web package: the content components