jekyll-map 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee7f133aff0e9c08366d7fe4bec2747f457add3d2684288411bab98ad4d76414
+  data.tar.gz: b422a0a6bc9ac0cb0b56a0be45eddc990b471a8565928d0789d0897d51928a6f
+SHA512:
+  metadata.gz: 89f62d0c9fea41d42e255032cb06d49f65a60aa73ca253fac9cecd47478e4bfe1838ee3385bc68b621d8f1f6de31f5267b80462136339df699ebaa41c8eae443
+  data.tar.gz: 1233b2d685cf729cc464558b58b6fddc35e539fd03503c9c87cc74ad98ef1a777b604327c31933bb7a0d66a937e51852053062336f963999c80fa46061d9fa02

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-08-20
+
+### Added
+- Google Static Maps provider support (`provider: google`)
+- Google Geocoding API support for address-string geocoding with Google provider
+- Per-tag `provider=` override (e.g. `{% map lat=N lng=N provider=google %}`)
+- Google map types: roadmap, satellite, terrain, hybrid
+
+### Changed
+- Config block moved from `mapbox:` to `map:` with nested `mapbox:` and `google:` sections
+- `map.provider` sets the default provider (default: `mapbox`)
+
+### Upgrading from 0.1.0
+
+Replace your `_config.yml` `mapbox:` block:
+
+```yaml
+# Before (0.1.x)
+mapbox:
+  token: pk.xxx
+
+# After (0.2.x)
+map:
+  provider: mapbox
+  mapbox:
+    token: pk.xxx
+```
+
+## [0.1.0] - 2026-08-20
+
+### Added
+- Initial release
+- `{% map %}` Liquid tag for embedding Mapbox static map images
+- Latitude/longitude direct input
+- Address string geocoding via Mapbox Geocoding API with local cache (`_map_cache.json`)
+- Parameters: `zoom`, `width`, `height`, `marker`, `style`, `alt`
+- Map style aliases: streets, satellite, outdoors, light, dark
+- Config-level defaults via `mapbox:` block in `_config.yml`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Chance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# 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`:
+
+```ruby
+gem "jekyll-map", "~> 0.2"
+```
+
+Then add it to the `plugins` list in `_config.yml`:
+
+```yaml
+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.
+
+```yaml
+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
+
+```liquid
+{% 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`.
+
+```liquid
+{% map "100 S Hill Street, Griffin, GA" zoom=15 %}
+```
+
+### Override provider per tag
+
+```liquid
+{% 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
+
+```liquid
+{% 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:
+
+```html
+<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:
+
+```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](LICENSE.txt).

data/lib/jekyll/map_tag.rb

