Frontmatter Schema Reference¶
Canonical reference for YAML frontmatter fields in Percypedia documents. The authoritative source is _schemas/frontmatter.schema.json.
Quick Reference¶
---
zkid: 202411281430
author: Percy
title: "Document Title"
description: "Brief summary for SEO."
date-created: 2024-11-28
date-edited: 2024-11-28
category: Theory
tags:
- theory/marxism
- politics/strategy
publish: true
status: complete
---
Field Definitions¶
Identity Fields¶
zkid¶
Zettelkasten ID. Immutable identifier in YYYYMMDDHHMM format.
Property |
Value |
|---|---|
Type |
string |
Pattern |
|
Required |
No |
zkid: 202411281430
Document Fields¶
title¶
Document title. If omitted, falls back to the first H1 heading in content.
Property |
Value |
|---|---|
Type |
string |
Min length |
1 |
Required |
No |
Consumed by |
|
description¶
Brief summary for SEO meta tags and social sharing.
Property |
Value |
|---|---|
Type |
string |
Max length |
160 characters |
Required |
No |
Timestamp Fields¶
date-created¶
Document creation date. Should be immutable after initial creation.
Property |
Value |
|---|---|
Type |
string |
Format |
|
Required |
No |
date-edited¶
Last modification date. Update on each revision.
Property |
Value |
|---|---|
Type |
string |
Format |
|
Required |
No |
Publication Fields¶
publish¶
Controls build inclusion. Documents with publish: false are excluded from the Sphinx build entirely.
Property |
Value |
|---|---|
Type |
boolean |
Default |
true |
Required |
No |
Consumed by |
|
publish: false # Draft, excluded from build
publish: true # Published, included in build
# (omitted) # Defaults to published
status¶
Editorial workflow status. More granular than publish for tracking document maturity.
Property |
Value |
|---|---|
Type |
enum |
Values |
|
Default |
draft |
Required |
No |
Status |
Meaning |
|---|---|
|
Work in progress |
|
Needs editing/feedback |
|
Finished and stable |
Validation¶
Schema Location¶
The JSON Schema lives at _schemas/frontmatter.schema.json.
Programmatic Validation¶
From within the repository (with _extensions in PYTHONPATH):
from frontmatter_schema import validate_frontmatter, validate_file, validate_directory
from pathlib import Path
# Validate a dictionary
errors = validate_frontmatter({
'title': 'Test',
'status': 'invalid' # Will error - not a valid enum value
})
# Validate a single file
errors = validate_file(Path('docs/example.md'))
# Validate all markdown files in a directory
results = validate_directory(Path('.'))
for filepath, errors in results.items():
print(f"{filepath}: {errors}")
Use the mise tasks for validation without manual path setup:
mise run fm:validate # Validate all frontmatter
mise run fm:report # Report on frontmatter status
Running Tests¶
mise run test
Migration Notes¶
Deprecated Fields¶
These fields should no longer be used:
Old Field |
Replacement |
|---|---|
|
|
|
|
|
|
|
Remove (auto-generated) |
|
Remove (unused) |
|
Remove (unused) |
Strict Mode¶
The schema uses additionalProperties: false. Unknown fields will fail validation. Remove deprecated fields before enabling schema validation in CI.