SketchMatter

This logo was created using this plugin and is available in the /sketch-matter-demo-vault

SketchMatter renders SVG images from the frontmatter in Obsidian notes.

Examples

The following examples are available in the /sketch-matter-demo-vault

Features

Preview Panel

• View image preview
• Edit by drag-and-drop
• Choose no grid, a customizable grid, or a hex grid
• Zoom and pan

3D Globe

• Switch between the 2D map and an interactive 3D globe
• Select from a variety of map projection modes
• Rotate the globe by dragging and zoom with the mouse wheel or a pinch gesture

Export

• Export a render as SVG

Inline Code Block

• Select an image and optional view to render directly in a note

Details

• Draw objects from note frontmatter
  • Support built-in shapes: polygon, polyline, line, circle, rect, ellipse, text, and composite
  • Create type definitions to extend base shapes, or other type definitions
• Order objects by layer
• Filter objects by layer using views
• Blend to soften edges
• Mask to keep items within certain bounds
• Noise to create jagged edges from a seed

Object notes

An object note usually contains:

• a type tag such as sketchmatter-type/continent
• optionally additional type tags when the same note should render as multiple objects
• coordinates
• optional label coordinates for label rendering
• an optional layer override
• optional image IDs
• optional style overrides such as fill, stroke, strokeWidth, and opacity

Example:

---
tags:
  - sketchmatter-type/continent
  - sketchmatter-type/label
sketchmatter-layer: 100
sketchmatter-coordinates:
  - "100, 100"
  - "300, 120"
  - "360, 240"
  - "220, 300"
sketchmatter-label-coordinates:
  - "240, 190"
sketchmatter-label-text: Sunreach
sketchmatter-font-family: Georgia
sketchmatter-font-size: 24
sketchmatter-font-style:
  - bold
  - italic
sketchmatter-font-color: "#4b2d12"
sketchmatter-image-id: map1
---

sketchmatter-image-id can be a single ID, a comma-separated string, or a YAML array when one object belongs to multiple images.

Coordinates are interpreted by the resolved shape renderer. Type definitions in plugin settings provide the usual shape and style defaults, and object-level frontmatter can override them. If a note has multiple matching type tags, SketchMatter emits one object per type tag so a single note can render, for example, both a continent polygon and its label.

Type definitions

Type definitions are configured in Settings → Community plugins → SketchMatter.

Each type definition can specify:

• Type name
• Extends for inherited defaults
• Shape
• Default layer
• Layer override property (optional, type-specific layer frontmatter key such as sketchmatter-label-layer)
• Style JSON
• optional extra properties consumed by a shape

The default settings include:

• a label type definition that uses the built-in text shape and reads its position from sketchmatter-label-coordinates
• a city type definition that uses the built-in composite shape for a marker symbol

If a shape is not explicitly set, SketchMatter can infer one from the coordinate structure.

View definitions

View definition notes are tagged like this:

tags:
  - sketchmatter-view/political

Supported frontmatter:

• sketchmatter-include-layers
• sketchmatter-exclude-layers
• includeImageIds
• excludeImageIds

Example:

---
tags:
  - sketchmatter-view/political
sketchmatter-include-layers: 100-400
includeImageIds:
  - map3
---

Views can be selected in the panel or referenced from a sketchmatter code block.

Image definitions

Image definition notes are tagged like this:

tags:
  - sketchmatter-image/map2

Supported frontmatter:

• sketchmatter-width
• sketchmatter-height
• sketchmatter-background-color
• sketchmatter-background-image
• sketchmatter-preserve-aspect-ratio
• sketchmatter-projection (see the supported projections below)

sketchmatter-background-image accepts vault assets, wikilinks, absolute URLs, and data URLs.

For 2D previews and SVG exports, image dimensions set the minimum canvas size. The canvas expands to include rendered objects outside those dimensions, including objects at negative coordinates. Without an image definition, the minimum canvas size is 1200 × 900. Backgrounds keep their configured size. Globe textures keep the fixed image dimensions for projection alignment.

Embedding in notes

Use a sketchmatter code block:

image: map1
view: political

Supported parameters:

• image
• view
• mode (2d or globe)
• projection (see the supported projections below)

Both are optional. The view value is case-insensitive. If an image is omitted, SketchMatter will try to resolve one from the selected view or the filtered objects.

Use an interactive globe in a note with:

image: Earth
view: political
mode: globe
projection: equirectangular

Projection describes the layout of the completed source map. It does not change existing object coordinates or reproject the 2D SVG. A code-block or panel override takes precedence over the image definition, which takes precedence over the plugin default.

Supported source projections:

• equirectangular — direct longitude and latitude mapping
• mercator — Web Mercator, with polar caps clamped at approximately ±85.0511°
• miller — Miller cylindrical compromise projection
• gall-peters — Gall–Peters equal-area cylindrical projection
• mollweide — Mollweide equal-area elliptical projection
• robinson — Robinson compromise projection
• winkel-tripel — Winkel Tripel compromise projection

