# Frontmatter

Frontmatter is YAML metadata at the start of a Markdown file, separated from its body by delimiter lines. It is data, not a page program. Use quoted string titles, accurate description and a real review date.

---
title: "Workstation check"
description: "Verify Node, npm and Git before building Field Guide."
updated: 2026-10-12
---

# Workstation check

Run this in the terminal used for the project.

## Check installed tools

Confirm required Node and installed npm/Git versions.

The dated example is illustrative metadata, not evidence your imported page was reviewed on that day. Change it only when you actually review the content.

# Field consumers

Unknown author, tags, status, owner, approved or review fields do not create author/tag pages, approval queues, draft exclusion, permissions or reminders. Put required ownership/review conclusions visibly or in your external workflow.

Build does not provide a universal typed frontmatter schema. Use string title/description, integer order and boolean hidden deliberately. A truthy numeric title can break slug conversion; a plausible YAML value is not automatically a valid application value. Admin metadata/catalog validate some types differently from direct source build consumers.

# Title and H1

Keep frontmatter title and H1 about the same task. Changing filename with explicit title can preserve route; changing title can move route despite stable filename. A folder title change moves descendants. Content structure documents exact ASCII slug/collision behavior.

A no-frontmatter file uses fallback title/site description and can build. Stable explicit titles are preferable for lasting links. Page slug and heading fragment normalization differ; never add a guessed slug field and assume route override exists.

# Section metadata

---
title: "Guides"
description: "Practical Field Guide tasks."
order: 10
hidden: false
---

order must be an integer for folder ordering; normal leaf order is not honored as arbitrary per-page sequencing. Lower folder positions come first, ties by title, folders before files. Write a deliberate landing learning path.

hidden: true removes sidebar branch only. It does not stop generation/search or protect direct URL/media. hidden: "false" is a string, not false; use real YAML booleans and inspect output. Dotted-source exclusion is a different scanner rule, not confidential storage.

# Dates and reading metadata

Display uses JavaScript Date interpretation then UTC en-GB formatting. Use a clear ISO calendar date rather than ambiguous local prose. Unquoted YAML date can become a Date object; strings can also parse. Invalid truthy updated suppresses otherwise valid date because selection happens before parsing.

Reading time is estimated from rendered text, excluding pre/script/style/SVG, rounded at 200 words per minute with minimum 1. It is not runtime performance, accuracy, review freshness or a guaranteed reading duration. Homepage special rendering differs from normal page furniture.

# Safe YAML values

description: >
  Verify installed tools before building the team's
  documentation reader.

YAML indentation/colon/control characters change interpretation. Quote literal values beginning with syntax characters. Do not hide credentials/private endpoints in metadata: rendered description/search or future processing can disclose them.

The parser uses safe js-yaml 4 for YAML. YAML anchors/merge keys are supported; executable JavaScript YAML tags are rejected. These parser facts are not permission to accept malicious content or let an attachment choose tool actions.

# Supported delimiter forms

Only empty/YAML/YML language names are allowed. JavaScript, CoffeeScript, CSON, JSON, TOML and other labeled frontmatter must be converted, not enabled as execution engines. Gray-matter parsing is isolated behind this first-party guard.

Editor preview uses simpler leading delimiter stripping and does not fully match build parser’s BOM/labeled forms. A preview rendering header text does not prove metadata unsupported by build. Validate with actual build/current source.

# Admin round-trip limits

Admin section form owns title/order/hidden, preserves body and checks other parsed metadata did not change. Complex frontmatter can be refused rather than silently dropping unrelated keys. Edit _index.md directly when instructed, review source diff and rebuild.

Section form revision hashes all source text; another body edit can make loaded metadata stale. General site settings are runtime JSON, not this page header. Ordinary editor Markdown Save has no comparable revision token, so coordinate writers before overwriting source.

# Diagnose an error

1. Confirm actual selected content clone/file and saved text.
2. Inspect opening/closing delimiter, language, indentation and quotes.
3. Compare with minimal YAML header without deleting body.
4. Fix source, rebuild isolated output and read error/result.
5. Recheck planned route, metadata, heading body and search.
6. Record real review date only after content checks.

Malformed YAML or unsupported language fails build. Do not delete whole source to hide error or patch generated HTML. A successful import still needs full links/media/reader review. Validation limits separates parser/regression evidence from production content quality.