napkin-sketchdocs 1.0.0 GitHub

Drawing with napkin script: cheatsheet#

On this page

API hub · Reference · Quickstart · Cheatsheet

Reminders for what each instruction draws: the drawing verbs, the shape library, the hand-drawn pass and evaluate.

The drawing verbs#

CategoryVerbWrittenDoes
Layerslayerlayer "<name>" [opacity <0-1>] [hidden] [locked]A drawing layer. Marks after it go on it until the next layer.
Layersgroupgroup "<name>" [opacity <0-1>] [hidden] [locked] { ... }A group layer. The layer and group lines in its block become its children.
Layersclipclip ["<name>"] { ... }A clip group: everything its block draws shows only inside the block's last closed shape, in paint order, which paints nothing while it clips - the app's Make Clipping Mask. Without a closed shape in it, the block is a plain group.
Painttooltool pen|marker|copic|pencil|eraser|brushThe kind of mark: pen (the app's Brush; brush is taken for it), marker (translucent, so overlapping passes build up like ink), copic (a broad, angled nib), pencil (a lead through the paper's grain; pencil picks one) or eraser (cuts its line's swath out of the marks drawn before it on its layer, as the app's Eraser does, and draws nothing of its own).
Paintcolorcolor <color>The ink color of every mark after it.
Paintwidthwidth <length>The stroke width of every mark after it.
Paintopacityopacity <0-1>The opacity of every mark after it, from 0 to 1.
Paintfillfill <color>
fill none
The fill color of closed shapes after it, or none.
Paintgradientgradient linear <angle> (<color> <offset>, ...)
gradient radial (<color> <offset>, ...)
gradient none
A gradient fill for closed shapes after it: linear at an angle, or radial from the centre out, or none.
Paintstrokestroke on|offTurns the outline on or off. With it off, a closed shape is its fill alone.
Paintstylestyle solid|dashed|dottedThe outline's dash: solid, dashed or dotted.
Paintprofileprofile uniform|rounded|tapered|waveHow the width runs along a brush or marker stroke: uniform, rounded, tapered or wave.
Paintnibnib <degrees>The angle of the copic nib, in degrees.
Paintpencilpencil <grade> [<color>]Takes up the Pencil at a grade: graphite alone, 9H to 9B, or charcoal (HB to 6B), compressed (2B to 6B) or vine (hard, medium, soft) and its grade. Every mark after it is drawn with that lead through the paper's grain, in its tone - or in the color given, a colored pencil. The width is the line's own; the app's softer leads draw broader at one tool width.
Paintroughrough <0-1> [passes 1|2] [overshoot <length>]
rough off
The hand-drawn pass for every mark after it: 0 is exact, 1 is clearly drawn by hand, and off is 0. Seeded, so it draws the same way every run.
Paintfontfont "<family>" [<size>]
font <size>
The font family and size of text after it.
Paintcharactercharacter [face "<face>"] [tracking <n>] [kern <n>] [kerning auto|none] [leading <length>] [spacing <n>%] [caps normal|all|small] [hscale <n>%] [vscale <n>%] [shift <length>] [rotate <degrees>] [highlight <color>] [super|sub] [underline] [strike]
character reset
The character attributes of text after it: its face, tracking, kerning, leading, word spacing, capitals, scales, baseline shift, turn and highlight, and whether it is a superscript or a subscript, underlined or struck through. reset puts every one back.
Paintparagraphparagraph [align left|center|right|justify] [indent <left> [<right>]] [first <length>] [before <length>] [after <length>] [hyphenate|nohyphenate] [list bullet|number|none] [level <n>]
paragraph reset
The paragraph attributes of text after it: its alignment, its indents, the space before and after it, whether it hyphenates, and a bulleted or numbered list at a level. reset puts every one back.
Painttextconfigtextconfig "<name>" [face "<face>"] [tracking <n>] [kerning auto|none] [leading <length>] [spacing <n>%] [caps normal|all|small] [hscale <n>%] [vscale <n>%] [shift <length>] [rotate <degrees>] [highlight <color>] [super|sub] [underline] [strike] [size <size>] [family "<family>"] [color <color>]Defines a Text Configuration, a vector editor's Character Style: a named set of character attributes the book keeps, which text follows with config and its runs with config in their clauses. What a text has of its own overrides it. Defined again under its name, it changes for every text that follows it.
Paintaccentaccent <language>A Clean Language Accent for the next text: its paragraphs are colored as a language reads them - keywords, strings, numbers, comments, names - live as the app edits them. A language by its id or a name highlight.js knows it by (a name no word spells in quotes, "c++"), auto for the one the code reads most like, or none. It waits for the next text; one nothing takes is reported.
Shapesrectrect <x> <y> <width> <height> [r <radius>]A rectangle, with rounded corners when r is given.
Shapescirclecircle <cx> <cy> <r>A circle, drawn as four cubic curves rather than a polygon.
Shapesellipseellipse <cx> <cy> <rx> <ry>An ellipse, from its centre and two radii.
Shapeslineline <x1> <y1> <x2> <y2>A straight line between two points.
Shapespolygonpolygon <x> <y>, <x> <y>, ... [r <radius>]A closed shape through a list of points, with rounded corners when r is given.
Shapespolylinepolyline <x> <y>, <x> <y>, ...An open line through a list of points.
Shapesstarstar <cx> <cy> <outer> <inner> <count>A star with the given number of points, between an outer and an inner radius.
Shapesarcarc <cx> <cy> <r> <from> <to>An open arc of a circle between two angles, in degrees clockwise from three o'clock.
Shapesspiralspiral <cx> <cy> <r> <turns>A spiral winding out from its centre to the radius over the given number of turns.
Shapesshapeshape "<name>" at <x> <y> size <width> [<height>]A named shape from the built-in library, drawn in a box from x, y. With one size its longer side is that long and it keeps its proportions; with a width and a height it is stretched to fill them.
Shapeswipewipe in|out-front|out-back|mid|outer|clean { ... }Combines the marks its block draws, as the app's Wipe Stacks do, and draws what is left in their place: in (Wipe In, their union), out-front (Subtract Top from Below: the bottom one less the rest), out-back (Subtract Below from Top: the top one less the rest), mid (Mid Wipe: where all of them overlap), outer (Outer Wipes: where an odd number overlap) or clean (Clean Wipe: every piece of their overlaps, a mark each). What is left is painted as the topmost mark, or as the bottom one for out-front; text, pictures and eraser marks in the block are passed over. The block keeps its paint and transforms to itself, as a group does, and effects written just before it go on what it leaves.
Shapesstackstack merge|remove <points> { ... }Stacks the marks its block draws as the app's Shape Stacker does, at the pieces under its points - the places where the marks overlap and where they do not: merge makes those pieces one shape, painted as the topmost mark over the first point, and each mark keeps what was not merged; remove takes them away from every mark. Text, pictures and eraser marks in the block are passed over. The block keeps its paint and transforms to itself, as a group does, and the points are where the stack line is.
Pathspathpath "<svg path data>"
path { ... }
One mark, from SVG path data or from a block of path steps. Each subpath of a compound path is one piece of the same mark.
Pathsmovemove <x> <y>Starts a new subpath at a point.
Pathstoto <x> <y>A straight segment to a point.
Pathsbyby <dx> <dy>A straight segment by an offset from the current point.
Pathscurvecurve <c1x> <c1y> <c2x> <c2y> <x> <y>A cubic curve to a point, steered by two handles.
Pathssmoothsmooth <c2x> <c2y> <x> <y>A cubic curve whose first handle mirrors the last one, so the join stays smooth.
Pathsthroughthrough <x> <y>, <x> <y>, ...A smooth curve through a list of points. Inside a path block it continues the subpath; outside one it is an open mark of its own.
PathsclosecloseCloses the current subpath back to its start.
Pathssplitsplit <x> <y>Cuts the topmost mark drawn so far whose path passes within 4 px of a point, where the point lands on it, as the app's Split does: an open path becomes two, a closed one opens there, and a compound shape gives up the ring that was cut, as an open mark of its own. Nothing moves, and the pieces take the mark's place on its layer. In a wipe or a stack block it cuts among the marks the block has drawn.
Pathssmearsmear <width> <strength> <x> <y>, <x> <y>, ...A pass of the Smear, a blending stump, along a list of points: it spreads the graphite of every pencil mark drawn so far that it reaches, along the drag, as the app's Smear does. The width is the stump's, scaled by the transform as a width is, and the strength from 0 to 1. In a wipe or a stack block it smears among the marks the block has drawn.
Pathswarpwarp <x> <y> <radius> <dx> <dy>Liquify's Warp, as the app's Liquify does it: a brush pushed from the point by dx and dy, carrying what is under its centre the whole way, like clay. The brush reaches the marks drawn so far whose outline passes within its radius of the point, under the transform as a mark drawn there would be, and its effect falls off smoothly to nothing at the rim; the radius scales with the transform. Pencil marks are the Smear's, and text, pictures and eraser marks have no outline to bend: all are left as they are. Each mark it bends is fitted again after, so its anchors stay few. In a wipe or a stack block it bends among the marks the block has drawn.
Pathstwirltwirl <x> <y> <radius> <degrees>Liquify's Twirl: turns what is under a brush at the point about its centre, by the angle in degrees there - clockwise on the screen, as rotate turns - and less toward the rim, so distances from the centre are kept. The brush reaches the marks drawn so far whose outline passes within its radius of the point, under the transform as a mark drawn there would be, and its effect falls off smoothly to nothing at the rim; the radius scales with the transform. Pencil marks are the Smear's, and text, pictures and eraser marks have no outline to bend: all are left as they are. Each mark it bends is fitted again after, so its anchors stay few. In a wipe or a stack block it bends among the marks the block has drawn.
Pathspuckerpucker <x> <y> <radius> <amount>Liquify's Pucker: draws what is under a brush at the point in toward its centre, a point near the centre by the amount, 0 to 1, of its distance. The brush reaches the marks drawn so far whose outline passes within its radius of the point, under the transform as a mark drawn there would be, and its effect falls off smoothly to nothing at the rim; the radius scales with the transform. Pencil marks are the Smear's, and text, pictures and eraser marks have no outline to bend: all are left as they are. Each mark it bends is fitted again after, so its anchors stay few. In a wipe or a stack block it bends among the marks the block has drawn.
Pathsbloatbloat <x> <y> <radius> <amount>Liquify's Bloat: pushes what is under a brush at the point out from its centre, a point near the centre by the amount, 0 to 1, of its distance. The brush reaches the marks drawn so far whose outline passes within its radius of the point, under the transform as a mark drawn there would be, and its effect falls off smoothly to nothing at the rim; the radius scales with the transform. Pencil marks are the Smear's, and text, pictures and eraser marks have no outline to bend: all are left as they are. Each mark it bends is fitted again after, so its anchors stay few. In a wipe or a stack block it bends among the marks the block has drawn.
Text and mediatexttext "<text>" at <x> <y> [size <size>] [box <width>] [inside "<path data>"] [along "<path data>"] [start <length>] [flip] [effect rainbow|skew|ribbon|stair|gravity] [align left|center|right|justify] [vertical] [config "<name>"] [runs (<start> <end> [config "<name>"] <character clauses>, ...)] [markdown] [as marks]A text item, set and aligned, and editable in the app: Sideless Typing from its anchor, Sheet Typing in a box or inside a shape, or Path Typing along a path, set in its runs' styles, the whole of it following a Text Configuration with config. With markdown its text is Markdown, shown as it renders: Markdown Flow. With as marks the letters are drawn as brush strokes instead.
Text and mediaimageimage "<asset or data URL>" at <x> <y> [size <width> [<height>]]Places an image: an asset the host supplied, by name, or a data URL. Nothing is read from disk.
Text and medialinklink "<path>" at <x> <y> [size <width> [<height>]] [name "<layer name>"]Places a linked file: one selectable element that references the file instead of drawing its contents into the page.
Text and mediauseuse "<document>" [at <x> <y>] [scale <s>] [layer "<name>"]Copies in a document the host supplied, as a group, with its layers and anchors.
Effectseffecteffect blur <radius>
effect brightness <amount>
effect contrast <amount>
effect saturate <amount>
effect grayscale [<0-1>]
effect sepia [<0-1>]
effect invert [<0-1>]
effect hue-rotate <degrees>
effect opacity <0-1>
effect drop-shadow <dx> <dy> <blur> <color> [spread <0-100>] [blend <mode>] [opacity <0-1>]
effect feather <radius>
effect bevel [inner|outer] [size <n>] [depth <percent>] [angle <degrees>] [altitude <degrees>] [soften <n>] [up|down] [light <color> [<0-1>]] [shade <color> [<0-1>]] [light-blend <mode>] [shade-blend <mode>]
effect emboss [emboss|pillow] [size <n>] [depth <percent>] [angle <degrees>] [altitude <degrees>] [soften <n>] [up|down] [light <color> [<0-1>]] [shade <color> [<0-1>]] [light-blend <mode>] [shade-blend <mode>]
effect inner-shadow <dx> <dy> <blur> <color> [choke <0-100>] [blend <mode>] [opacity <0-1>]
effect outer-glow [<blur>] [<color>] [spread <0-100>] [blend <mode>] [opacity <0-1>]
effect inner-glow [<blur>] [<color>] [choke <0-100>] [edge|center] [blend <mode>] [opacity <0-1>]
effect splatter [preset <name>] [angle <degrees>] [overlap <n> [<variation>]] [width <n>] [curviness <percent> [<variation>]] [spacing <n> [<variation>]] [seed <n>]
effect warp <style> [bend <percent>] [horizontal|vertical] [distort <percent> [<percent>]] [part whole|lower|upper]
effect extrude [<depth>] [rotate <x> <y> <z>] [perspective <degrees>] [shading plastic|diffuse|none|wireframe] [hollow] [light <azimuth> <elevation> [<intensity> [<ambient>]]] [position <x> <y> <z>] [scale <x> <y> <z>]
effect revolve [angle <degrees>] [offset <n>] [axis left|right] [segments <n>] [rotate <x> <y> <z>] [perspective <degrees>] [shading plastic|diffuse|none|wireframe] [hollow] [light <azimuth> <elevation> [<intensity> [<ambient>]]] [position <x> <y> <z>] [scale <x> <y> <z>]
effect none
An effect for the next layer, group or mark the script makes: a CSS filter function - blur, brightness, contrast, saturate, grayscale, sepia, invert, hue-rotate, opacity or drop-shadow, which is Outer Shadow - an appearance effect - feather, bevel, emboss, inner-shadow, outer-glow or inner-glow - or splatter, a vector editor's Scribble, which draws a mark's fill as a loose hatch (on a layer or a group it draws nothing) - or warp, a vector editor's Warp, which bends what takes it by a style, a layer's or a group's marks as one - or extrude and revolve, a vector editor's Classic 3D, which build a mark in depth and draw it as shaded faces (on a layer or a group they draw nothing). Any of them also takes on fill or on stroke, to work on that part of a mark alone, and hidden, to be kept without being drawn. Several stack in order, and none clears what is waiting.
Effectsblendblend <mode>How the next layer or group the script makes mixes with what is drawn under it, the page's background included: a Napkin Blend by its name or by Illustrator's - stack or multiply, sheer or screen, cover or luminosity. A blend is a layer's, so it waits for the next layer or group; normal sets one back.

