Frontmatter Parameters
updated
Format
YAML between --- markers, as the first block of the file, UTF-8.
---
alias: my-document
title: My Document
---
Document body content...
Keys not listed below are left untouched on pull and ignored on push. If you keep your own metadata in frontmatter, pick names unlikely to become product fields later — a key that becomes recognised starts being managed by pull.
Fields
| Field | Type | Required | Default | Values |
|---|---|---|---|---|
title |
string | yes (for publish) | — | Any text |
alias |
string | yes (for publish) | — | kebab-case, unique within project |
parentAlias |
string | no | — | Alias of an existing document (parent_alias also accepted) |
order |
int | no | — | 0-based position among siblings — see Order below |
workflow |
string | no | published |
draft | published |
visibility |
string | no | visible |
visible | hidden |
exposure |
string | no | inherit |
inherit | private | unlisted | public |
template |
string | no | — | Document Types alias — see Templates below |
archived |
bool | no | — | true | false — see Archiving below |
replacedBy |
string | no | — | Alias of the successor document (same project) |
fields |
map | no | — | Custom field values — see Custom fields below |
Archiving
| In the file | On push |
|---|---|
| key absent | leaves the archive state unchanged |
archived: false |
restores the document |
archived: true |
archives the document |
An absent key never un-archives a document, so files pulled before something was archived in the web stay safe. replacedBy works the same way: absent leaves it alone, an empty value clears it.
Archiving through a pushed file applies to that document only. meldoc archive and meldoc unarchive change the state on the server like the web does — including descendants — and update the local file. See Command Reference.
Archived documents are not deleted by prune; restore one first if you want to delete it from the CLI.
Templates
template: assigns a Document Types by alias, which decides which custom fields apply.
---
alias: pricing-rework
title: Pricing rework
template: adr
---
| In the file | On push |
|---|---|
| key absent | leaves the assignment unchanged |
template: adr |
assigns adr |
template: "" |
removes the type |
template: with no value |
leaves the assignment unchanged, with a warning |
An unknown alias produces a warning and keeps the document’s current type. meldoc templates list and meldoc templates show <alias> browse the project’s types; meldoc new --template <alias> writes the key.
Custom fields
Values for the project’s Custom Fields live under fields:, keyed by field key:
---
alias: payments-service
title: Payments Service
fields:
status: in-review
owner: platform-team
reviewed: false
tags:
- billing
- backend
---
- Values are typed per the field: string, number, boolean or list of strings.
- Empty values are omitted;
falseis a value and is written. - On pull, the block is rewritten from the server, including values for fields outside the document’s current type, so nothing is lost on a round trip. Inherited defaults are not written.
- On push, unknown keys are ignored and reported as warnings.
What pull changes
Pull keeps your frontmatter and updates only the keys Meldoc manages: title, alias, parentAlias, order, workflow, visibility, exposure, template, archived, replacedBy, and the fields: block. Every other key stays as you wrote it.
Default values are not written: workflow: published, visibility: visible, exposure: inherit and archived: false are removed from the file.
First push
- No
alias: the CLI derives one from the file name, adding the parent directory name if needed to keep it unique, and writes it to the file. - No
titlebut an H1 at the top: the heading becomes thetitleand is removed from the body.
Order
The position sent on push comes from, in order: the order field, a numeric file name prefix (01-intro.meldoc.md → 1), the last synced value, or the end of the list.
order is a position, not a sort key: siblings are numbered 0, 1, 2… without gaps, so 10, 20, 30 becomes 0, 1, 2. To insert a page, shift the siblings after it in the same change. meldoc validate warns about gaps.
Deprecated fields
id, server_version and last_sync are no longer used. meldoc validate reports them and meldoc migrate removes them.
See also: Configuration · Command Reference