4 Authoring Jank documents

The previous chapter (Kindly kinds) covered how to control the rendering of a value. This chapter covers the knobs around .jank blocks — display attributes (echo, eval), Janqua’s output= override, per-block options (timing, sizing, output suppression) — and finishes with the document-level Quarto features (math, callouts) that pair with live evaluation.

4.1 Code block attributes

The Quarto-standard echo and eval attributes go on the code-block fence (the opening line of a code block, e.g. ```{.clojure .jank echo=false}):

Attribute	Effect
`echo=false`	Hide the source code, show only the result
`eval=false`	Show code without evaluating it

Only the rendered HTML appears — no source code shown

Janqua also recognizes an output= attribute that picks a renderer when the value isn’t tagged with Kindly metadata:

Attribute	Effect
`output=html`	Render the value as raw HTML
`output=markdown`	Parse the value as markdown
`output=hidden`	Suppress both source and result

When both :kindly/kind metadata on the value and output= on the fence are set, the Kindly metadata wins.

See the Quarto documentation on code cells for more on the standard attributes.

4.2 Per-block options

These are Janqua-specific knobs — not part of the Kindly convention.

Option	Type	Default	Where to set it
`timeout`	integer (ms)	`10000`	fence, frontmatter
`hide-stdout`	boolean	`false`	fence, frontmatter
`width`	integer (px)	per chart kind	fence, `:kindly/options`
`height`	integer (px)	per chart kind	fence, `:kindly/options`

ECharts and Cytoscape default to 600 × 400 pixels because their libraries refuse to render to a size-less container. Other chart kinds (Plotly, Vega-Lite, Highcharts) auto-fit and have no built-in pixel default.

timeout and hide-stdout are evaluation/runtime concerns. They’re set on the code-block fence (the opening line of a code block) or as document-wide defaults in the frontmatter (the YAML header at the top of a .qmd file).

width and height are layout concerns, so Janqua also reads them from the value’s :kindly/options metadata. Library functions can attach chart dimensions via with-meta so callers don’t have to.

For each option, the highest-priority source that sets it wins, falling back through the others to the built-in default.

4.2.1 Fence attribute

Set on the opening line of a code block. All four options work here:

```{.clojure .jank timeout=30000 hide-stdout=true}
(do (println "noisy debug")
    42)
```

```{.clojure .jank width=400 height=250}
^:kind/plotly
{:data [{:x [1 2 3 4 5] :y [4 1 5 3 2] :type "bar"}]
 :layout {:title "Sized 400×250"}}
```

4.2.2 Frontmatter (`timeout` and `hide-stdout` only)

Doc-wide defaults for timeout and hide-stdout go in the YAML header:

---
filters:
  - jank
jank:
  timeout: 30000
  hide-stdout: true
---

width and height aren’t read from frontmatter — set them per block via the fence or via :kindly/options.

4.2.3 `:kindly/options` (`width` and `height` only)

Annotate the value’s metadata under :kindly/options:

^{:kindly/kind :kind/plotly
  :kindly/options {:width 800 :height 500}}
{:data [{:x [1 2 3] :y [10 20 15] :type "bar"}]
 :layout {:title "Sized via :kindly/options"}}

Library functions can attach these via with-meta / vary-meta, so callers don’t need to set them at the call site.

4.3 Combining with other filters

If you list more than one filter in filters:, put jank first — Janqua needs the .jank class to still be on the block when it runs:

filters:
  - jank
  - some-other-filter

4.4 Document-level Quarto features

Quarto’s authoring features apply to a .qmd file the same way they would in any Quarto document — Janqua only intervenes for .jank code blocks. A few worth knowing:

Math. Quarto recognizes LaTeX math in prose: write $\sqrt{x^2 + y^2}$ for inline math like $\sqrt{x^2 + y^2}$, or $$ ... $$ for a display equation:

\[\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}\]

The same Quarto pipeline handles math returned from ^:kind/md — Janqua emits the markdown string into Pandoc’s AST and Quarto then processes the math:

^:kind/md
["The area of a circle is $A = \\pi r^2$."]

The area of a circle is $A = \pi r^2$.

Callouts, frontmatter (title, theme, format options), cross-references, and citations are all standard Quarto. See the Quarto authoring guide for the full set.