By default render emits a bare HTML fragment — ready to pipe into something bigger. Passing --title or --css switches the output to a finished document: the same fragment wrapped in a minimal HTML shell. With no flags the fragment is byte-identical to what oliver rendered alone.
A bare fragment — no shell flags:
$ dogbed render share/verdict.knap -d share/verdict.json
<h1>dogbed 0.1.0 — first verdict</h1>
<p><strong>approve</strong> — the pipeline sings</p>
<h2>Blockers</h2>
<h2>Nits</h2>
<ol>
<li>ship it</li>
</ol>
--title--title wraps the fragment in the shell and sets <title>. The text is HTML-escaped for &, <, > and " — the data is untrusted:
$ dogbed render share/verdict.knap -d share/verdict.json --title 'Art & "Code" <review>' | grep '<title>'
<title>Art & "Code" <review></title>
--css--css adds a stylesheet link to the shell. Repeatable — links keep flag order — and the href passes through verbatim: URL or relative path, unvalidated. The consumer owns it.
The whole deal — one command, one finished document:
$ dogbed render share/verdict.knap -d share/verdict.json --title 'Verdict — dogbed' --css style.css
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Verdict — dogbed</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<h1>dogbed 0.1.0 — first verdict</h1>
<p><strong>approve</strong> — the pipeline sings</p>
<h2>Blockers</h2>
<h2>Nits</h2>
<ol>
<li>ship it</li>
</ol>
</body>
</html>
--profile xhtml--profile xhtml swaps the HTML5 shell for XHTML 1.0 Strict: strict doctype, an http-equiv meta instead of <meta charset> (which is invalid XHTML), self-closing <link … /> tags, and xmlns on the root element.
$ dogbed render share/verdict.knap -d share/verdict.json -p xhtml --title 'Verdict' --css style.css
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Verdict</title>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<h1>dogbed 0.1.0 — first verdict</h1>
<p><strong>approve</strong> — the pipeline sings</p>
<h2>Blockers</h2>
<h2>Nits</h2>
<ol>
<li>ship it</li>
</ol>
</body>
</html>
--max-output--max-output caps the final document — shell included. The k4o stage is bounded by the same value, so a runaway template dies early:
$ dogbed render share/verdict.knap -d share/verdict.json --title T --css style.css --max-output 250
dogbed: output (297 bytes) exceeds --max-output (250)
Dogfood finding: Textile typography eats -- in data. A JSON value containing --title renders as —title — the value flows through the Textile intermediate, and Textile converts -- to an em-dash. Surprising for CLI flags and technical content; plan around it:
$ echo '{"flag":"--title"}' | dogbed render flag.knap -d -
<p>—title</p>
Dogfood finding: backticks are not code spans. Markdown habits produce literal backticks — Textile code spans are …:
$ echo '{"t":"try `backticks` for code"}' | dogbed render note.knap -d -
<p>try `backticks` for code</p>
The fix: wrap flags in … spans — the code span protects the dashes:
$ echo '{"t":"wrap flags in @--title@ and Textile leaves them alone"}' | dogbed render note.knap -d -
<p>wrap flags in <code>--title</code> and Textile leaves them alone</p>