Fretboard Renderer

日本語 README

Render guitar fretboard diagrams as SVG in your Obsidian notes, from a lightweight YAML syntax inside fenced code blocks. From analyzing chord progressions to checking pentatonic/mode positions, the goal is clean-looking diagrams with minimal typing.

```fretboard
notes:
  - {s: 6, f: 0, label: root}
  - [5, 2]
  - [4, 5]
  - [3, 2]
  - [2, 0]
  - [1, 0]
```

Installation

From Community Plugins

Search for "Fretboard Renderer" in Obsidian's Community Plugins browser and install it.

Manual / development build

1. Clone or place this repository at <vault>/.obsidian/plugins/fretboard-renderer.
2. npm install
3. npm run build (one-off build), or npm run dev (watch mode, rebuilds on save)
4. Enable "Fretboard Renderer" in Obsidian's Settings → Community plugins.

Three configuration layers (System / Global / Local)

Configuration is layered in three tiers, each one overriding the last:

Local (YAML inside a single ```fretboard block)
  ↑ overrides
Global (fretboard-renderer.yaml at the vault root)
  ↑ overrides
System (the plugin's Settings tab)

System (Settings tab)

Change these under Settings → Fretboard Renderer. They're the defaults for every diagram in the vault. The settings tab is organized into four sections: "Layout & dimensions", "Display & style", "Note appearance", and "Tuning & fallback".

Label mode: note only shows note names in absolute mode (startFret given, or an explicit open string f: 0 present). In relative/movable mode (startFret omitted and no open string), the actual notes depend on where the shape is played, so note mode shows no automatic label either (interval labels are unaffected, since the same relationship holds wherever the shape is played).

Global (vault-wide YAML config file)

Create a file named fretboard-renderer.yaml at the vault's root (not inside .obsidian/) to override System values for the whole vault. It accepts the same keys as the System table above.

# <vault root>/fretboard-renderer.yaml
orientation: vertical
fretCount: 5
labelMode: note

• Any key that's absent, or if the file doesn't exist, falls back to the System value.
• Saving the file takes effect on the next render — no need to reload the plugin.
• A syntax error shows a one-time Obsidian notice and falls back to System settings (it won't break every diagram in the vault).

Local (YAML inside each ```fretboard block)

Write this directly inside each note's ```fretboard code block. It has the highest priority, overriding both System and Global. Only notes is required.

title: Am Pentatonic (Box 1)
visible: 1-6
startFret: 5
frets: 4
boxes:
  - {frets: "5-8", style: dashed}
paths:
  - [[6,5], [6,8], [5,5], [5,7]]
notes:
  - {s: 6, f: 5, label: root, shape: square}
  - [6, 8]
  - {s: 5, f: 5}
  - {s: 5, f: 7, finger: 3, ghost: true}

notes (required)

An array of note placements. Both object form and a positional shorthand array are accepted.

notes:
  - {s: 6, f: 5, label: root, shape: square, finger: 1, ghost: false, class: "highlight"}
  - [6, 8]              # [s, f]
  - [5, 5, "root"]       # [s, f, label]
  - [5, 7, "3", "square", 3]  # [s, f, label, shape, finger]
  - {s: 4, f: 7, color: red, fillStyle: outlined, sizeAdjust: -3, labelSizeAdjust: 2}

color, fillStyle, sizeAdjust, and labelSizeAdjust are only available in object form ({s: ..., f: ...}) — not in the [s, f, label, shape, finger] shorthand array.

Notes highlighted as the root (same pitch class as the label: root note, including octaves) use the System accent color by default (Obsidian's --interactive-accent theme variable, typically purple/blue) — this is intentional default behavior. Use color above to override the color of any specific note, e.g. to make it red.

Other Local options (all optional)

size / fretSpacingAdjust / stringSpacingAdjust (whole diagram) and each note's sizeAdjust / labelSizeAdjust exist so you can fine-tune appearance from a note's YAML instead of editing the plugin's own styles.css — that file isn't meant to be edited by users. Fine-grained color is likewise handled per-note via color, not CSS.

Absolute mode vs. relative mode

• Absolute mode: startFret is given, or — even without it — notes contains an explicit open string (f: 0), since a shape with an open string can't physically be moved up the neck. Generates a real chord name (e.g. Cmaj7), and only draws the nut (thick/double line) when the left edge is truly fret 0.
• Relative mode: startFret is omitted and no open string is present. Treated as a movable pattern: the leftmost fret is set automatically to the lowest fretted note (excluding 0 and x), no fret numbers are printed, and a relative chord name is generated (e.g. □maj7).

Interval auto-calculation and root highlighting

Marking any note with label: root auto-computes each note's interval degree (1, b2, 2, m3, 3, 4, b5, 5, m6, 6, m7, M7) relative to the tuning, and shows it when label mode is interval. Notes matching the root's pitch class (including other octaves) are automatically highlighted (different shape and/or color).

This calculation can't distinguish tensions beyond one octave — e.g. a 9th looks the same as a 2nd, an 11th the same as a 4th. To show them correctly, override a note's label (e.g. label: "9") or the diagram's title (e.g. title: Cmaj9) explicitly.

Multiple diagrams side by side (diagrams)

Writing separate ```fretboard blocks back to back doesn't reliably place them side by side — that depends on how Obsidian itself wraps markdown blocks, which a CSS snippet can't always override (Obsidian sometimes wraps each code block in an outer element the plugin has no access to).

To make this reliable, use the diagrams syntax: several diagrams in one ```fretboard block. The plugin builds its own flexbox layout entirely inside that one block's container, so it doesn't depend on how Obsidian wraps blocks at all.

diagrams:
  - title: Cmaj7
    startFret: 0
    size: 0.6
    notes:
      - {s: 5, f: 3, label: root}
      - [4, 2]
      - [3, 0]
      - [2, 0]
  - title: Dm7
    startFret: 0
    size: 0.6
    notes:
      - {s: 4, f: 0, label: root}
      - [3, 2]
      - [2, 1]
      - [1, 1]
  - title: G7
    startFret: 0
    size: 0.6
    notes:
      - {s: 6, f: 3, label: root}
      - [5, 2]
      - [4, 0]
      - [3, 0]
      - [2, 0]
      - [1, 1]

• A block using diagrams (a list) can't mix in other top-level keys like notes — it's treated purely as a multi-diagram block.
• Each entry in diagrams accepts exactly the same keys as a single diagram (title, startFret, notes, size, orientation, ...).
• Wrapping happens automatically based on the available width.
• Errors are reported with the diagram's index, e.g. diagrams[0].notes.

Error handling

• Local (a block's YAML): A syntax error or invalid value doesn't crash the plugin — it shows a red error message inside that code block.
• Global (vault-wide file): A syntax error in fretboard-renderer.yaml doesn't break every diagram in the vault — it shows a one-time Obsidian notice and falls back to System settings.
• Unknown keys (typo detection): Both Local and Global reject unrecognized keys (e.g. flets instead of frets) with an explicit error, rather than silently ignoring them — a silently-ignored typo looks like nothing happened, which is much harder to debug. This also applies to keys inside notes / barre / boxes entries.

Development

npm install    # install dependencies
npm run dev    # esbuild watch build (keep this running while developing)
npm run build  # type-check + production build (produces main.js)
npm test       # unit tests via vitest

License

MIT