2 Introduction¶

2.1 What is PnPInk?¶

PnPInk is an open-source extension suite for Inkscape that turns it into a practical production environment for print-and-play components: cards, tiles, counters, boards, and player aids.

If you are new to Inkscape: Inkscape is a free, open-source vector editor based on the SVG standard. If you do not have it installed yet, you can download it for Windows, macOS, and Linux from the official website: https://inkscape.org

PnPInk works fully inside Inkscape. You design with normal SVG objects, and PnPInk handles replication, data filling, placement, and pagination automatically.

The output remains editable SVG, and you can export using Inkscape formats such as PDF, PNG, JPG, and SVG.

2.2 The core idea¶

PnPInk is built around a simple workflow:

Draw one component.
Describe variations in a dataset.
Let PnPInk generate the rest.

You start with a single visual design (a card, a tile, a token face), connect it to a dataset, and PnPInk produces as many instances as you need, placing them on pages and preparing them for printing.

You can begin with defaults. Advanced controls are optional and can be added gradually when you need more precision.

2.3 What you can do immediately¶

Without advanced syntax, you can already:

duplicate one template many times,
change texts and images per instance,
auto-fill pages,
generate multi-page output ready to export.

Everything beyond that is incremental.

2.4 First contact: template, IDs, dataset¶

2.4.1 What is a template in PnPInk?¶

A template is a normal Inkscape drawing that represents one unit to replicate: one card, one tile, one board section, and so on.

In practice, it is a group of regular SVG objects (text, rects, paths, images, groups), identified by IDs.

PnPInk uses one internal object as template bounding box (bbox) to understand:

template size,
placement reference,
replication behavior.

The bbox can be a rect or another simple shape. What matters is that its outline correctly wraps the component you want to replicate.

2.4.2 How IDs connect data to graphics¶

In PnPInk, IDs are the connection between dataset and drawing.

If a dataset column is named title and your SVG contains id="title", that object can be updated for each generated row.

Typical usage:

text IDs: dynamic text replacement,
rect IDs: image/icon anchors,
group IDs: visibility or variant control (advanced workflows).

Useful Inkscape panels:

Object > Objects... (Shift+Ctrl+O): hierarchy, groups, layers, Z-order, IDs.
Object > XML Editor (Shift+Ctrl+X): direct SVG/XML attributes.

2.5 Minimal working example¶

2.5.1 Dataset notation used in this documentation¶

To avoid confusion, this guide uses a consistent visual notation:

header cells: dataset column names (first row),
regular cells: normal data values,
first-column cells: cells in column 1 (template/page/layout control).

In dataset tables, headers and first-column cells are also color-highlighted.

2.5.2 Conceptual template structure¶

Use a basic Inkscape file named hello_word.svg.

In Inkscape, the structure can look like this:

(g) hello_word_template
 |- (rect) card_bbox        <- template bounding box
 |- (text) title
 |- (text) cost
 |- (rect) art              <- image/icon anchor
 `- (text) text

Key points:

card_bbox visually wraps the full component.
title, cost, art, and text are the objects you vary per row.

2.5.3 Dataset example¶

Spreadsheet-like table view:

card_bbox	title	cost	art	text
`{A4 b=[-5]}.L{p=4x3 g=2}`	Tomatoes	3	tomato	You win 1 tomato
	Mushrooms	5	brown-mushroom	You win 2 mushrooms
	Lemons	2	lemon	Win 1 lemon for every tomato you own

CSV text view (same data):

card_bbox,title,cost,art,text
{A4 b=[-5]}.L{p=4x3 g=2},Tomatoes,3,tomato,You win 1 tomato
,Mushrooms,5,brown-mushroom,You win 2 mushrooms
,Lemons,2,lemon,Win 1 lemon for every tomato you own

Interpretation:

The header of the first column is card_bbox.
The first-column cell {A4 b=[-5]}.L{p=4x3 g=2} sets page/layout context for this dataset block.
Empty first-column cells continue using the same template/page context.
Each row generates one component instance.
title and cost update text fields.
art provides the image source for the art anchor.
text updates the text object with id="text".

With defaults only, PnPInk places instances sequentially, fills the page, and creates additional pages automatically when needed.

2.6 A first taste of the DSL¶

Once basics work, you can start controlling page and layout with a short expression:

{A4 b=[-5]}.L{p=4x3 g=2}

At a glance:

{A4 b=[-5]}: A4 page with 5 mm inner margin at every side.
.L{p=4x3 g=2}: layout of cards in a pattern of 4x3 grid with 2 mm gap.

This short notation is part of the PnPInk DSL (Domain Language). It lets you control placement, scaling, rotations, grids, gaps, bleeds, marks, and more.

PnPInk is designed to be simple by default, and powerful when you need it.

2.7 What PnPInk can do (quick tour)¶

Even if you do not understand every syntax detail yet, this gives you a practical map of what is possible.

2.7.1 From simple repetition...¶

Build many components from one design and one dataset:

{A4}.L{3x4}

One template can be placed 12 times on an A4 page. See Layout and Page.

2.7.2 ...to data-driven variation¶

Each dataset row can produce a different result. Texts, images, icons, and properties can vary per instance. See Dataset Reference.

2.7.3 Precise layout control¶

Control spacing and sizing explicitly:

L{3x4 gaps=4 shape=poker}

See Layout.

2.7.4 Fronts and backs, automatically¶

Generate aligned duplex backs with @back:

{card_back @back}

See DSL Advanced.

2.7.5 Page-level elements¶

Place objects once per page, not once per card:

{page_title @page}

Useful for titles, page numbers, frames, or static page backgrounds. See Page.

2.7.6 Fit and Anchor (single concept)¶

Position objects relative to target rectangles without manual coordinates:

icon.F{i a=9}

The element is fitted and anchored by intent, not by absolute measurements. See Fit and Anchor.

2.7.7 Adaptive layouts¶

Let layout adapt to available space:

L{1x? gaps=?}

Items stack and spacing is computed automatically. See Layout.

2.7.8 Explicit ID arrays and slots¶

Apply layout directly to selected IDs:

[id1 id2 - id3].L{1x?}

- reserves an empty slot without rendering. See Core Syntax.

2.7.9 Slot-level alignment¶

Align content inside each layout slot:

L{1x? a=6}

See Layout and Fit and Anchor.

2.7.10 Production features¶

Generate cut marks aligned with final geometry:

.M{len=[3 2] d=2}

Marks follow real layout, spacing, bleeds, and rotations. See Marks.

Use external sources (images, PDFs, spritesheets, icon libraries), and reuse generated assets in pipelines. See Source.

2.8 A key practical advantage¶

With PnPInk you do not need to work with absolute coordinates for most production tasks.

You can express intent, for example: bring an image from a source, rotate it, fit it to a top-right anchor, scale it, and crop overflow.

If the source image changes, the same rule still works. If you switch card size (for example from poker to tarot), layout and fitting scale with the template logic, without manually re-measuring everything.

This is one of the main differences between PnPInk and many manual or coordinate-heavy workflows.