koala-diagrams 1.2.5

Koala is a DSL and SVG compiler for structured concept diagrams.

Koala

Koala is a DSL for generating diagrams from structured text.

Write once, render in multiple layouts.

GitHub Repository Español

Quick Example

Write this:

@theme jungle

main:: 1 Biology
Study of life.

hl:: contains -> 1.1 Cell
Basic unit of life.

1.2 Genetics
Study of heredity.

Then run:

koala compile example.txt --layout tree

Result

Installation

Install from PyPI:

pip install koala-diagrams

Or with pipx:

pipx install koala-diagrams

Usage

CLI

koala compile docs/examples/tree.txt --layout tree
koala compile docs/examples/radial.txt --layout radial --theme jungle --size square
koala inspect docs/examples/tree.txt
koala validate docs/examples/radial.txt --strict

Python

import koala

file_result = koala.compile(
    "docs/examples/radial.txt",
    layout="radial",
    theme="academic",
    size="square",
)

svg_result = koala.render_text(
    """
    1 Central Topic
    Main explanation.

    1.1 First Branch
    Supporting detail.
    """,
    layout="tree",
    theme="frutal",
)

source_path = koala.save_text(
    "1 Root\nBody.\n",
    "docs/examples/inline_demo",
)

print(file_result.output_svg)
print(svg_result.svg)
print(source_path)

Library API summary:

• koala.compile(path, **config) or koala.compile_file(path, **config): source file to .svg
• koala.render_text(text, **config): Koala DSL text to in-memory SVG via result.svg
• koala.save_text(text, output, **config): raw Koala DSL text to .txt
• koala.compile_text(text, **config): legacy helper that still writes .svg to disk

RenderResult now always includes the serialized SVG in result.svg. result.output_svg is only populated when the operation writes a file.

In general, avoid embedding @show-node-numbers in document metadata. Prefer CLI flags, library arguments, or user config defaults unless a file really needs to be self-descriptive about numbering.

DSL Syntax

Koala uses a simple line-based DSL:

[kind::] [relation ->] number title

Example:

1 Main Concept
contains -> 1.1 Child Node
hl:: 1.2 Highlighted Node

• Full syntax guide
• Authoring tutorial
• Examples
• LLM prompts

Features

• Simple hierarchical DSL
• Multiple layouts (tree, radial, synoptic)
• Theme system
• CLI and Python API
• SVG output to disk or in memory

Multiple Layouts

Tree, radial, and synoptic layouts from the same source.

Philosophy

Koala is built around a simple idea:

The same source file should be able to drive multiple layouts and visual styles without rewriting the content.

License

MIT