# Dg Dungeon Map

> Add an interactive dungeon map to an Obsidian Digital Garden (oleeskild digital-garden plugin + Eleventy) site. Use when a DG user wants a hex-grid map of their garden that renders in the note header, highlights the current page (you-are-here), and can overlay backlinks/mentions pulled from graph.json. The layout is a spiral whose rhythm follows the digits of pi; each note is a hex placed in date…

- **Type:** Skill
- **Install:** `agentstack add skill-palol-skills-zoo-dg-dungeon-map`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [palol](https://agentstack.voostack.com/s/palol)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [palol](https://github.com/palol)
- **Source:** https://github.com/palol/skills-zoo/tree/main/skills/dg-dungeon-map
- **Website:** http://skillz.paologabriel.com/

## Install

```sh
agentstack add skill-palol-skills-zoo-dg-dungeon-map
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://brad.quest/map/#dungeon) - a garden map mode that presents
  notes as a dungeon-style exploration surface.
- [Hermitage's Forest](https://hermitage.utsob.me/writings/technical/how-tos/steal-my-look/#forest)
  (source in [topobon](https://github.com/uroybd/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](https://docs.forestry.md/advanced/tips-and-tricks/#creating-hex-map) points
  readers to the [Digital Garden Map tutorial](https://www.paologabriel.com/swamp/digital-garden-map/)
  this skill packages (π spiral, hex layout, header map).
- Hex ring-walking spiral math follows
  [Red Blob Games](https://www.redblobgames.com/grids/hexagons/#rings-spiral).

## 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](https://www.redblobgames.com/grids/hexagons/#rings-spiral)).
- **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/`.
3. **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`
4. **Append** `assets/dungeon-map.scss` to `src/site/styles/custom-style.scss`.
5. **Add the postbuild hook** and deps (see step 3 in Instructions).
6. **Add icons** to `src/site/img/` and set `noteIcon` on notes (step 4).
7. **Build**, then walk the user through `references/verify.md`.
8. 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.
3. **`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.
4. A **sitemap** (`dist/sitemap.xml`) or a scannable `src/site/notes/` directory exists so the
   data script can enumerate published notes.
5. `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

```bash
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](https://github.com/palol)
- **Source:** [palol/skills-zoo](https://github.com/palol/skills-zoo)
- **License:** MIT
- **Homepage:** http://skillz.paologabriel.com/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-palol-skills-zoo-dg-dungeon-map
- Seller: https://agentstack.voostack.com/s/palol
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.