File Format Reference

For a tutorial introduction, see Guides: File Format.

Formats

Extension	Parser	Block delimiter
`.txt`	`dotkit_txt_parser`	`---` on its own line
`.md`	`dotkit_md_parser`	`##` H2 heading
`.sh`	none (sourced directly)	N/A

Both parsers emit identical shell. Choose based on preference.

.txt block structure

<block>
---
<block>
---
<block>

--- separator required between blocks; optional at start/end of file
First non-blank, non-comment line sets block type
Comment lines: start with # (optionally indented)
Blank lines: preserved in shell/try bodies; skipped in map data

.md block structure

## <verb>

- <first bullet>
- <subsequent bullets>

Only ## H2 headers open blocks
Only top-level bullets (- , not indented) are parsed
Everything else (H1, H3+, prose, nested bullets, blockquotes) is ignored (treated as comments/documentation)
**word** in map templates → {{word}}
[label](url) links → bare url

Block types

shell / run

Default type. Content passed through as-is.

.txt: any block whose first content line doesn’t start with try, map, or ask. .md: ## run or any unrecognized ## heading.

try

try <check-command>
<body line 1>
<body line 2>

Compiles to:

<check-command> || {
    <body line 1>
    <body line 2>
}

Body runs only if check exits non-zero.

map

map <template>
<data row 1>
<data row 2>

Compiles to:

dotkit map '<template>' <<'DOTKIT_BODY'
<data row 1>
<data row 2>
DOTKIT_BODY

Substitution rules

Data rows split on = (space-equals-space) into fields:

Placeholder	Alias	Field
`{{1}}`	`{{item}}`, `{{key}}`	First
`{{2}}`	`{{value}}`	Second
`{{3}}`	N/A	Third

Single-field rows (no =) fill {{1}}/{{item}}/{{key}} only.

In .md, **word** in the template line maps to {{word}}.

ask

Three variants:

Form	Behavior
`ask <message>` (no body)	Print message, wait for Enter
`ask <message>` (with body)	Yes/no prompt. Body runs if yes.
`ask $VAR <message>`	Hidden input captured into `$VAR`

Input is read from /dev/tty. Hidden input uses stty -echo.

Generated script header

Both parsers emit this header:

#!/bin/sh
set -eu
. "${DOTKIT_FUNCS:-$HOME/.local/bin/dotkit/dotkit_funcs}"

set -eu is active: unset variables and failing commands abort the script unless explicitly handled.

dotkit_funcs availability

In parsed scripts, dotkit is a shell function (from dotkit_funcs), not the binary. This means state changes, exported variables, shellenv sourcing, persist into subsequent lines of the same script.

dotkit run and dotkit apply set DOTKIT_FUNCS automatically. In standalone use, set it manually or rely on the default path.