Code Blocks

All code blocks must be executable. Never write illustrative/pseudo code blocks. If you’re showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves.

After writing a code block in your markdown file, you can run it by executing md-babel-py run document.md

more information on this tool is in codeblocks

Code or Docs Links

After adding a link to a doc run

doclinks document.md

Code file references

See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation.

After running doclinks, becomes:

See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation.

Symbol auto-linking

Mention a symbol on the same line to auto-link to its line number:

The `Configurable` class is defined in [`service/spec.py`](/dimos/protocol/service/spec.py#L22).

Becomes:

The `Configurable` class is defined in [`service/spec.py`](/dimos/protocol/service/spec.py#L22).

Doc-to-doc references

Use .md as the link target:

See [Configuration](/docs/usage/configuration.md) for more details.

Becomes:

See [Configuration](/docs/usage/configuration.md) for more details.

More information on this in doclinks

Pikchr

Pikchr is a diagram language from SQLite. Use it for flowcharts and architecture diagrams.

Important: Always wrap pikchr blocks in <details> tags so the source is collapsed by default on GitHub. The rendered SVG stays visible outside the fold. Code blocks (Python, etc.) should NOT be folded—they’re meant to be read.

Basic syntax

Box sizing

Use fit with percentage scaling to auto-size boxes with padding:

The pattern fit wid 170% ht 170% means: auto-size to text, then scale width by 170% and height by 170%.

For explicit sizing (when you need consistent box sizes):

Common settings

Always start with:

color = white    # text color
fill = none      # transparent box fill

Branching paths

Tip: For tree/hierarchy diagrams, prefer left-to-right layout (root on left, children branching right). This reads more naturally and avoids awkward vertical stacking.

Adding labels

Reference

Element	Syntax
Box	box "text" rad 5px wid Xin ht Yin
Arrow	arrow right 0.3in
Oval	oval "text" wid Xin ht Yin
Text	text "label" at (X, Y)
Named point	A: box ... then reference A.e, A.n, A.x, A.y

See pikchr.org/home/doc/trunk/doc/userman.md for full documentation.