4 Authoring Babqua documents

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

4.1 Where options can go

Babqua reads block-level options from four places:

Fence attribute — on the opening line of a code block, e.g. ```{.clojure .bb echo=false}.
#| cell directive — Quarto’s #| key: value syntax at the top of the block. Babqua parses these and applies them as if they’d been written on the fence, then strips them from the source:
Document frontmatter — under a top-level babqua: key, for doc-wide defaults. Only some options support this.
:kindly/options metadata — on the value, for layout options that library functions can attach via with-meta / vary-meta.

For options that accept more than one source, the highest-priority source wins, falling back to the built-in default. The per-option tables below note where each can go.

4.2 Display: echo, eval

Quarto-standard. Set via fence attribute or #| directive.

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

See the Quarto documentation on code cells for the full set of standard attributes.

4.3 Renderer override: output=

output= 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, output= wins. The fence attribute is the more explicit, local signal — treating it as an override matches Quarto’s own pattern of per-block attributes taking precedence over document-level defaults.

This is also the escape hatch for inspecting a value that’s tagged for chart rendering: output=html shows the JSON spec; output=hidden suppresses the cell entirely.

4.4 Babqua knobs: hide-stdout, width, height

Option	Type	Default	Where
`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.

hide-stdout is an evaluation/runtime concern; width and height are layout concerns, which is why they additionally read from :kindly/options — library functions can attach sizing to a value without the caller having to set it.

Fence example:

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

```{.clojure .bb 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"}}
```

Frontmatter default for hide-stdout:

---
filters:
  - bb
babqua:
  hide-stdout: true
---

:kindly/options metadata for sizing:

^{: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"}}

4.5 Combining with other filters

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

filters:
  - bb
  - some-other-filter

4.6 Document-level Quarto features

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

4.6.1 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 — Babqua 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$.

4.6.2 Other Quarto features

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