Usage

How to use the Leaflet shortcode extension

1 Overview

The leaflet shortcode embeds interactive Leaflet maps into Quarto documents. It supports two input modes:

  1. YAML metadata — define map configuration in the document frontmatter and reference by label
  2. Inline shortcode arguments — pass parameters directly in the shortcode

center can be omitted when marker coordinates are available. In that case, the center is computed as the midpoint of the bounding box of all marker coordinates (i.e. the midpoint between the extreme latitudes and the extreme longitudes). This is unbiased with respect to point density — a dense cluster has no more influence than a single isolated point. If zoom is omitted or cannot be parsed, the shortcode uses 13.

2 Basic map

2.1 YAML metadata approach

Define the map in the YAML frontmatter:

---
leaflet:
  map-basic:
    center: [51.505, -0.09]
    zoom: 13
    height: "400px"
---

Then reference it in the document:

{{< leaflet map-basic >}}

2.2 Inline approach

Pass parameters directly as shortcode arguments:

{{< leaflet center="[48.86, 2.35]" zoom=14 height="350px" >}}

3 Markers

Add markers with popups and tooltips:

---
leaflet:
  map-markers:
    center: [59.33, 18.07]
    zoom: 12
    height: "400px"
    markers:
      - lat: 59.33
        lon: 18.07
        popup: "<b>Stockholm</b><br>Capital of Sweden"
        tooltip: "Stockholm"
      - lat: 59.35
        lon: 18.10
        popup: "Djurgården"
      - lat: 59.31
        lon: 18.05
        popup: "Södermalm"
---

{{< leaflet map-markers >}}

3.1 Inline approach

Markers can also be passed directly as a JSON string:

{{< leaflet center="[59.33, 18.07]" zoom=12 height="350px" markers='[{"lat":59.33,"lon":18.07,"popup":"<b>Stockholm</b>","tooltip":"Stockholm"},{"lat":59.35,"lon":18.10,"popup":"Djurgården"},{"lat":59.31,"lon":18.05,"popup":"Södermalm"}]' >}}

center can be omitted when markers are present:

{{< leaflet height="350px" markers='[{"lat":59.33,"lon":18.07,"popup":"<b>Stockholm</b>","tooltip":"Stockholm"},{"lat":59.35,"lon":18.10,"popup":"Djurgården"},{"lat":59.31,"lon":18.05,"popup":"Södermalm"}]' >}}

3.2 Delimited text file approach

Markers can be read from any text file at render time using markers-file. The file must include lat and lon columns. Optional columns include popup, tooltip, icon, icon-color, icon-size, icon-anchor, and icon-url.

leaflet:
  map-markers-tab:
    center: [59.33, 18.07]
    zoom: 12
    height: "400px"
    markers-file: "data/stockholm-markers.tsv"
    markers-sep: "\t"
lat lon popup   tooltip icon    icon-color  icon-size
59.33   18.07   <b>Stockholm</b><br>Capital of Sweden   Stockholm   fa-solid fa-house   tomato  18
59.35   18.10   Djurgården  Djurgården  fa-solid fa-tree    #2f7d32 18
59.31   18.05   Södermalm   Södermalm   fa-solid fa-briefcase   #4a90d9 18
{{< leaflet map-markers-tab >}}

Inline shortcodes can use the same file:

{{< leaflet center="[59.33, 18.07]" zoom=12 height="350px" markers-file="data/stockholm-markers.tsv" markers-sep="\t" >}}

center is also optional for file-based markers:

{{< leaflet height="350px" markers-file="data/stockholm-markers.tsv" markers-sep="\t" >}}

3.3 CSV file approach

CSV files can be loaded directly with markers-file. If omitted, separator defaults to comma for .csv, tab for .tsv, and tab otherwise.

leaflet:
  map-markers-csv:
    center: [59.33, 18.07]
    zoom: 12
    height: "400px"
    markers-file: "data/stockholm-markers.csv"
lat,lon,popup,tooltip,icon,icon-color,icon-size
59.33,18.07,"<b>Stockholm</b><br>Capital of Sweden",Stockholm,fa-solid fa-house,tomato,26
59.35,18.10,Djurgården,Djurgården,fa-solid fa-tree,#2f7d32,26
59.31,18.05,Södermalm,Södermalm,fa-solid fa-briefcase,#4a90d9,26
{{< leaflet map-markers-csv >}}

Inline shortcodes can also read CSV files:

{{< leaflet center="[59.33, 18.07]" zoom=12 height="350px" markers-file="data/stockholm-markers.csv" >}}

4 Icon markers

Use Font Awesome 6 classes for markers. The extension now loads the stylesheet automatically, so no extra header setup is required.

---
leaflet:
  map-icons:
    center: [48.86, 2.35]
    zoom: 13
    height: "400px"
    markers:
      - lat: 48.8584
        lon: 2.2945
        popup: "<b>Eiffel Tower</b>"
        icon: "fa-solid fa-house"
        icon-color: "tomato"
        icon-size: 16
      - lat: 48.8606
        lon: 2.3376
        tooltip: "Louvre Museum"
        popup: "<b>Louvre Museum</b>"
        icon: "fa-solid fa-building-columns"
        icon-color: "#4a90d9"
        icon-size: 16
      - lat: 48.853
        lon: 2.3499
        popup: "<b>Notre-Dame</b>"
        icon: "fa-solid fa-church"
        icon-color: "green"
        icon-size: 16
---

{{< leaflet map-icons >}}

4.1 Font Awesome example

Use Font Awesome classes in icon. The extension injects the stylesheet automatically.

---
leaflet:
  map-fontawesome:
    center: [41.9028, 12.4964]
    zoom: 13
    height: "400px"
    markers:
      - lat: 41.9028
        lon: 12.4964
        popup: "<b>Roman Forum</b>"
        icon: "fa-solid fa-landmark"
        icon-color: "#b04a2b"
        icon-size: 16
      - lat: 41.89
        lon: 12.4922
        tooltip: "Colosseum"
        popup: "<b>Colosseum</b>"
        icon: "fa-solid fa-torii-gate"
        icon-color: "#5c6f7b"
        icon-size: 16
---

{{< leaflet map-fontawesome >}}

4.2 Icon types

Mode Example Description
Font Awesome icon: "fa-solid fa-tree" Included automatically by the extension. Use any Font Awesome class name.
Custom image icon: {url: "pin.png", size: [25,41], anchor: [12,41]} Any image file.
Default (omit icon) Standard Leaflet blue marker.

Additional icon options:

  • icon-color: color of the location-pin background icon behind icon-font markers; the glyph itself is white (default: "currentColor")
  • icon-size: base size in pixels for icon-font markers; scales both the white glyph and its location-pin background (default: 14)
  • icon-anchor: [x, y] anchor point override
  • markers-sep: field separator for markers-file (for example ",", "\t", "|")

5 Passthrough options

Any Leaflet Map option can be passed through. Options must be written in camelCase exactly as Leaflet expects them (e.g. scrollWheelZoom, zoomControl).

---
leaflet:
  map-options:
    center: [40.7128, -74.006]
    zoom: 14
    height: "400px"
    zoomControl: false
    scrollWheelZoom: false
    dragging: true
---

{{< leaflet map-options >}}

6 Custom tile layers

Specify a custom tile provider via the tile sub-object. See this demo or this for examples of tile provider URLs and attribution strings.

6.1 TopPlusOpen

---
leaflet:
  map-tile-topplus:
    center: [40.7128, -74.006]
    zoom: 11
    height: "400px"
    tile:
      url: "https://sgx.geodatenzentrum.de/wmts_topplus_open/tile/1.0.0/web/default/WEBMERCATOR/{z}/{y}/{x}.png"
      attribution: "Map data: &copy; <a href=\"https://www.govdata.de/dl-de/by-2-0\">dl-de/by-2-0</a>"
      maxZoom: 16
---

{{< leaflet map-tile-topplus >}}

6.2 CartoDB Voyager

---
leaflet:
  map-tile-cartodb:
    center: [40.7128, -74.006]
    zoom: 11
    height: "400px"
    tile:
      url: "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png"
      attribution: "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors &copy; <a href=\"https://carto.com/attributions\">CARTO</a>"
      maxZoom: 16
---

{{< leaflet map-tile-cartodb >}}

6.3 ESRI World Topo Map

{{< leaflet center="[40.7128, -74.006]" zoom=11 height="400px" tile='{"url":"https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}","attribution":"Tiles &copy; ESRI"}' >}}

7 Multiple maps

You can define multiple maps in the same document. Each map gets a unique ID automatically:

{{< leaflet center="[35.68, 139.69]" zoom=10 height="300px" >}}
{{< leaflet center="[-33.87, 151.21]" zoom=12 height="300px" >}}

See the repo README for full list of arguments.