What a block keeps to itself#

BlockKeeps
group "G" { ... }, place "d"Paint, transform, units and the current layer: a definition is a drawing of its own
repeat n { ... }Nothing: each pass starts where the last one ended
push ... popPaint, transform and units

The shape library#

ShapeNatural sizeMarksBackdropsRead from
square231.43 x 231.431-shapes.svg#square
rectangle482.09 x 231.431-shapes.svg#rectangle
circle272.06 x 272.061-shapes.svg#circle
ellipse514.62 x 212.941-shapes.svg#ellipse
triangle231.43 x 231.441-shapes.svg#triangle
right-triangle209.91 x 231.441-shapes.svg#right-triangle
hexagon164.76 x 142.681-shapes.svg#polygon
star233.42 x 2221-shapes.svg#star
horizontal195.31 x 01-shapes.svg#horizontal
vertical0 x 195.311-shapes.svg#verticla
45-degree138.11 x 138.111-shapes.svg#_45-degree
15-degree188.66 x 50.551-shapes.svg#_15-degree
arc79.66 x 103.41-shapes.svg#curve
spiral147.292 x 130.5611-shapes.svg#curve-2
wheel-isometric249.57 x 262.71231isometric-objects.svg#wheel-isometric
sphere-isometric275.74 x 275.741-isometric-objects.svg#sphere-isometric
cube-isometric296.23 x 264.397-isometric-objects.svg#cube-isometric
cylinder-isometric246.64 x 199.925-isometric-objects.svg#cylinder-isometric
wheel-perspective200.615 x 260.11631perspective-objects.svg#wheel-perspective
sphere-perspective262.48 x 275.741-perspective-objects.svg#sphere-perspective
cube-perspective267.9 x 223.0671perspective-objects.svg#cube-perspective
cylinder-perspective246.64 x 209.9251perspective-objects.svg#cylinder-perspective

