Skip to content

Interactive Map Module

Embeddable Leaflet map for MkDocs, loaded from a simple <div>. Satellite basemap (Esri) with OSM tiles overlaid at close zooms to avoid blank imagery.

Overview

  • Toggleable overlays from KMZ, KML, or GeoJSON
  • Folder-aware layer tree (from KML/KMZ Folders) with nested, collapsible branches
  • Color swatches reflect KML styles; popups render sanitized HTML and links
  • Responsive, glassy, scrollable menu; outside-click collapses top-most sections only

Quick Start

  1. Ensure mkdocs.yml includes the CSS/JS (see Integration).
  2. Place overlays under docs/assets/maps/overlays/ (or any served path).
  3. Add the map to a Markdown page:
<div class="lb-map"
     data-center="-12.916,131.300"
     data-zoom="14"
     data-height="60vh"
     data-max-zoom="22"
     data-swap-zoom="17"
     data-overlays='[
       {"name":"Water Mains","url":"/assets/maps/overlays/water-mains.kmz"},
       {"name":"Sewer Lines","url":"/assets/maps/overlays/sewer.kmz"}
     ]'>
</div>

Deep-Linking (Preselect Layers)

Use the URL hash to pre-check items by name (slugged):

  • Single: #watertanks
  • Multiple: #watertanks,power-cables
  • With key: #show=water-pipes/potted-aux,power-cables

Slug rules: lowercase; spaces become dashes; punctuation is removed. Nested items can use parent/child. Ancestors auto-expand to reveal selected items.

Data Attributes

Attribute Detail
data-center "lat,lng" (optional)
data-zoom Initial zoom (optional)
data-height CSS size (e.g. 480px, 60vh). Default 60vh
data-autofit true/false (default true). If true and overlays exist, map fits to their bounds
data-overlays JSON array of overlays { name, url, type? } where type is kmz\|kml\|geojson (auto-detected if omitted)
data-kmz Comma-separated list of KMZ/KML URLs (fallback to data-overlays)
data-max-zoom Maximum interactive zoom (default 22). Allows over-zooming beyond tile native max
data-swap-zoom Integer zoom at which OSM tiles overlay Esri (default 17)
data-base-path Optional base path prefix for built sites (e.g. /site). Alternatively set window.LB_MAP_BASE_PATH = '/site'

Behaviour and UI

  • KML/KMZ Folders become nested menu branches; leaf nodes are not collapsible
  • Double-click a branch label to zoom to that branch’s extent; double-click the overlay title to zoom to its full extent
  • Outside-click collapses only the top-most sections, preserving inner open states
  • Overlays start unchecked; checking adds layers to the map

Popups

  • Name shown as title
  • Description supports sanitized HTML; plain text is auto-linkified
  • Additional properties are listed in a table; style fields are omitted

Integration (mkdocs.yml)

Add the following:

extra_css:
  - https://unpkg.com/leaflet@1.9.4/dist/leaflet.css
  - assets/maps/leaflet-map.css

extra_javascript:
  - https://unpkg.com/leaflet@1.9.4/dist/leaflet.js
  - https://cdnjs.cloudflare.com/ajax/libs/jszip/3.10.1/jszip.min.js
  - https://unpkg.com/@tmcw/togeojson@5.8.0/dist/togeojson.umd.js
  - assets/maps/leaflet-map.js

Notes

  • KMZ is handled in-browser via JSZip + toGeoJSON; large files may be slow — consider preprocessing
  • Esri World Imagery is used for satellite. At close zooms (≥ data-swap-zoom), OSM overlays to maintain tiles
  • Ensure overlay URLs are same-origin (served by MkDocs) to avoid CORS issues

Optional Preprocessing

Use kmz_to_geojson.sh (Ubuntu/Linux) or kmz_to_geojson.bat (Windows) with GDAL ogr2ogr installed:

./kmz_to_geojson.sh input.kmz output.geojson

kmz_to_geojson.bat input.kmz output.geojson

Version Control

Version Date Description
1.0 2025-10-06 Initial Release

Next Review Date: 2026-04-06