Frontmatter Reference

Every published note starts with a YAML frontmatter block between --- delimiters. OnyxFolio 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.

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

Title resolution order

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

1. Frontmatter title
2. First # H1 heading in the note body
3. 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

OnyxFolio 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

OnyxFolio parses date and updated in any of these formats:

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.

See also

• Post Types — how type: homepage, type: listing, and type: book work
• Publishing and Privacy — the website: true flag and private notes
• Navigation — menu_order and nav pinning
• SEO and Metadata — banner images, author, OpenGraph