Skip to content
Documentation

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; false is 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 title but an H1 at the top: the heading becomes the title and 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