Skip to content

Sketchspaces and Gists

prjctimg edited this page Aug 5, 2026 · 1 revision

Sketchspaces and Gists

Sketchspaces

A sketchspace is a directory containing a p5.json manifest that p5.nvim uses to manage a p5.js project.

Structure

my-sketch/
β”œβ”€β”€ p5.json          # Project configuration
β”œβ”€β”€ sketch.js        # Main sketch file
β”œβ”€β”€ index.html       # Generated HTML page
β”œβ”€β”€ tsconfig.json    # TypeScript configuration
β”œβ”€β”€ assets/
β”‚   β”œβ”€β”€ favicon.ico
β”‚   β”œβ”€β”€ libs/
β”‚   β”‚   β”œβ”€β”€ p5.js        # p5.js core library (version-cached)
β”‚   β”‚   └── libs.js      # Runtime library loader
β”‚   └── types/
β”‚       └── p5.d.ts      # Ambient types
└── skchbk/              # Optional: cloned gist sketches

p5.json

{
  "version": "2.3.1",
  "mode": "global",
  "libs": {},
  "includes": ["sketch.js"],
  "gist": {
    "url": "username/gistId",
    "title": "My Sketch"
  }
}
Field Description
version p5.js version to use (v2.x)
mode global or instance sketch template
libs Contributor libraries to install ({ "name": "version" })
includes Files included in Gist uploads
gist Gist metadata written on publish, used for sync

Lifecycle

flowchart LR
    A["1. Create\n:P5 create"] --> B["2. Setup\n:P5 setup"]
    B --> C["3. Develop\n:P5 server + :P5 cdp"]
    C --> D["4. Share\n:P5 gist \"desc\""]
    D --> E["5. Sync\n:P5 gist sync"]
Loading
  1. Create β€” :P5 create my-sketch scaffolds the skeleton and opens sketch.js. Prompts for global vs instance mode unless sketch.mode is set.
  2. Setup β€” :P5 setup hydrates runtime assets from ~/.cache/p5.nvim/versions or the CDN and installs libraries.
  3. Develop β€” :P5 server starts the dev server and opens the sketch; :P5 cdp opens the debugging panel.
  4. Share β€” :P5 gist "description" uploads the includes files to a public Gist and records gist.url.
  5. Sync β€” :P5 gist sync reconciles local vs remote changes.

Gists

Publish

:P5 gist "My first generative sketch"

Creates a public Gist from the project's includes files. The gist URL and title are stored back into p5.json.

Sync

:P5 gist sync

Shows a diff of local vs remote and lets you apply local changes, pull remote changes, or skip.

Edit

:P5 gist edit

Edits the Gist description or the first comment (sketch notes).

Sketchbook

A sketchbook is a local directory (skchbk/) of cloned public Gists that you can browse offline.

Command Action
:P5 skchbk Interactive β€” clone all gists or pick one
:P5 skchbk list Show locally cloned sketches and jump to one
:P5 skchbk clone Clone all public Gists from the configured user
require("p5").setup({
  sketchbook = { user = "your-github-username" },
})

Each clone preserves the gist link (p5.json β†’ gist.url) so you can sync changes back with :P5 gist sync.

Organization Tips

  • Use descriptive Gist descriptions β€” they become directory names when cloned
  • The first comment on each Gist is your sketch notes/README
  • skchbk/ is excluded from Gist uploads automatically

Clone this wiki locally