Plank markup

Plank is the markup you write in. It stays out of the way: ordinary prose is ordinary text, emphasis is plain markdown, and directives are visible tokens — tinted in the editor, never hidden behind WYSIWYG. Your leaf remains a readable text file in any editor on earth.

The whole grammar, four rules

@name{...} INLINE @sc{USS ENTERPRISE} H@sub{2}O @name ... @end BLOCK @quote … @end quote @name arg key="val" ARGUMENTS one positional, then key="value" pairs \@ \* \{ ESCAPES literal @, asterisk, brace Braces mean inline. @end means block. That is the whole grammar.

Markdown you already know passes through untouched: *emphasis*, **strong**, ~~struck~~, - lists. One sentence per line is the house style — it makes revision diffs readable.

Two tiers — and the rule that prevents a whole class of bugs

Structural markup is emitted, never typed. @chapter, @part, @titlepage and their kin come from the spine and the frames at render time. If they could also be typed in prose, the book's structure would exist in two places, and nothing could principledly decide which wins. So typing one is an error, not a warning — the question cannot arise.

Refused in prose: book · part · chapter · section · prologue · epilogue · contents · titlepage · copyright · dedication · preface · foreword · acknowledgments · appendix · glossary · scene. (A leaf is the scene — the boundary is the file, so even @scene has nothing to say.)

Tier 2 · Inline — yours

@sc{…}	small caps
@u{…}	underline
@sup{…} · @sub{…}	superscript · subscript (H@sub{2}O)
@think{…}	interior monologue — renders italic, but is semantically distinct from emphasis, which matters for POV checking
@note{…}	a printed footnote
@redact{…}	redacted on the page: ████████
@lang fr{…}	foreign-language span — correct hyphenation and metadata
@ref{e-kael}	renders as its text only — makes the reference index exact instead of guessed
@fact{…}	renders as its text only — an explicit canon assertion the Ledger extractor takes verbatim

Tier 2 · Blocks — yours

@quote … @end quote	block quotation · takes credit="…"
@epigraph … @end	chapter/book epigraph · takes credit="…"
@verse · @song	poetry and lyrics — line breaks preserved
@letter · @journal · @email · @chat · @transcript	inset documents, each styled by kind (@journal takes date="…")
@terminal	computer output — monospace, preformatted
@document type="…"	any other embedded document
@signature	a signature block
@center · @right	aligned text
@cut … @end cut	author-only: prose you removed but will not throw away — renders as nothing, stays in the file, greyed in the editor. Every tool without this grows a "graveyard" file.

Tier 2 · One-liners

@break	a scene break within the leaf — renders as the volume's scene-break style (* * *)
@dateline · @location · @time	place and time headings, small caps
@theend	the optional end-of-book marker

plank fmt — bare @end is legal to type

You may close any block with a bare @end; formatting expands it to the named form so nesting is unambiguous in the stored file and diffs stay clean. This runs automatically on every check-in, or by hand:

before after `keel plank fmt s-0001` @letter @letter @verse @verse line one line one @end @end verse @end @end letter

plank strip — clean CommonMark on demand

The promise "your book is a folder of markdown" is kept honest by strip: inline directives collapse to their text, block markers vanish (interiors stay), @cut interiors disappear entirely, @break becomes * * *, escapes unescape. This is also what the EPUB/DOCX exports feed to pandoc.

He thought @think{never} again. He thought never again. @quote kept words kept words ──► * * * @end quote tail @break @cut gone forever @end cut tail

The gate at check-in

A leaf with Plank errors cannot land — the check-in is refused with each problem named, your working file untouched, the lock still yours. Unknown directives are warnings (printed, allowed); broken structure and structural markup are errors:

$ keel ci s-0001 -m "broken" keel: Plank errors in s-0001 — fix before check-in: @quote is never closed — add `@end quote` $ keel ci s-0001 -m "structural" keel: Plank errors in s-0001 — fix before check-in: @chapter is structural — it is emitted from the spine at render time and never typed in prose

keel plank check s-0001 runs the same analysis any time, against your working file if the leaf is checked out, otherwise against the stored head.