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 output= override, per-block options (output suppression, sizing) — 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 .bb 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

Babqua 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, 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.

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

4.2 Quarto cell directives

Quarto’s #| key: value syntax also works at the top of a .bb block. Babqua parses the directives, applies them as if they’d been written on the fence, and strips them from the source before evaluation:

4.3 Per-block options

These are Babqua-specific knobs.

Option	Type	Default	Where to set it
`hide-stdout`	boolean	`false`	fence, frontmatter, `#\|` directive
`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 and Babqua also reads them from the value’s :kindly/options metadata.

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

4.3.1 Fence attribute

Set on the opening line of a code block:

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

4.3.2 Frontmatter (`hide-stdout` only)

Doc-wide default for hide-stdout goes in the YAML header:

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

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

4.3.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.4 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.5 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.5.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.5.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.