jekyll-map

A Jekyll plugin that adds a {% map %} Liquid tag for embedding static Mapbox map images. No JavaScript required — just a responsive <img> tag pointing to the Mapbox Static Images API.

Installation

Add the gem to your Jekyll site's Gemfile:

gem "jekyll-map", "~> 0.1"

Then add it to the plugins list in _config.yml:

plugins:
  - jekyll-map

Run bundle install to install the gem.

Configuration

Add a mapbox block to _config.yml with your Mapbox public access token:

mapbox:
  token: pk.your_public_access_token_here
  style: streets        # optional, default: streets
  zoom: 13              # optional, default: 13
  width: 800            # optional, default: 800
  height: 400           # optional, default: 400

Your Mapbox public token is safe to include in your Jekyll config — it is scoped to map tile requests and can be further restricted in the Mapbox dashboard.

Usage

Embed by latitude and longitude

{% map lat=33.749 lng=-84.388 %}

Embed by address

Pass a quoted address string and the plugin will geocode it via the Mapbox Geocoding API at build time. Results are cached in _map_cache.json to avoid repeated API calls on subsequent builds.

{% map "Downtown Decatur, GA" %}

Add _map_cache.json to version control

Commit _map_cache.json alongside your site to avoid re-geocoding addresses on every CI build:

# .gitignore — do NOT ignore this file
# _map_cache.json

Parameters

All parameters are optional and override the values in _config.yml.

Parameter	Default	Description
lat	—	Latitude (required if no address string)
lng	—	Longitude (required if no address string)
zoom	13	Map zoom level (0–22)
width	800	Image width in pixels
height	400	Image height in pixels
marker	true	Show a red pin at the center point
style	streets	Map style (see below)
alt	"Map"	Alt text for the <img> tag

Map styles

Value	Mapbox style
streets	streets-v12
satellite	satellite-v9
outdoors	outdoors-v12
light	light-v11
dark	dark-v11

You can also pass a full Mapbox style ID directly (e.g. style=mapbox/navigation-day-v1).

Examples

{% map lat=33.749 lng=-84.388 %}

{% map "City Hall, Decatur, GA" zoom=15 %}

{% map lat=33.749 lng=-84.388 style=satellite zoom=16 width=1200 height=500 %}

{% map "Atlanta, GA" marker=false style=light alt="Atlanta metro area" %}

Output

The tag renders a single <img> element:

<img src="https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/pin-s+ff0000(-84.388,33.749)/-84.388,33.749,13/800x400?access_token=pk...." alt="Map" width="800" height="400" class="jekyll-map" loading="lazy">

Add styles for .jekyll-map in your site's CSS as needed:

.jekyll-map {
  width: 100%;
  height: auto;
  border-radius: 4px;
}

GitHub Pages compatibility

This plugin is compatible with Jekyll sites deployed to GitHub Pages when the site is built through a custom GitHub Actions workflow.

It is not compatible with the default GitHub Pages safe-mode build, because custom plugins are not loaded there.

License

MIT License. See LICENSE.txt.