note specification#
A note is a markdown file stored inside a vault. Each note carries metadata in a YAML frontmatter block and a body of regular markdown content.
file naming#
When a note is created through the daemon, its filename is derived from the title by converting it to a slug. The title is lowercased, digits are preserved, and every other character is replaced with a dash. The resulting slug becomes the filename (with .md appended) and also acts as the canonical identifier used in internal links.
For example, the title Distributed Systems Overview produces the slug distributed-systems-overview and the file distributed-systems-overview.md.
frontmatter#
Every note should begin with a YAML frontmatter block delimited by ---. The daemon parses the following fields:
| Field | Type | Description |
|---|---|---|
title | string | Human readable title of the note. |
tags | list of strings | Tags associated with the note. Used for categorization and search. |
created | string | Creation timestamp. |
updated | string | Last updated timestamp. |
date | string | Date in YYYY-MM-DD format. Populated by the template system. |
author | string | Author of the note. |
A minimal frontmatter block:
---
title: distributed systems overview
date: 2025-04-18
tags: ["distributed-systems", "fundamentals"]
---Only title is required by the daemon for indexing. The remaining fields are optional and serve organizational or display purposes in the client.
body#
The body follows the closing --- of the frontmatter. The daemon does not interpret the body content during indexing, except to extract internal links using the [[slug]] or [[slug|display text]] syntax. All other markdown formatting is passed through to the client as is.
slug as identity#
The slug serves as the unique identity of a note within the index. It is derived from the filename (stripping the .md extension) rather than from the frontmatter title. Two notes should never share the same slug within a single vault.