Reference Guide: Writing Guitar Articles with the Custom Hugo Shortcode

This reference guide establishes standard patterns for creating guitar visualizations in future articles. The underlying shortcode renders note badges centered directly on simulated guitar string lines, providing realistic fretboard diagrams with zero client-side JavaScript.

🛠️ Shortcode Parameter Spec Link to heading

Every diagram is declared via the {{< guitar ... >}} shortcode using these parameters:

🎨 Note Tagging & Visual Roles Link to heading

The 4th parameter of any note tuple specifies its visual role:

string_number : fret_number : note_text [: role_tag]

• Standard Note (No Tag): Defaults to slate grey badge (#334155). Used for general scale/chord tones.
• Root Note (:root): Highlighted with crimson red badge (#e11d48). Used for tonal center landmarks.
• Start Note (:start): Highlighted with amber gold badge (#f59e0b). Used for the initial exercise note, unisons, or scale run entry points.
• Open String Notes (Fret 0): Setting fret 0 (e.g. 5:0:A:start) highlights the open string zone to the left of the thick nut wire.

📦 Playable Region Boxes (box=...) Link to heading

The box parameter allows you to visually enclose playable chord or scale zones across designated strings and frets:

startString : endString : startFret : endFret [: hex_or_rgb_color]

• Automatic Palette: If no color is passed, boxes cycle through a distinct palette (cyan, emerald, purple, orange, pink).
• Custom Color: You can provide a custom hex color code at the end (e.g. 1:3:7:9:#a855f7).
• Multiple Regions: Separate multiple boxes with a comma (e.g. box="1:3:3:5, 1:3:7:9").

🎸 Common Usage Styles & Recipes Link to heading

1. Playable Region with Muted Bass Strings (box + mute) Link to heading

Highlight the active 4-string, 4-fret playing zone for open chords while muting unused lower strings:

{{/*< guitar
    title="Open D Major (Playable Box: Strings 1-4, Frets 0-3)"
    frets="0,1,2,3"
    mute="5,6"
    box="1:4:0:3"
    notes="4:0:D:root, 3:2:A, 2:3:D:root, 1:2:F#"
>*/}}

2. Side-by-Side Triad Inversions with Unique Colored Boxes Link to heading

Highlight separate 3-string triad zones across the neck with distinct colored borders:

{{/*< guitar
    title="E Minor Triad Inversions (Strings 1-3)"
    frets="0,3,4,5,7,8,9"
    mute="4,5,6"
    box="1:3:3:5:#10b981, 1:3:7:9:#a855f7"
    notes="3:4:B, 2:5:E:root, 1:3:G, 3:9:E:root, 2:8:G, 1:7:B"
>*/}}

3. Open Position Chord Boxes (From Nut / Fret 0) Link to heading

Ideal for standard open chords where open strings and fretted notes combine:

{{/*< guitar
    title="C Major (Open Shape — Strings 1 to 5)"
    frets="0,1,2,3"
    mute="6"
    box="1:5:0:3:#0ea5e9"
    notes="5:3:C:root, 4:2:E, 3:0:G, 2:1:C:root, 1:0:E"
>*/}}

4. Unison & Tuning Equivalences Link to heading

Use :start alongside :root across open and fretted strings to highlight unison pitches:

{{/*< guitar
    title="Unison Equivalence: 6th String Fret 5 (A) vs 5th String Open (A)"
    frets="0,1,2,3,4,5"
    notes="6:5:A:start, 5:0:A:root"
>*/}}

5. Full 2-Octave Box Scales Link to heading

Enclose the whole scale pattern inside a multi-string box:

{{/*< guitar
    title="A Minor Pentatonic (Box 1 — Frets 5 to 8)"
    frets="0,5,6,7,8"
    box="1:6:5:8:#f97316"
    notes="6:5:A:root, 6:8:C, 5:5:D, 5:7:E, 4:5:G, 4:7:A:root, 3:5:C, 3:7:D, 2:5:E, 2:8:G, 1:5:A:root, 1:8:C"
>*/}}

6. Interactive Scale Animation Link to heading

Add animate="true" to any shortcode to display an interactive player:

• Attaches Start and Stop badges to sequence endpoints.
• Embeds speed adjustment controls (0.5x, 1x, 1.5x, 2x) and pause/play toggle.
• Loops and highlights each note sequentially in declaration order.

{{/*< guitar
    title="C Major (Box 1 / E-Shape) — Step-by-Step Run"
    frets="0,7,8,9,10"
    animate="true"
    box="1:6:7:10:#0ea5e9"
    notes="6:8:C:root, 6:10:D, 5:7:E, 5:8:F, 5:10:G, 4:7:A:start, 4:9:B, 4:10:C:root, 3:7:D, 3:9:E, 3:10:F, 2:8:G, 2:10:A:start, 1:7:B, 1:8:C:root"
>*/}}

7. Multi-Diagram Selector Tabs (items=...) Link to heading

Keep the full items="..." string on a single line without unescaped line breaks so Hugo parses the argument without syntax errors:

{{/*< guitar title="Major Chord Family Across All Roots" items="A | frets:1,2,3 | mute:6 | notes:5:0:A:root,4:2:E,3:2:A:root,2:2:C#,1:0:E; B | frets:2,3,4 | mute:6 | notes:5:2:B:root,4:4:F#,3:4:B:root,2:4:D#,1:2:F#; C | frets:1,2,3 | mute:6 | notes:5:3:C:root,4:2:E,3:0:G,2:1:C:root,1:0:E; D | frets:1,2,3 | mute:6,5 | notes:4:0:D:root,3:2:A,2:3:D:root,1:2:F#; E | frets:1,2,3 | notes:6:0:E:root,5:2:B,4:2:E:root,3:1:G#,2:0:B,1:0:E:root; F | frets:1,2,3 | notes:6:1:F:root,5:3:C,4:3:F:root,3:2:A,2:1:C,1:1:F:root; G | frets:1,2,3 | notes:6:3:G:root,5:2:B,4:0:D,3:0:G:root,2:0:B,1:3:G:root" >*/}}

✍️ Best Practices for Blog Authors Link to heading

• Single-Line Attributes: Never insert line breaks inside a quoted shortcode attribute like items="..." or notes="...".
• Order of Strings: Always identify strings with numbers 1 (high e) through 6 (low E).
• Muted Strings: Declare mute="5,6" whenever open bass strings shouldn’t ring in chord voicings.
• Playable Boxes: Use box="s1:s2:f1:f2" to visually box in finger clusters and positional regions.