How do I have so many partners??
1# polymap
2
3Generate interactive polycule relationship maps from a YAML config file.
4
5Outputs a self-contained interactive HTML page, an embeddable JS snippet, a static SVG, and a PNG image.
6
7## Requirements
8
9- Node.js 18+
10
11## Setup
12
13```bash
14npm install
15npm run build
16```
17
18## Usage
19
20```bash
21node dist/cli.js generate <input.yaml> [options]
22```
23
24### Options
25
26| Flag | Default | Description |
27|---|---|---|
28| `-o, --output <dir>` | `.` | Output directory |
29| `-f, --format <list>` | `html,svg,png` | Comma-separated formats to generate |
30| `-n, --name <prefix>` | input filename | Output filename prefix |
31| `--width <px>` | `1400` | PNG output width in pixels |
32| `--title <title>` | `Polycule Map` | HTML page title |
33| `--legend` | off | Render relationship legend on SVG/PNG exports |
34| `--no-labels` | on | Hide edge label text on SVG/PNG exports |
35| `--no-names` | on | Hide node name labels on SVG/PNG exports |
36
37### Examples
38
39```bash
40# Generate all formats
41node dist/cli.js generate polycule.yaml --output ./out
42
43# HTML only, custom name
44node dist/cli.js generate polycule.yaml --output ./out --format html --name my-polycule
45
46# PNG only, higher resolution
47node dist/cli.js generate polycule.yaml --output ./out --format png --width 2400
48```
49
50## Config file format
51
52```yaml
53settings:
54 theme: dark # dark | light
55 nodeScale: uniform # uniform | connections (scales node size by number of relationships)
56 mainNode: alice # optional — this person is placed at the centre of the graph
57
58people:
59 - id: alice # unique identifier used in relationships
60 name: Alice # display name
61 pronouns: she/her # optional
62 photo: "https://example.com/alice.jpg" # optional, URL to profile picture
63 color: "#e91e8c" # optional, overrides auto-assigned colour
64 links:
65 - label: Instagram
66 url: "https://instagram.com/alice"
67 - label: Website
68 url: "https://alice.me"
69
70relationships:
71 - from: alice
72 to: bob
73 type: partner
74 label: "since 2021" # optional, overrides the default type label on the edge
75```
76
77### Relationship types
78
79| Type | Line style |
80|---|---|
81| `primary_partner` | Solid thick, gold |
82| `partner` | Solid, pink |
83| `nesting_partner` | Double line, red |
84| `anchor_partner` | Dashed thick, dark red |
85| `fwb` | Dashed, purple |
86| `casual` | Dotted, cyan |
87| `queerplatonic` | Dash-dot, teal |
88| `comet` | Long dash, grey |
89| `friend` | Solid thin, light blue |
90| `metamour` | Faint dotted, dark grey |
91| `tbd` | Dash-dot, grey |
92
93## Embedding in a website
94
95Two files are generated for the `html` format:
96
97**Standalone page** (`polycule.html`) — open directly in a browser or host as-is. Can also be embedded via `<iframe>`.
98
99**Embed script** (`polycule-embed.js`) — drop into any existing page:
100
101```html
102<div id="polymap-root" style="width: 100%; height: 600px;"></div>
103<script src="polycule-embed.js"></script>
104```
105
106No framework required. Works in any HTML page.
107
108## Interactive controls
109
110- **Drag** a node to reposition it (pins in place)
111- **Double-click** a pinned node to release it back into the simulation
112- **Scroll / pinch** to zoom
113- **Click and drag** the background to pan
114- **Click** a node to open an info panel with name, pronouns, and links
115- **☀ Light / ☾ Dark** button — toggle theme
116- **Legend** button — show/hide relationship type key
117- **Labels On/Off** button — toggle edge label text
118- **Names On/Off** button — toggle node name labels
119- **⊡ Fit** button — fit the whole graph into view
120
121## Development
122
123```bash
124# Run CLI directly without building (requires tsx)
125npx tsx src/cli.ts generate example.yaml --output ./out
126
127# Rebuild client bundle only (after editing src/client/graph.ts)
128npm run build:client
129
130# Rebuild CLI only (after editing anything except src/client/)
131npm run build:cli
132```