Configuration
Settings live in two places. A board keeps its own settings in a config mapping in the board’s index.md. Each Mac also has one config document of its own, which sets defaults for every board opened on that Mac.
---schema: 1title: Docs Pipelineconfig: show-card-body: 3 due-soon: 2 show-trash: true logging: {level: info, retain: 30}---Board settings
Section titled “Board settings”| Key | Type | Description |
|---|---|---|
show-card-body | integer | How many lines of each card's first paragraph appear on its face: 0 (off, the default) or 2 to 5. Other values are moved into that set. A body that opens with a heading, list, quote, code fence, table or raw HTML shows no preview. |
due-soon | integer | How many days ahead a card's due date counts as due soon and wears the amber chip. The default is 1 (today and tomorrow); 0 means today only. Overrides this Mac's value. |
labels | list of label kind definitions | The board's own label kinds, as a list of kind definitions. The built-in text kind is always available in addition to these. |
thumb-sizes | list of integers | A list of square pixel sizes offered when you embed an image, such as [200, 400]. Overrides this Mac's list; with neither set, the sizes are 200 and 400. An empty list [] offers full size only. |
short-id | text | Whether a card's face shows its short id (the first eight characters of its uuid): show, option (only while the Option key is held) or hide. If unset, this Mac's value applies, then hide. |
show-statusbar | boolean | Set to true to show a status bar along the bottom of the board window. Remove the key to hide it again; hidden is the default. |
show-trash | boolean | Set to true to show the trash as the board's last lane. Remove the key to hide it again; hidden is the default. |
move-receipts | boolean | Set to true to have the app write a move receipt, a quiet comment, on a card each time it moves to another lane. Off when absent; to turn it off, remove the key instead of writing false. |
perspective | text | Which perspective the board window shows. kanban is the only one drawn today, and any other value looks the same. Safe to leave out. |
logging | logging | The board's activity log settings: a mapping with level and retain. Each falls back separately to this Mac's value, then to the built-in default (off, 30 days). |
Edit one subkey and leave the rest alone. The app does the same, so a setting you write by hand survives every change the user makes to another one. Keys the app does not know are kept and ignored.
To turn a setting off, remove its subkey instead of writing 0 or false. When the last subkey goes, the app removes config itself. A board with no config takes every default.
Card previews
Section titled “Card previews”show-card-body previews the first paragraph of a card’s body on its face, but only when that paragraph is plain prose. A body that opens with a heading, list, quote, code fence, table or raw HTML previews nothing. That is how you keep a card’s face to its title: start the body with a heading.
Thumbnail sizes
Section titled “Thumbnail sizes”Each number in thumb-sizes is a square that an image is fitted into, never enlarged. Each size is a real file beside the attachment’s blob, so a body can embed it with ordinary Markdown. See thumbnails. Removing a size does not delete files already written. A single number reads as a one-item list, and an entry that is not a positive number is dropped.
Move receipts
Section titled “Move receipts”move-receipts: true has the app write a quiet comment on a card each time it moves to another lane. Leave the key out for the default, off. See Move receipts.
Labels
Section titled “Labels”config.labels holds the board’s label kinds. See label kind definition.
Settings for this Mac
Section titled “Settings for this Mac”The Mac’s own config document sits one level above every board and is not synced between machines. Its config mapping has the same shape as a board’s, with a few extra settings that belong to the app itself.
| Key | Type | Description |
|---|---|---|
schema | integer | Always 1. |
kind | text | config. Marks this as the Mac's config document. |
config | mapping | The mapping holding this Mac's settings. If a setting is absent, its default applies. |
| Key | Type | Description |
|---|---|---|
handle | text | The mention handle for the person using this Mac, used when matching @handle in comments. An empty string does not override anything. |
due-soon | integer | The default number of days ahead a due date counts as due soon, for boards that do not set their own. Falls to 1 if neither is set. |
thumb-sizes | list of integers | The default list of square thumbnail sizes for boards that do not set their own. The built-in default is [200, 400]. |
short-id | text | The default for showing a card's short id: show, option or hide. A board's own value overrides it; with neither set, the id is hidden. |
restore-open-boards | boolean | Whether the app reopens the boards that were open when it last quit. Absent means true. |
waiting-signpost | boolean | Whether the app announces the moment a card starts waiting on this Mac's person. Absent means true. false turns off only the announcement; the waiting mark still shows. |
return-posts-comment | boolean | Whether Return posts the comment you are writing, with Shift-Return starting a new line. Absent means true; false swaps the two. Command-Return posts either way. |
templates-repo | text | The GitHub repository the New Board Gallery reads, as https://github.com/<owner>/<repo>. Absent or unreadable means laneworkapp/lanework-templates. |
logging | logging | The default activity log settings for boards on this Mac: a mapping with level and retain. A board can override each one separately. |
What cascades to a board
Section titled “What cascades to a board”Four settings set a default that boards fall back to: due-soon, thumb-sizes, short-id and logging. A board’s own value wins wherever it is set. If neither sets one, the built-in default applies.
| Setting | Built-in default |
|---|---|
due-soon | 1 |
thumb-sizes | [200, 400] |
short-id | hide |
logging | off, kept 30 days |
To change one board, write that board’s own subkey. Edit the Mac’s config only when you are asked to.
Settings that belong to the app
Section titled “Settings that belong to the app”handle is the mention handle of the person using this Mac. restore-open-boards, templates-repo, waiting-signpost and return-posts-comment are settings of the app itself. None of them changes what a board’s files say or how they read.
Logging
Section titled “Logging”The activity log records what happens on a board, one plain-text file per UTC day, in the board’s .log/ folder. It is off unless a board’s config.logging or the Mac’s default turns it on. Never edit or commit the log.
logging: {level: info, retain: 30}| Key | Type | Description |
|---|---|---|
level | text | The log threshold: off, error, warning, info or debug, from least to most detailed. A level records its own lines and everything more severe. An unknown name reads as info. |
retain | integer | How many days of daily log files to keep. The default is 30; 0 keeps everything. A negative or unreadable value is ignored. |
level works as a threshold: a level records its own lines and everything more severe. level: warning records errors and warnings, and skips info and debug.
level and retain cascade separately. Each falls back to the Mac’s value, then to the built-in default, so a board that sets only level still inherits the Mac’s retain.
A plain value is accepted for a quick setting: logging: info means {level: info}, logging: true means {level: info}, and logging: false means {level: off}. A level name the app does not know is left as written and read as info.
The log is read once when the board opens, so a change takes effect the next time the board is opened. A board kept in iCloud Drive never logs, whatever the setting says.
Each log line reads <UTC stamp> <level> <kind> <sentence>, optionally followed by | key=value pairs. For example, grep ' card.move ' finds card moves.