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`](https://github.com/dimensionalOS/dimos/blob/main/dimos/protocol/service/spec.py) for the implementation.

After running doclinks, becomes:

See [`service/spec.py`](https://github.com/dimensionalOS/dimos/blob/main/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`](https://github.com/dimensionalOS/dimos/blob/main/dimos/protocol/service/spec.py#L22).

Becomes:

The `Configurable` class is defined in [`service/spec.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/protocol/service/spec.py#L22).

Doc-to-doc references¶

Use .md as the link target:

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

Becomes:

See [Configuration](../../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¶

diagram source

color = white
fill = none

A: box "Step 1" rad 5px fit wid 170% ht 170%
arrow right 0.3in
B: box "Step 2" rad 5px fit wid 170% ht 170%
arrow right 0.3in
C: box "Step 3" rad 5px fit wid 170% ht 170%

Box sizing¶

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

diagram source

color = white
fill = none

# fit wid 170% ht 170% = auto-size + padding
A: box "short" rad 5px fit wid 170% ht 170%
arrow right 0.3in
B: box ".subscribe()" rad 5px fit wid 170% ht 170%
arrow right 0.3in
C: box "two lines" "of text" rad 5px fit wid 170% ht 170%

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):

diagram source

color = white
fill = none

A: box "Step 1" rad 5px fit wid 170% ht 170%
arrow right 0.3in
B: box "Step 2" rad 5px fit wid 170% ht 170%

Common settings¶

Always start with:

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

Branching paths¶

diagram source

color = white
fill = none

A: box "Input" rad 5px fit wid 170% ht 170%
arrow
B: box "Process" rad 5px fit wid 170% ht 170%

# Branch up
arrow from B.e right 0.3in then up 0.35in then right 0.3in
C: box "Path A" rad 5px fit wid 170% ht 170%

# Branch down
arrow from B.e right 0.3in then down 0.35in then right 0.3in
D: box "Path B" rad 5px fit wid 170% ht 170%

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¶

diagram source

color = white
fill = none

A: box "Box" rad 5px fit wid 170% ht 170%
text "label below" at (A.x, A.y - 0.4in)

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.