Frontmatter Reference

Every note in Ametrine starts with YAML frontmatter ¹The metadata block between --- markers. This reference documents all available fields.

What is Frontmatter?

Frontmatter is metadata at the top of markdown files:

---
title: My Note
description: A note about something interesting
tags: [topic1, topic2]
date: 2025-10-30
---

# My Note

Content goes here...

The frontmatter:

• Must be the first thing in the file
• Uses YAML syntax
• Surrounded by --- markers
• Contains key-value pairs

Required Fields

title

Type: string Required: Yes

The note’s title, displayed everywhere.

title: My First Note

Rules:

• Must be unique (for wikilink resolution)
• Used in browser tab, nav, search results
• Case-insensitive for wikilinks

Standard Fields

description

Type: string Required: No Default: Empty

Short summary of the note’s content.

description: Learn how to configure Ametrine's theme and features

Used in:

• Search results preview
• Page metadata
• Social sharing (OG description)
• SEO meta tags

Best practices:

• Keep under 160 characters
• Write for humans, not keywords
• Summarize the note’s value

date

Type: string (ISO 8601 date) Required: No Default: File creation time

When the note was created or published.

date: 2025-10-30

Supported formats:

• 2025-10-30 (recommended)
• 2025-10-30T14:30:00Z (with time)
• 2025-10-30T14:30:00-07:00 (with timezone)

Used for:

• Sorting notes
• Activity heatmap
• Timeline features
• RSS feed ordering

updated

Type: string (ISO 8601 date) Required: No Default: None

When the note was last updated.

updated: 2025-10-30

Shows in metadata as “Updated” with its own timestamp.

tags

Type: array of strings Required: No Default: Empty array

Categories or topics for the note.

tags: [concept, pkm, evergreen]

Also accepted:

tags:
  - concept
  - pkm
  - evergreen

Used for:

• Tag pages (/tags/[tag])
• Related notes algorithm
• Content organization
• Filtering and search

Best practices:

• Use lowercase
• Prefer single words
• 3-7 tags per note
• Consistent vocabulary

author

Type: string Required: No

The note’s author name.

author: Jane Doe

Displayed in metadata section if configured.

Privacy and Publishing

draft

Type: boolean Required: No Default: false

Mark note as draft (unpublished).

draft: true

Behavior depends on privatePages.mode in config:

Draft mode (default):

• Notes are public by default
• draft: true hides the note

Publish mode:

• Notes are private by default
• draft field is ignored (use publish instead)

Draft notes:

• Don’t appear in navigation
• Don’t appear in search
• Don’t generate pages
• Still tracked by git

publish

Type: boolean Required: Only in publish mode Default: false

Mark note for publishing (in publish mode).

publish: true

Only relevant when privatePages.mode: "publish" in config.

Linking and Navigation

aliases

Type: array of strings Required: No

Alternative names for wikilink resolution.

aliases: [Alt Name, Another Name, Abbreviation]

All these wikilinks resolve to the same note:

• [[My Note]]
• [[Alt Name]]
• [[Another Name]]
• [[Abbreviation]]

Use cases:

• Abbreviations: PKM → Personal Knowledge Management
• Common typos or variations
• Historical names
• Multiple languages

links

Type: array of objects Required: No Auto-generated: Yes

Internal and external links in the note.

links:
  - target: other-note
    text: Other Note
    type: internal

Usually auto-generated by Ametrine’s plugins. Don’t edit manually unless needed.

Custom Fields

Ametrine supports any custom frontmatter field! They’ll be displayed automatically with appropriate icons.

URLs

Any field ending with _url or containing a URL:

source_url: https://wikipedia.org
reference: https://github.com/repo

Displayed with Link icon and clickable.

Booleans

True/false values:

verified: true
featured: false
archived: true

Displayed with Check (✓) or X icon.

Numbers

Numeric values:

priority: 5
version: 2
rating: 8