For the five extended projections, SketchMatter assumes the complete world projection is centered and proportionally fitted to the full image canvas. Select the projection in which the source map was authored; selecting a different projection does not convert the underlying note coordinates. Winkel Tripel uses a 2048×1024 texture limit to keep interactive preview generation responsive.

Globe previews require WebGL. If WebGL or a texture asset is unavailable, SketchMatter displays the existing 2D preview with an error message. Remote image assets remain subject to the source server's CORS policy. Editing and SVG export continue to use the 2D map.

Styling and advanced rendering

In addition to type-definition styles, object notes can opt into:

• Opacity with sketchmatter-opacity
• Texture fills with sketchmatter-texture
• Masks with sketchmatter-mask
• Soft-edge blending with sketchmatter-blend and sketchmatter-blend-radius
• Overlap-only patterns with sketchmatter-overlap-pattern, sketchmatter-overlap-thickness, sketchmatter-overlap-spacing, sketchmatter-overlap-angle, and sketchmatter-overlap-color
• Deterministic edge noise with sketchmatter-seed, sketchmatter-magnitude, and sketchmatter-noise
• Label text with sketchmatter-label-text
• Label font family, size, style list, and color with sketchmatter-font-family, sketchmatter-font-size, sketchmatter-font-style, and sketchmatter-font-color

sketchmatter-texture accepts the same asset forms as background images: vault paths, wikilinks, absolute URLs, and data URLs.

Mask selectors can target:

• type:<type-name>
• file:<path-or-basename>
• a plain value matched against type or file name, such as continent

Overlap patterns are drawn only where objects of the same type intersect. Supported pattern values are:

• lines
• hatch
• crosshatch
• dots

For lines, use sketchmatter-overlap-angle to rotate the line direction (degrees, default 0).

Exporting SVG

In the panel, select Export SVG to write the current render to the vault root.

Typical filenames look like:

• sketch-matter-export-all.svg
• sketch-matter-export-political-map1.svg

Configurable property names

All user-facing frontmatter and tag-prefix keys are configurable in plugin settings. The defaults include:

• sketchmatter-type
• sketchmatter-view
• sketchmatter-image
• sketchmatter-layer
• sketchmatter-shape
• sketchmatter-children
• sketchmatter-coordinates
• sketchmatter-radius
• sketchmatter-image-id
• sketchmatter-label-coordinates
• sketchmatter-label-text
• sketchmatter-font-family
• sketchmatter-font-size
• sketchmatter-font-style
• sketchmatter-font-color
• sketchmatter-width
• sketchmatter-height
• sketchmatter-background-color
• sketchmatter-background-image
• sketchmatter-preserve-aspect-ratio
• sketchmatter-opacity
• sketchmatter-texture
• sketchmatter-mask
• sketchmatter-seed
• sketchmatter-magnitude
• sketchmatter-noise
• sketchmatter-blend
• sketchmatter-blend-radius
• sketchmatter-overlap-pattern
• sketchmatter-overlap-thickness
• sketchmatter-overlap-spacing
• sketchmatter-overlap-angle
• sketchmatter-overlap-color
• sketchmatter-fill
• sketchmatter-stroke
• sketchmatter-stroke-width
• defaultLayer: 1000 (fallback layer for objects with no layer set)

Install for development

1. Install dependencies:

   npm install
   

2. Build the plugin:

   npm run build
   

3. Copy main.js, manifest.json, and styles.css to:

   <Vault>/.obsidian/plugins/sketch-matter/
   

4. In Obsidian, enable Settings → Community plugins → SketchMatter.
5. Run SketchMatter: Open panel from the command palette.

For watch mode during development:

npm run dev

Fastest way to try it

This repository includes a ready-made demo vault in /sketch-matter-demo-vault.

• Windows/PowerShell:

  .\scripts\build-to-demo-vault.ps1
  

• Any platform:
  1. Run npm run build
  2. Copy main.js, manifest.json, and styles.css to sketch-matter-demo-vault/.obsidian/plugins/sketch-matter/
  3. Open sketch-matter-demo-vault in Obsidian

See sketch-matter-demo-vault/README.md for a guided walkthrough.

How the plugin is organized

SketchMatter works with three note types:

1. Object notes
   Notes tagged with the configured type-tag prefix become drawable objects.
2. View definition notes
   Notes tagged with the configured view-tag prefix filter objects by layer and image ID.
3. Image definition notes
   Notes tagged with the configured image-tag prefix define SVG-wide settings such as size and background.

At render time, the plugin collects objects, applies any selected view and image filters, resolves shapes and styling, and renders the matching objects into one SVG.