The FlowBoard File Format

A FlowBoard document is one Markdown file. You never need to look inside it to use FlowBoard, but you can: to read it in another editor, to generate a document with a script, or to fix something by hand. This page describes what FlowBoard reads and writes.

The file has two parts:

1. optional frontmatter in YAML at the top, holding document and board settings;
2. the body, where level-one headings are boards, level-two headings are columns, and * list items are cards.

A small example

---
language: en
date_time: YYYY-MM-DDTHH:mm:ss
boards:
  Novel:
    archive_column: Archive
    done_column: Finished
    ref_column: Sources
---

# Novel

## Draft

* Write the opening scene
  ::!! ::2026-08-20 ::#draft
* A longer card
  The second and following lines are indented by two spaces.
  Markdown such as **bold text** is allowed inside a card.
  ::blue ::#chapter/one

## Finished

* Character outline

## Sources

* [Reference article](https://example.com)

## Archive

Boards and columns

• A board is an unindented level-one heading: # Board name.
• A column is an unindented level-two heading after a board: ## Column name.
• Both need a space after the # characters.

Keep board names unique within a document, and column names unique within a board. Settings refer to boards and columns by name, so duplicates are ambiguous.

A column heading can end with these controls:

Control	Effect
::red, ::orange, ::yellow, ::green, ::teal, ::blue, ::purple, ::pink, ::gray	Tints the column
::count_view / ::no_count_view	Turns the column’s word and character counts on or off
::play / ::no_play	Includes or excludes the column in Play Mode

Cards

A card starts with an unindented * (asterisk and space). Lines starting with - or + don’t create cards.

Every further line of a card is indented by two spaces. Extra indentation beyond those two spaces is kept as part of the card’s text. A blank line stays inside the card only if the next line is indented as part of the card.

Card metadata

The metadata of a card goes on its last line, as :: tokens:

* Fix the ending
  Add one more beat before the reveal.
  ::!!! ::2026-08-20 ::purple ::#revision ::#chapter/three

Token	Meaning
::!, ::!!, ::!!!	Importance level 1, 2 or 3
::2026-08-20 or ::2026-08-20T14:30:00	Due date, optionally with a time
::#tag, ::#parent/child	A tag. / separates the levels of a hierarchical tag.
::red … ::gray (nine names, as for columns)	Tint
::blur, ::blur_focus, ::blur_focus_h1, ::blur_leitner	Blurs the card’s content: always, until the card is focused, everything except the first heading until focused, or in a study (Leitner) mode
::collapse	Shows the card collapsed
::count_view / ::no_count_view	Turns the card’s counts on or off
::play / ::no_play	Includes or excludes the card in Play Mode
::md, ::fnt, ::raw	Renders the card as Markdown, Fountain or plain text. Without a token, the card follows its column’s and then the document’s default.
::id:mk-…	An ID that links and embedded instances use to find the card. It’s created by FlowBoard.

Tags that define interactive stories, such as ::#type/choice or ::#vn/scene/…, are described in Story markup.

In the app you can type the short forms #tag, ! to !!!, and a date at the end of the last line. FlowBoard writes them as :: tokens when it saves. A ::word that isn’t a known token stays part of the visible text.

Tags with spaces or special characters

Quote a part of a tag that contains spaces: ::#character/"Anna Berg". Inside a quoted part, put a backslash before a quotation mark, a / or a backslash that belongs to the value. Other backslashes are kept as they are. If a quotation mark isn’t escaped, the value ends early, the tag is dropped, and the rest shows up in the card text.

IDs

Leave ::id:mk-… tokens as they are, and never give two cards the same ID. Links and embedded instances elsewhere in your documents point to them.

Groups

A group is a card marked ::group, followed by its member cards indented by four spaces:

* Research tasks ::group ::collapsed
  A note on the group itself.
    * Read the source
    * Extract quotations
      Preserve page numbers.

• Keep ::group on the group card’s first line. ::collapsed stores that the group is folded.
• Indent member cards by four spaces, and their further lines by six.
• A group ends at the next unindented card or heading.

::collapse (on a card) and ::collapsed (on a group) are different things: the first shortens a card’s preview, the second folds a group.

Content inside cards

Cards support Markdown, including GitHub-style tables, task lists and fenced code blocks. Every line still needs the card’s indentation. Text that looks like metadata inside a fenced code block stays text.

Files are embedded with double square brackets:

* Mock-up
  ![[images/screen.png|640x480]]
  ![[brief.pdf]]
  ![[interview.ogg]]

• A plain path refers to the board’s own folder inside the assets folder. A path starting with ./ refers to the top level of the assets folder instead.
• A board’s folder is boards/board-<name>/ inside the assets folder, with the board name in lowercase and dashes in place of spaces and other characters. Boards whose names differ only in ways the folder name ignores, such as Act 1 and act-1, share a folder.
• A path such as ./boards/board-act-1/photo.png points into a particular board’s folder. FlowBoard writes this form when a card moves or is copied to another board, so that it keeps showing the same file.
• |640 or |640x480 sets an image’s size.
• Supported files are images (png, jpg, jpeg, gif, webp, svg, bmp, tif, tiff, ico, avif), pdf, and audio (mp3, ogg, oga, opus, mp2, flac, wav). Opus files can be referenced but not played in the app.

Combine several files

A document can pull in other FlowBoard files when you start Play Mode or export the whole document:

## Reference

* Chapter 1
  ::#include/"chapters/chapter 01.md"

The path is relative to the file that contains the card. The card itself doesn’t appear anywhere; it only marks where the other file goes. A reference column is a good home for such cards. Included files follow the document’s own boards, in the order of their include cards. They aren’t loaded in the normal board view, in Read View, or in single-board and single-column exports.

Frontmatter

Frontmatter is optional. If present, it must start on the first line of the file. Commonly edited keys:

Key	Purpose
language	The app language for this document: en or de
date_time	Date format, built from YYYY, MM, DD, HH, mm, ss
tags	Tags suggested while typing, in addition to those already used
auto_save, auto_save_delay_ms	Autosave on or off, and its delay
backup_retention	Number of backups kept on Mac (1–100)
card_syntax	Default for cards: markdown, fountain or raw
export_prefix	Text added in front of exported file names
story_organization	What cards and acts stand for in this story: cards: scene or beat, acts: column or board. Left out when it’s the default (scenes, columns). See Story organization
boards	Settings for each board, keyed by the board’s exact name

Board settings include archive_column, done_column and ref_column for the special columns, export_included to leave a board out of full exports, and column_width, theme and typography for its appearance.

All of these can be changed in Settings, which is the safer way.

What FlowBoard changes when it saves

FlowBoard doesn’t edit the file in place. It writes the whole document again in a consistent layout. As a result:

• YAML comments and unknown frontmatter keys are removed, and default settings are written out;
• card metadata moves to the last line, in a fixed order;
• blank lines are normalized;
• anything outside the structure described above, such as loose paragraphs between columns or lists with -, may be removed.

Editing a document by hand

Before you edit a document in another editor:

1. Make a copy if the file contains YAML comments or Markdown outside the FlowBoard structure.
2. Keep the frontmatter’s opening --- on the first line, and make sure the YAML is valid.
3. Use # for boards, ## for columns and * for cards.
4. Indent card lines by two spaces, and group members by four (their further lines by six).
5. Put metadata on the card’s last line as :: tokens.
6. When you rename a board or column, also rename it where the frontmatter refers to it.
7. Keep every ::id:mk-… unchanged and unique.
8. Put examples that look like metadata inside a code block. Otherwise they become metadata.
9. Expect FlowBoard to reformat the file the first time it saves.

If a document is open in FlowBoard while you edit the file, see When the file changes elsewhere.