Dg Dungeon Map

Digital Garden Dungeon Map

Adds an interactive dungeon map to a Digital Garden (oleeskild digital-garden plugin + Eleventy) site. Notes become hexes on a spiral whose spacing follows the digits of π; the header component renders the generated SVG, marks the current page ("you are here"), and can toggle a backlinks / mentions overlay derived from graph.json.

Everything lives in user-owned paths (autoloaded components, custom-style.scss) plus two build scripts in scripts/ - upstream git pull never overwrites your files.

Inspirations

Conceptual / visual inspiration (not code provenance):

• brad.quest's Dungeon view - a garden map mode that presents

notes as a dungeon-style exploration surface.

• Hermitage's Forest

(source in topobon) - a home-page forest of notes that treats the garden as a wanderable landscape.

Technical packaging / implementation sources:

• The official Digital Garden docs tip

Creating hex map points readers to the Digital Garden Map tutorial this skill packages (π spiral, hex layout, header map).

• Hex ring-walking spiral math follows

Red Blob Games.

When to Use This Skill

Use when a Digital Garden user wants:

• A visual, wander-friendly map of their whole garden in the note header.
• A "you are here" marker on the current note, visible even with overlays off.
• Optional backlink/mention overlays that connect the current note to related rooms.

Do not use for Quartz, Astro, or non-DG sites - the autoload mechanism, theme tokens, and graph.json shape are DG-specific. This skill installs the feature; to author new DG skills, use dg-skill-authoring.

How It Works (the pipeline)

notes + frontmatter (noteIcon, dates)
   → [build] eleventy build           (produces sitemap + graph.json)
   → [postbuild] generate-static-dungeon.js
         ├─ generate-dungeon-data.js  (sort by date, π virtual-tile list, hex-spiral.js)
         │     → dist/data/dungeon-data.json  (+ src/site/_data/dungeonData.json)
         └─ build SVG (hexes, spiral path, icons)
               → dist/img/dungeon-map.svg
   → [runtime] dungeon.njk header slot renders the SVG;
               zz-dungeon-map-init.njk fetches SVG + graph.json,
               marks current hex, draws backlink/mention overlays;
               aa-graph-helpers.njk provides shared graph lookups.

• π spiral: getPiDigits + createVirtualTileList read π in digit pairs - first digit = how

many content hexes, second = how many empty "ambient" hexes - so the path rhythm is literally π. Hex positions come from an axial-coordinate ring-walking spiral (hex-spiral.js, per Red Blob Games).

• Current-note marker is derived from the page URL (gold "you are here" dot + magenta outline)

and stays visible even when the backlink/mention overlay is toggled off.

Quick Install (agent-driven)

1. Verify prerequisites (below). If the repo doesn't match, say so plainly and stop.
2. Copy the build scripts: assets/generate-dungeon-data.js and

assets/generate-static-dungeon.js → scripts/; assets/hex-spiral.js → src/helpers/.

1. Copy the components into their user-owned slots:

• assets/dungeon.njk → src/site/_includes/components/user/notes/header/dungeon.njk
• assets/aa-graph-helpers.njk → src/site/_includes/components/user/common/head/aa-graph-helpers.njk
• assets/zz-dungeon-map-init.njk → src/site/_includes/components/user/common/footer/zz-dungeon-map-init.njk

1. Append assets/dungeon-map.scss to src/site/styles/custom-style.scss.
2. Add the postbuild hook and deps (see step 3 in Instructions).
3. Add icons to src/site/img/ and set noteIcon on notes (step 4).
4. Build, then walk the user through references/verify.md.
5. Only commit/push if the user asks.

Prerequisites (verify first)

1. Repo uses the DG plugin with Eleventy; site source under src/site/.
2. User-component autoloading exists: src/site/_data/dynamics.js globs

components/user/common//*.njk (and components/user/notes//*.njk), sorts alphabetically, injects into layout slots. Confirm the notes/header, common/head, and common/footer slots are iterated.

1. graph.json is emitted at the site root (/graph.json) with a nodes map whose entries

carry backLinks, outBound, and neighbors arrays. This is the DG local-graph data; the overlays degrade gracefully to no-op if it's absent.

1. A sitemap (dist/sitemap.xml) or a scannable src/site/notes/ directory exists so the

data script can enumerate published notes.

1. src/site/styles/custom-style.scss is compiled into the site CSS.

If any path differs, adapt it but keep the structure. If the repo is not DG+Eleventy, stop.

Instructions

1. Install the components (autoloaded, no layout edits)

Filename prefixes matter - the autoloader sorts alphabetically within a slot:

• aa-graph-helpers.njk (head) - aa- so the helper window global exists before other head scripts.
• zz-dungeon-map-init.njk (footer) - zz- so it runs after the DOM/SVG is in place.
• dungeon.njk (notes/header) - renders the map container.

Copy each to the path in Quick Install step 3. No layout edit is needed.

2. Install the styles

Append assets/dungeon-map.scss to src/site/styles/custom-style.scss. Safe tunables live in the >>> TUNING KNOBS s with aria-pressed; the hint uses aria-live="polite"; the fallback `` has alt text.

Risk Level

L2 (moderate). Beyond user-owned component/style files, this adds two Node build scripts and a helper that execute at build time and read your notes and sitemap to generate the SVG and JSON. No secrets, no network calls, output is static files. Review assets/*.js before wiring the postbuild hook. Fully reversible via git (remove the files + the postbuild line).

Reference Files

• references/architecture.md - annotated tour of the pipeline, data shapes, and each file's job.
• references/tuning.md - every adjustable knob (π source, hex size, spiral, config constants, SCSS).
• references/verify.md - post-build QA checklist.

Assets

• assets/generate-dungeon-data.js - enumerate notes, sort by date, π virtual-tile list, spiral.
• assets/generate-static-dungeon.js - build the SVG (hexes, path, icons) + coordinate map.
• assets/hex-spiral.js - axial-coordinate ring-walking spiral generator.
• assets/dungeon.njk - notes/header slot: the map container + overlay controls.
• assets/aa-graph-helpers.njk - head slot: shared graph.json lookups (window.DgGraphHelpers).
• assets/zz-dungeon-map-init.njk - footer slot: fetch SVG, mark current hex, draw overlays.
• assets/dungeon-map.scss - styles (TUNING KNOBS on top; colors inherit theme).

Validate & Package

npx skills-ref validate skills/dg-dungeon-map/
zip -rq dg-dungeon-map.zip dg-dungeon-map

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: palol
• Source: palol/skills-zoo
• License: MIT
• Homepage: http://skillz.paologabriel.com/

Install and usage instructions live in the source repository linked above.