No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 18:18:29 +01:00
cuddly add support for KDL 2.0 (upgrade kde-py) 2026-11-16 18:18:28 +01:00
samples update 2026-08-20 00:08:45 +02:00
.envrc add .envrc 2025-09-30 18:23:13 +02:00
.gitignore update .gitignore (remove useless stuff, add .pdf and .html files) 2026-11-16 18:18:29 +01:00
LICENSE Initial commit 2024-02-17 16:19:46 +01:00
pyproject.toml add support for KDL 2.0 (upgrade kde-py) 2026-11-16 18:18:28 +01:00
README.md update and improve documentation 2026-11-16 18:18:29 +01:00

Cuddly

Generate HTML and PDF files, with HTML and Jinja templates, from KDL structured data.

Installation

git clone https://git.bksp.space/hannaeko/cuddly
cd cuddly
python -m venv env
env/bin/pip install .

Basic Usage

Example

Generating a PDF:

env/bin/cuddly --template samples/cv/cv.template.html --input samples/cv.kdl --output samples/cv.pdf

Generating a HTML file

env/bin/cuddly --template samples/cv/cv.template.html --input samples/cv.kdl --output samples/cv.html

Generating both at the same time, with short options:

env/bin/cuddly -t samples/cv/cv.template.html -i samples/cv.kdl -o samples/cv.pdf -o samples/cv.html

Samples

  • samples/cv/cv.template.html: Template to generate a CV, see samples/cv.kdl for the input data.
  • samples/facture/facture.template.html: Template to generate a French invoice, see samples/facture.kdl for the input data.

Template usage

The source template need to be a single HTML template file.

  • The template language is Jinja.
  • For PDFs, the resulting HTML is run through Weasyprint.
  • The data language is KDL (2.0.0).

Base URL

When generating a PDF, the base URL is set to the source template directory. All relative links to other resources (for example CSS and images) must be relative to that directory.

Accessing nodes values and attributes

Nodes are available as global variables in the template. The rendered value of a node is the first value that has been assigned to the node. This value can also be accessed using the value property. The list of values can be accessed using the values property.

my_node "something" "other thing"
{{ my_node }}
{{ my_node.value }}
{{ my_node.values | join(', ')}}

renders to

something
something
something, other thing

Attributes of a node can be accessed through the attributes property:

my_node version=42 "something"
{{ my_node.attributes.version }}

renders to

42

Accessing children nodes

Children nodes can be accessed using the children names.

my_node {
    other_node "test"
}
{{ my_node.other_node.value }}

renders to

test

If a node has multiple children of a same node type, you’ll need to use a loop (directly accessing the children properties will fail). Note that, on the other hand, looping on the children always work, even if there is only one child of the given type.

my_node {
    other_node "first"
    other_node "second"
}
{% for node in my_node.other_node %}
{{ node.value }}
{% endfor %}

renders to

first
second

Using components to template nodes

You can define node specific templates inside the components tag in the HTML template file. Nodes can then be rendered using those micro-templates using the render filter.

The context of the micro-template is the node being rendered. As such, children and properties (value, values, attributes) of that node are in the global scope.

menu "Midnight meal" price="10 €" {
    dish name="Tomato soup" "Fancy tomato soup with a slice of bread"
    dish name="Banana bread" "Amazing banana bread with a scoop of icecream"
}
<!DOCTYPE html>
<html lang="{{ lang }}">
<head>
    <meta charset="UTF-8">
</head>
<components>
    <menu>
        <h1>{{ value }}</h1>
        <dl>
            <dt>Price</dt>
            <dd>{{ attributes.price }}</dd>
        </dl>

        <dl>
        {% for dish in dish %}
            {{ dish | render }}
        {% endfor %}
        </dl>
    </menu>
    <dish>
        <div>
            <dt>{{ attributes.name }}</dt>
            <dd>{{ value }}</dd>
        </div>
    </dish>
</components>
<body>
    {{ menu | render }}
</body>