@@ -0,0 +1,230 @@
+require "jekyll"
+require "net/http"
+require "uri"
+require "json"
+require "cgi"
+
+module Jekyll
+  class MapTag < Liquid::Tag
+    # Mapbox
+    MAPBOX_STATIC_BASE  = "https://api.mapbox.com/styles/v1/mapbox/%s/static"
+    MAPBOX_GEOCODE_BASE = "https://api.mapbox.com/geocoding/v5/mapbox.places/%s.json"
+
+    MAPBOX_STYLE_ALIASES = {
+      "streets"   => "streets-v12",
+      "satellite" => "satellite-v9",
+      "outdoors"  => "outdoors-v12",
+      "light"     => "light-v11",
+      "dark"      => "dark-v11"
+    }.freeze
+
+    # Google
+    GOOGLE_STATIC_BASE  = "https://maps.googleapis.com/maps/api/staticmap"
+    GOOGLE_GEOCODE_BASE = "https://maps.googleapis.com/maps/api/geocode/json"
+
+    GOOGLE_MAPTYPE_ALIASES = {
+      "streets"  => "roadmap",
+      "roadmap"  => "roadmap",
+      "satellite" => "satellite",
+      "terrain"  => "terrain",
+      "hybrid"   => "hybrid"
+    }.freeze
+
+    DEFAULT_ZOOM     = 13
+    DEFAULT_WIDTH    = 800
+    DEFAULT_HEIGHT   = 400
+    DEFAULT_PROVIDER = "mapbox"
+
+    def initialize(tag_name, markup, tokens)
+      super
+      @raw_markup = markup.strip
+    end
+
+    def render(context)
+      site       = context.registers[:site]
+      map_config = site.config["map"] || {}
+      params     = parse_markup(@raw_markup)
+
+      provider = params["provider"] || map_config["provider"] || DEFAULT_PROVIDER
+
+      zoom   = (params["zoom"]   || map_config["zoom"]   || DEFAULT_ZOOM).to_i
+      width  = (params["width"]  || map_config["width"]  || DEFAULT_WIDTH).to_i
+      height = (params["height"] || map_config["height"] || DEFAULT_HEIGHT).to_i
+      marker = truthy?(params.fetch("marker", "true"))
+      alt    = params["alt"] || "Map"
+
+      case provider
+      when "google"
+        render_google(params, map_config, site, zoom, width, height, marker, alt)
+      else
+        render_mapbox(params, map_config, site, zoom, width, height, marker, alt)
+      end
+    end
+
+    private
+
+    # -------------------------------------------------------------------------
+    # Mapbox
+    # -------------------------------------------------------------------------
+
+    def render_mapbox(params, map_config, site, zoom, width, height, marker, alt)
+      mapbox_config = map_config["mapbox"] || {}
+      token = mapbox_config["token"]
+      raise "jekyll-map: map.mapbox.token is required in _config.yml" if token.nil? || token.strip.empty?
+
+      lat, lng = resolve_coordinates_mapbox(params, token, site)
+      raise "jekyll-map: could not resolve coordinates from markup: #{@raw_markup}" if lat.nil?
+
+      style = resolve_mapbox_style(params["style"] || mapbox_config["style"] || "streets")
+      url   = build_mapbox_url(lat, lng, zoom, width, height, marker, style, token)
+
+      img_tag(url, alt, width, height)
+    end
+
+    def resolve_mapbox_style(style)
+      MAPBOX_STYLE_ALIASES.fetch(style, style)
+    end
+
+    def resolve_coordinates_mapbox(params, token, site)
+      return [params["lat"].to_f, params["lng"].to_f] if params["lat"] && params["lng"]
+      return geocode_mapbox(params["address"], token, site) if params["address"]
+      [nil, nil]
+    end
+
+    def geocode_mapbox(address, token, site)
+      cache = load_cache(site)
+      return cache[address] if cache.key?(address)
+
+      encoded  = URI.encode_www_form_component(address)
+      uri      = URI.parse("#{format(MAPBOX_GEOCODE_BASE, encoded)}?access_token=#{token}&limit=1")
+      response = Net::HTTP.get_response(uri)
+      raise "jekyll-map: Mapbox geocoding failed (#{response.code}) for: #{address}" unless response.is_a?(Net::HTTPSuccess)
+
+      data     = JSON.parse(response.body)
+      features = data["features"]
+      raise "jekyll-map: no Mapbox geocoding results for: #{address}" if features.nil? || features.empty?
+
+      coords = features.first["center"] # [lng, lat]
+      result = [coords[1].round(6), coords[0].round(6)]
+      save_cache(site, cache.merge(address => result))
+      result
+    end
+
+    def build_mapbox_url(lat, lng, zoom, width, height, marker, style, token)
+      base    = format(MAPBOX_STATIC_BASE, style)
+      overlay = marker ? "pin-s+ff0000(#{lng},#{lat})" : "none"
+      if overlay == "none"
+        "#{base}/#{lng},#{lat},#{zoom}/#{width}x#{height}?access_token=#{token}"
+      else
+        "#{base}/#{overlay}/#{lng},#{lat},#{zoom}/#{width}x#{height}?access_token=#{token}"
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Google
+    # -------------------------------------------------------------------------
+
+    def render_google(params, map_config, site, zoom, width, height, marker, alt)
+      google_config = map_config["google"] || {}
+      key = google_config["key"]
+      raise "jekyll-map: map.google.key is required in _config.yml" if key.nil? || key.strip.empty?
+
+      lat, lng = resolve_coordinates_google(params, key, site)
+      raise "jekyll-map: could not resolve coordinates from markup: #{@raw_markup}" if lat.nil?
+
+      maptype = resolve_google_maptype(params["style"] || google_config["style"] || "roadmap")
+      url     = build_google_url(lat, lng, zoom, width, height, marker, maptype, key)
+
+      img_tag(url, alt, width, height)
+    end
+
+    def resolve_google_maptype(style)
+      GOOGLE_MAPTYPE_ALIASES.fetch(style, "roadmap")
+    end
+
+    def resolve_coordinates_google(params, key, site)
+      return [params["lat"].to_f, params["lng"].to_f] if params["lat"] && params["lng"]
+      return geocode_google(params["address"], key, site) if params["address"]
+      [nil, nil]
+    end
+
+    def geocode_google(address, key, site)
+      cache_key = "google:#{address}"
+      cache     = load_cache(site)
+      return cache[cache_key] if cache.key?(cache_key)
+
+      uri      = URI.parse("#{GOOGLE_GEOCODE_BASE}?address=#{URI.encode_www_form_component(address)}&key=#{key}")
+      response = Net::HTTP.get_response(uri)
+      raise "jekyll-map: Google geocoding failed (#{response.code}) for: #{address}" unless response.is_a?(Net::HTTPSuccess)
+
+      data    = JSON.parse(response.body)
+      results = data["results"]
+      raise "jekyll-map: no Google geocoding results for: #{address}" if results.nil? || results.empty?
+
+      loc    = results.first["geometry"]["location"]
+      result = [loc["lat"].round(6), loc["lng"].round(6)]
+      save_cache(site, cache.merge(cache_key => result))
+      result
+    end
+
+    def build_google_url(lat, lng, zoom, width, height, marker, maptype, key)
+      params = {
+        center:  "#{lat},#{lng}",
+        zoom:    zoom,
+        size:    "#{width}x#{height}",
+        maptype: maptype,
+        key:     key
+      }
+      params[:markers] = "color:red|#{lat},#{lng}" if marker
+      query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+      "#{GOOGLE_STATIC_BASE}?#{query}"
+    end
+
+    # -------------------------------------------------------------------------
+    # Shared helpers
+    # -------------------------------------------------------------------------
+
+    def parse_markup(markup)
+      params = {}
+      rest   = markup.dup
+
+      if rest =~ /\A["'](.+?)["']\s*(.*)\z/m
+        params["address"] = Regexp.last_match(1)
+        rest = Regexp.last_match(2)
+      end
+
+      rest.scan(/(\w+)=("([^"]*?)"|'([^']*?)'|(\S+))/) do |key, _full, dq, sq, bare|
+        params[key] = dq || sq || bare
+      end
+
+      params
+    end
+
+    def truthy?(val)
+      return true if val.nil?
+      !%w[false 0 no].include?(val.to_s.downcase)
+    end
+
+    def cache_path(site)
+      File.join(site.source, "_map_cache.json")
+    end
+
+    def load_cache(site)
+      path = cache_path(site)
+      return {} unless File.exist?(path)
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    def save_cache(site, cache)
+      File.write(cache_path(site), JSON.pretty_generate(cache))
+    end
+
+    def img_tag(url, alt, width, height)
+      %(<img src="#{url}" alt="#{CGI.escapeHTML(alt)}" width="#{width}" height="#{height}" class="jekyll-map" loading="lazy">)
+    end
+  end
+end
+
+Liquid::Template.register_tag("map", Jekyll::MapTag)

data/lib/jekyll-map/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module Map
+    VERSION = "0.2.0"
+  end
+end

data/lib/jekyll-map.rb

@@ -0,0 +1,3 @@
+require "jekyll"
+require_relative "jekyll-map/version"
+require_relative "jekyll/map_tag"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-map
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Jason Chance
+bindir: bin
+cert_chain: []
+date: 2026-08-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: jekyll-map adds a {% map %} Liquid tag to Jekyll sites. Pass a latitude/longitude
+  or an address string and get a responsive static map image with no JavaScript required.
+  Powered by the Mapbox Static Images API.
+email:
+- jason@jasonchance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-map.rb
+- lib/jekyll-map/version.rb
+- lib/jekyll/map_tag.rb
+homepage: https://jasonchance.com/projects/jekyll-map/
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A Jekyll plugin for embedding static Mapbox maps with a simple Liquid tag.
+test_files: []