pengmn23/sketchnote-diagram

Sketchnote Diagram Generator (Draw with Code)

One diagram = one JSON file. scripts/render.py uses your local Google Chrome (or Microsoft Edge) to open scripts/sketchnote.html headlessly, renders the diagram according to the JSON, and takes a screenshot. All text comes from the JSON, so there will be no typos; the trade-off is that it is more structured than a generative model.

Requires: macOS built-in "Hannotate SC" and "HanziPen SC" fonts, Google Chrome, Python 3 (standard library only).

Files

Location	What it is	When to read
scripts/render.py	Command line: create, check, export, open editor	Every time
scripts/sketchnote.html, editor.js	Rendering engine and browser editor	No need to read, render.py calls them
scripts/templates/*.json	5 templates for new diagrams	--list-templates for descriptions
scripts/templates.js	Template bundle for the editor, auto-generated, do not edit manually	Run --templates after modifying templates
references/json-format.md	Full JSON field, section, icon, doodle, color name documentation, known limitations	Before editing JSON
references/style.md	Style rules: layout zones, color scheme, shape meanings, word count, what not to draw, post-export checks	First time drawing, defining node types and word count
references/editor.md	How to use the browser editor	When handing over to user for manual adjustments
assets/examples/	One 3:4 vertical, one 16:9 horizontal (JSON + PNG)	When unsure about layout, use as reference

In the commands below, R refers to the scripts/render.py of this skill (use absolute path). Place each diagram's JSON and output PNG in the user's project directory, not inside this skill.

Commands

python3 R --list-templates                          # View available templates
python3 R --new 03_02_field_order --from 1            # Create new specs/03_02_field_order.json from template 1 (specs folder in current directory)
python3 R --new cover --dir specs --output ../images/cover.png   # Specify JSON location and output PNG location
python3 R --check specs/03_02_field_order.json          # Only check layout (overlap, out-of-bounds), takes a few seconds; exit code 1 if warnings exist
python3 R specs/03_02_field_order.json --scale 1        # Export 1x small image for preview (1600×900)
python3 R specs/03_*.json                           # Export 2x full-size images (3200×1800), saved per each output
python3 R specs/xxx.json --svg                      # Also save one SVG copy
python3 R --edit specs/xxx.json                     # Open editor in Chrome, let user drag and adjust
python3 R --templates                               # Rebuild template bundle after modifying scripts/templates/

• When --new name is written as <chapter>_<figure>_<content>, it will search parent directories for <chapter>_*.md markdown notes and set output to <figure>.png in the sibling folder. If not found, output is left unset; set it before export or add --output.
• output is a relative path from the JSON file.

Workflow to Draw a Diagram

1. First decide what this diagram is about and where it will be placed in the text. Only use words from the text, do not introduce new phrasing. For diagrams with lots of text, discuss the copy with the user before writing the JSON.
2. Choose a template: --list-templates, pick the one with the closest structure (process closure, top-bottom comparison, four-step cycle, blank horizontal, 3:4 vertical), then --new to create a new JSON.
3. Edit the JSON: Follow references/json-format.md to replace text and coordinates (estimate coordinates at 1600×900, node x, y are center points). For each node's type, refer to section 5 of references/style.md:
   • input blue circle: data, ideas, inspiration, sources
   • produce orange square: produced items, actions
   • feedback green hexagon: review, reflection, summary Use the same shape for the same category within one diagram; add a legend to explain.
4. Run --check until no warnings, then export a 1x small image, actually open and inspect it: arrow directions, text overlapping, white space balance, word count compliance with section 6 of style.md. If layout is hard to tune, use --edit to let the user drag in the browser; after user saves (⌘S), export the image.
5. Export 2x full-size image, save to output.
6. Tell the user where to place it: which sentence in the text it follows, and how to embed it.

Notes

• Chinese text does not auto-wrap: use \n in JSON, or use "/" in the editor when double-clicking to edit.
• When switching between 16:9 and 3:4, element positions do not auto-convert; you must re-layout based on --check warnings.
• Attribution is off by default. If the user wants a signature, add "signature": { "text": "Signature", "x": 40, "y": 862 } in the JSON; ask the user once what to write, then reuse for subsequent diagrams.
• If you modify colors in references/style.md, update the corresponding color constants in scripts/sketchnote.html as well.