Displayed with Hash (#) icon.

Arrays

Lists of values:

references: [Book1, Book2, Book3]
contributors: [Alice, Bob]

Displayed with List icon and comma-separated.

Dates

Any ISO date field:

completed: 2025-10-30
deadline: 2025-12-31
reviewed: 2025-10-15

Displayed with Calendar icon and formatted.

Computed Fields

Some fields are computed automatically:

readingTime

Auto-calculated reading time in minutes.

# Automatically added:
readingTime: 5

Based on:

• Word count
• Average reading speed (200 WPM)
• Rounded to nearest minute

wordCount

Total words in the note content.

# Automatically added:
wordCount: 1234

Excludes:

• Frontmatter
• Code blocks
• Image alt text

Metadata Display Configuration

Control which fields display in src/config.ts:

metadata: {
  show: true,
  dateFormat: "MMMM d, yyyy",
  fields: [
    { key: "date", label: "Published", icon: "Calendar", format: "date" },
    { key: "updated", label: "Updated", icon: "RefreshCw", format: "date" },
    { key: "author", label: "Author", icon: "User", format: "text" },
    { key: "readingTime", label: "Reading time", icon: "Clock", format: "computed" },
  ]
}

See Configuration Guide for details.

Examples

Minimal Note

---
title: Quick Thought
---

Just a quick idea...

Standard Note

---
title: Understanding Zettelkasten
description: Overview of the slip-box note-taking method
tags: [concept, pkm, zettelkasten]
date: 2025-10-30
author: Jane Doe
---

Comprehensive Note

---
title: Project Retrospective
description: Lessons learned from the website redesign project
tags: [project, retrospective, learning]
date: 2025-10-30
updated: 2025-10-31
author: Team Lead
status: completed
priority: 5
source_url: https://project-docs.com/retro
contributors: [Alice, Bob, Charlie]
verified: true
archived: false
---

Hub/MOC Note

---
title: Digital Gardening Resources
description: Central hub for all digital garden content
tags: [hub, moc, navigation]
date: 2025-10-30
aliases: [Garden Hub, DG Resources]
featured: true
---

Draft Note

---
title: Incomplete Research
description: Work in progress, not ready to publish
tags: [research, draft]
date: 2025-10-30
draft: true
---

Best Practices

Title Guidelines

• Be specific: “Configuration Guide” not “Guide”
• Use title case: “My Note” not “my note”
• Avoid dates: Use frontmatter date field instead
• Keep under 60 chars: For better display

Description Guidelines

• Write complete sentences: Not just keywords
• Focus on value: What will reader learn?
• Under 160 characters: For SEO
• No markdown: Plain text only

Tag Guidelines

• Lowercase: concept not Concept
• Single words: digital-garden not digital garden
• Consistent vocabulary: Reuse existing tags
• Limit quantity: 3-7 tags per note
• Categories not keywords: Broad topics

Date Guidelines

• Use ISO format: 2025-10-30
• Set on creation: When you first write the note
• Update updated: When making significant changes
• Be consistent: Same timezone for all notes

Troubleshooting

YAML Syntax Errors

Problem: Build fails with YAML error

Solutions:

• Check indentation (use spaces, not tabs)
• Escape special characters: title: "Note: Subtitle"
• Quote strings with colons: "https://url.com"
• Use array syntax correctly

Fields Not Showing

Problem: Custom fields don’t appear

Solutions:

• Check Configuration Guide
• Verify field is in frontmatter
• Try restarting dev server
• Check browser console for errors

Wikilinks Not Resolving

Problem: [[Note]] links don’t work

Solutions:

• Check target note has title field
• Verify spelling and capitalization
• Add alias if needed
• Check note isn’t marked draft: true

Dates Not Formatting

Problem: Dates show as raw strings

Solutions:

• Use ISO format: YYYY-MM-DD
• Set dateFormat in config
• Check field name is date or updated
• Verify date is valid

Schema Definition

Ametrine uses Astro Content Collections with Zod schema validation.

The schema is defined in src/content/config.ts:

const notesCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
    date: z.date().optional(),
    updated: z.date().optional(),
    tags: z.array(z.string()).optional(),
    author: z.string().optional(),
    draft: z.boolean().optional(),
    publish: z.boolean().optional(),
    aliases: z.array(z.string()).optional(),
    // ... more fields
  })
});

This provides:

• Type safety at build time
• Auto-completion in editors
• Runtime validation
• Clear error messages

Next Steps

• Syntax Reference - Content formatting syntax
• Configuration Guide - Site-wide settings
• Quick Start - Create your first note
• Wikilinks and Graph - Link between notes

Master frontmatter to organize your digital garden effectively!