Shtuk Format
Blocks · Principles · Decisions · Layout · Cases · Fallback strategies
Shtuk Format is a superset of OKF v0.2: a folder of Markdown files with YAML frontmatter, readable anywhere, owned by the person. Everything the product adds is an ordinary file in that folder. An OKF bundle is a valid Shtuk bundle; a Shtuk bundle opens anywhere Markdown opens, and degrades honestly where a construct is ours alone.
Data specification
Where everything lives
Blocks — one record is one block kind: its syntax on disk, its attributes, its tier, the surfaces it appears on and its fallback class. A block absent here does not exist.
Shapes — one record is one pattern recognised in ordinary Markdown and drawn a particular way. It never changes what the file says. No shape is written yet.
Principles — one record is one short rule the rest is derived from. When two pages disagree, the principle decides which one is the bug.
Decisions — one record is one dated, binding ruling with its reason. State: binding, open or superseded.
flowchart TD
P["Principles"] --> D["Decisions"]
D --> B["Blocks"]
D --> S["Shapes"]
D --> G["Rule pages"]
B --> F["Fallback class"]
G --> C["Cases"]Rule pages
Fallback strategies — how every block looks outside the product, and the five classes a block must choose from.
Layout — each document owns its sibling folder; collection declarations stand next to their records.
Widget and sidebar blocks — the one declaration of the block-as-link reading.
Dynamic blocks — labelled blocks found anywhere and gathered into tables.
Cross-project links — aliases, @proj/path, and project identity.
HTML files — viewable HTML documents in the bundle: naming, view modes, the sandbox, never edited.
Исправление 23 октября — пять задач вечера: три бага приложения, ряд статистики и шапка поверх обложки.
Cases — declared behaviours for every boundary situation.
Rules for this project
Start with the principles when you want the why. Open a block's page when you need exact syntax. A decision explains a change; a shape explains a drawing that no syntax declares.
One rule, one owner. A rule is written on exactly one page. Other pages link to it and do not restate it.
Decisions are never edited into silence. A superseded decision stays, struck through, with the date and its successor.
A situation not declared is undecided. The product refuses it plainly and never guesses. New boundary situations go to Cases.
index.md is the one entry point. Authored, never generated; every other page is reached from here.
Reading a block record
Tier: native, rich, directive or envelope — how much of the product a reader needs to understand it.
Surfaces: page, sidebar, widget — where the block may stand.
Fallback: native, readable, literal, code or invisible — what a reader that does not know the block shows.
State: settled, draft or open — how final the block's definition is.
flowchart LR
W["Authored Markdown"] --> R["Product reader"]
W --> O["Any other reader"]
R --> X["Full block"]
O --> Y["Fallback class"]