jekyll-map

A Jekyll plugin that adds a {% map %} Liquid tag for embedding static map images. No JavaScript required — just a responsive <img> tag. Supports both Mapbox and Google Static Maps as providers.

Installation

Add the gem to your Jekyll site's Gemfile:

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

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

plugins:
  - jekyll-map

Run bundle install to install the gem.

Configuration

Add a map: block to _config.yml. Set provider to mapbox (default) or google, and include credentials for whichever provider(s) you use.

map:
  provider: mapbox        # default provider: mapbox or google
  zoom: 13                # optional default zoom
  width: 800              # optional default width
  height: 400             # optional default height
  mapbox:
    token: pk.your_public_access_token_here
    style: streets        # optional: streets, satellite, outdoors, light, dark
  google:
    key: AIzaSy...
    style: roadmap        # optional: roadmap, satellite, terrain, hybrid

Usage

By latitude and longitude

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

By address string

Pass a quoted address string and the plugin geocodes it at build time using the active provider's geocoding API. Results are cached in _map_cache.json.

{% map "100 S Hill Street, Griffin, GA" zoom=15 %}

Override provider per tag

{% map lat=33.749 lng=-84.388 provider=google %}
{% map "City Hall, Atlanta, GA" provider=mapbox zoom=14 %}

Commit _map_cache.json

Commit _map_cache.json to your repo so CI builds don't re-geocode addresses on every run.

Parameters

All parameters are optional and override 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 marker at the center point
style	streets / roadmap	Map style (see below)
provider	config value	Override provider for this tag: mapbox or google
alt	"Map"	Alt text for the <img> tag

Mapbox styles

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

Google map types

Value	Description
roadmap	Standard road map (default)
satellite	Satellite imagery
terrain	Topographic map
hybrid	Satellite with road labels

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" %}

{% map "Griffin, GA" provider=google style=hybrid zoom=14 %}

Output

The tag renders a single <img> element:

<img src="https://api.mapbox.com/..." alt="Map" width="800" height="400" class="jekyll-map" loading="lazy">

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

.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.