The hand-drawn pass#

PartAt rough 1
Anchor driftUp to 5 px, and no more than 15% of the way to a neighbouring anchor
Bow of a straight segmentUp to 0.57 times the square root of its length: 5.7 px for a 100 px segment, 11.4 px for a 400 px one
Turn of a curve's handlesUp to 6 degrees, both handles of an anchor alike
Stretch of a curve's handlesUp to 20% longer or shorter
Overshoot1.5 line widths past each end, and no more than 25% of the segment it extends
Join of a closed lineUp to 60% of the anchor drift from where the line began
Fill under a lineRoughened 50% as much as the line
Second pass60% of the width and 55% of the opacity
Wobble length80 px: anchors closer together than this drift together

evaluate(source, options)#

OptionDefaultMeaning
namedrawingThe book's name and its first page's
seed0The seed for rough, until a seed line names one
assets, documentsnone{ logo: 'data:image/png;base64,...' } for image "logo"; pages or books for use "badge"
resolveLinknoneReads a linked file for its size; resolveLinkFromDir(folder)
limits, timestampthe budget, now{ marks: 200000 } raises one limit; a fixed timestamp makes a book the same byte for byte
fragmentfalseA snippet: no napkin line expected

One line each#

WantWrite
A rounded card, a dashed outline with no fill, or a linear gradientrect 20 20 360 260 r 16, style dashed fill none, gradient linear 90 (#ffe08a 0, #ff8a65 1)
A smooth curve through points, or a library hexagonthrough 20 200, 120 140, 240 190, shape "hexagon" at 40 40 size 120
Wrapped text, text along a path, or letters as brush strokestext "A caption" at 40 100 size 16 box 180, text "Acme" at 40 200 along "M0 0 C40 -40 120 -40 160 0", text "Hi" at 40 40 size 32 as marks
A Text Configuration a text follows, code colored as its language reads it, or Markdown shown as it renderstextconfig "Callout" face "Bold" color #cc0000 then text "Sale" at 40 40 config "Callout", accent python then text "x = 1" at 40 80, text "# Notes" at 40 120 markdown
A placed image, or a linked fileimage "logo" at 40 40 size 120, link "assets/logo.svg" at 40 40 size 160 80
A shadow under the next mark, a sepia layer, or one that multiplieseffect drop-shadow 4 4 8 #00000066, or effect sepia then layer "Photo", or blend stack then layer "Shade"

Common mistakes#

WrongRightWhy
image "art/logo.png" at 0 0image "logo" at 0 0, with the host passing logoA script reads no files: a path is unknown-asset.
Paint set inside repeat leaking outWrap the body in push ... popA repeat keeps nothing to itself.
effect blur 2, or blend stack, with nothing after itPut it right before the layer, group or mark; a blend before a layer or groupIt waits for the next one, and unused-effect or unused-blend says none came: a mark alone takes no blend.
Expecting rough 1 to wobble differently each runChange the seed: seed 3, or --seed 3One script and one seed draw the same bytes every run.