Frontmatter Reference

April 16, 2026 · 4 min read

Contents

Minimal example
Full field reference
Title resolution order
The YAML colon rule
Accepted date formats
Slug and URL generation
See also

Every published note starts with a YAML frontmatter block between --- delimiters. InkStone reads these fields to control publishing, routing, display, and SEO.

Minimal example

---
website: true
title: My Post
date: 2026-04-16
---

That's all you need. Everything else is optional.

Full field reference

---
# ── Publishing ──────────────────────────────────────────
website: true          # Required. Omit to keep the note private (not a web page).
type: homepage         # Optional: homepage | listing | book
                       #   homepage  — renders this note's content at the section root
                       #   listing   — auto-generates a post index at the section root
                       #   book      — uses the book template with cover/metadata header

# ── Identity ─────────────────────────────────────────────
title: My Post         # Overrides the H1 heading and filename. Wrap in quotes if it contains a colon.
slug: my-post          # URL slug. Auto-derived from title if omitted.
aliases:               # Alternate names that [[wiki-links]] will resolve to this note.
  - alternate name
  - another alias

# ── Dates ────────────────────────────────────────────────
date: 2026-04-16       # Publication date. Accepted formats: YYYY-MM-DD, DD/MM/YYYY, and more.
updated: 2026-04-20    # Last-modified date. Shown as "Updated …" in post meta and JSON-LD.

# ── Author ───────────────────────────────────────────────
author: "Jane Doe"     # String or list. Shown in post meta and JSON-LD.
# author:
#   - Jane Doe
#   - John Smith

# ── Listing & Discovery ───────────────────────────────────
summary: "..."         # Shown on listing cards. Auto-derived from the first ~200 chars if omitted.
featured: true         # Highlight in the section's featured area on the listing page.
priority: 0            # Featured posts only. Lower = higher rank. Date breaks ties.
tags:                  # Content tags. Merged with inline #hashtags from the note body.
  - python
  - philosophy

# ── Navigation ────────────────────────────────────────────
menu_order: 1          # Pin this note to the top nav. Lower number = further left.
                       # Appended after auto-generated section links.

# ── Branding (header icon & title) ───────────────────────
icon: _attachments/logo.png   # Image shown beside the site title in the header.
                               # Accepts a vault-relative path, /static/... URL, or full URL.
                               # Cascades to all child pages unless overridden lower down.
site_title: "My Brand"         # Replaces the website name displayed in the header.
                               # Also cascades to child pages.

# ── Banner image ─────────────────────────────────────────
banner: "https://example.com/image.jpg"
banner_x: 0.5          # Horizontal focal point, 0–1 (default: centre).
banner_y: 0.4          # Vertical focal point, 0–1 (default: centre).

# ── Root homepage only ───────────────────────────────────
show_search: true      # Adds a Search link to the top nav.
show_tags: true        # Adds a Tags link to the top nav.
default_theme: dark    # Initial theme for new visitors: "dark", "light", or "system" (default).
                       # "system" follows the OS prefers-color-scheme. Visitors can always
                       # override with the toggle; their choice is stored in localStorage.

# ── Multilingual ─────────────────────────────────────────────
language: en           # Root homepage only. Sets the default language for the site (e.g. "en", "ru").
lang: ru               # Per-note language code. Overrides filename suffix if both are present.
                       # Filename suffix _RU.md is equivalent to setting lang: ru in frontmatter.

# Social links — one key per platform. InkStone extracts the handle from the
# URL and renders [icon] @handle in the footer. Supported keys:
# github, mastodon, bluesky, twitter, instagram, linkedin, facebook, youtube
github: https://github.com/you
mastodon: https://mastodon.social/@you
bluesky: https://bsky.app/profile/you.bsky.social
---

Title resolution order

When no title is set in frontmatter, InkStone falls back in this order:

Frontmatter title
First # H1 heading in the note body
Filename (without .md)

The YAML colon rule

Any string value that contains a colon (:) must be wrapped in double quotes, otherwise YAML silently parses it as a nested mapping and the field breaks.

title: "From Vault to Web: How This Works"   # correct
title: From Vault to Web: How This Works      # broken — YAML sees a nested dict

InkStone logs a WARNING to stderr and falls back to H1/filename when it detects a dict-valued title.

To embed literal " characters in a title, wrap the whole value in single quotes:

title: '"Hello World" Considered Harmful'   # → "Hello World" Considered Harmful

Accepted date formats

InkStone parses date and updated in any of these formats:

Format	Example
`YYYY-MM-DD`	`2026-04-16`
`YYYY-MM-DD HH:MM`	`2026-04-16 09:30`
`YYYY-MM-DD HH:MM:SS`	`2026-04-16 09:30:00`
`YYYY/MM/DD`	`2026/04/16`
`DD-MM-YYYY`	`16-04-2026`
`DD/MM/YYYY`	`16/04/2026`

Slug and URL generation

slug is auto-generated from title if omitted: lowercased, spaces → hyphens, non-alphanumerics stripped.
The URL is /<section>/<slug> for posts in subfolders, or /<slug> for vault-root notes.
aliases register additional wiki-link names that all resolve to the same URL.