Document Metadata (Frontmatter)
Each document can carry a YAML frontmatter block (Longform/Scrivener-style manuscript metadata) at the very top of the file:
---
type: Chapter
status: draft
pov: Alex
word_count_target: 2500
tags: [action, chapter-3]
---
Open View > Metadata (or Ctrl+Shift+M) to edit these fields through a dockable form (see Dockable Tool Windows) instead of hand-editing YAML. Unlike a typical dialog, there’s no Save/Cancel step — edits apply as you type, the same way typing in the main editor does. Smaragd only ever reads/writes these five keys:
| Field | Meaning |
|---|---|
type | Free-form section type — “Chapter”, “Scene”, “Part”, or anything you want. Not tied to folder nesting. |
status | Free-form drafting status — “draft”, “revised”, “final”, or anything you want. |
pov | Point-of-view character, free text. |
word_count_target | A target word count for this document. |
tags | A list of free-form tags, edited as removable pill-style chips rather than typed YAML — click × on a chip to remove it, and type into the adjoining box to add one: a comma or Enter commits it, and an autocomplete list of every tag already used elsewhere in the project appears as you type (click a suggestion to accept it). Any #tag mentioned in the document’s body (not just this list) also shows up here as its own chip, without a × — it’s not stored in tags:, so there’s nothing for this form to remove; edit the body text to change it instead. See Tags for how these two kinds of tags combine project-wide and how to search by tag. |
Any other YAML key you’ve hand-added to the block (or that some other tool wrote) is left alone — Smaragd never round-trips the whole block through its own data model, so unrelated keys survive a save untouched — and shown read-only in an Other fields section below the form, so a custom key isn’t invisible just because there’s no dedicated row for it. The frontmatter block is stripped from the Markdown preview so it doesn’t render as a garbled paragraph.
Edits also flow the other way: hand-editing the frontmatter block directly (in the Editor, or from outside Smaragd) updates this form immediately, the same as editing through it.
The Metadata panel also shows a Word count — a live, read-only count of the open document’s body (frontmatter excluded), recomputed continuously from whatever’s currently in the editor, not just what was last saved.
The Status: and POV: rows each show a color-swatch button once that field isn’t blank — click it to assign that status/POV value a project-wide binder background color. See Binder Background Coloring for what these colors are used for and how to switch which one (if any) the Binder actually displays.
Dropdown Source Folders
By default, type/status/pov are free text — nothing stops “Scene” and “scene” and “seen” from all being typed for the same field across a project. To turn one of them into a closed dropdown instead, right-click any folder and check it under Dropdown Source for Type, Status, or POV. That folder’s direct child documents’ titles (not documents in a subfolder of it) become the dropdown’s options for that field; the Metadata panel’s Type:/Status:/POV: row switches from a text box to a dropdown automatically as soon as a field has at least one folder assigned and one document in it.
A few things worth knowing:
- Independent per field, and independent of Folder Role. Type, Status, and POV each have their own separate folder assignment — the same folder can drive more than one field, or each can point somewhere different. Checking a folder here doesn’t touch whatever Folder Role it already has (or lack of one), and doesn’t exclude it from Export — so an existing Research folder of character bios can double as the POV dropdown’s source without anything else about it changing.
- Never destroys an existing value. If a document’s
pov: Alicewas typed before you ever assigned a POV folder — or Alice’s document has since been renamed or removed from that folder — the field still shows “Alice” as-is; it just isn’t one of the clickable options until you pick something else from the dropdown. - “(none)” is always the first dropdown entry, for clearing the field.
- Not recursive: only documents placed directly inside the assigned folder count, the same limitation Templates has.