jekyll-streetview 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 743ebb835ef743e70095829170a02e537746736999edc79e6af22471507b2c69
+  data.tar.gz: 7e5c3317298e49775e8d1daafc5e3582a6024958dd61c6286dc6e19aec82357f
+SHA512:
+  metadata.gz: cfeb9a0514872970f77718de17fb032d26de82efb890dcf22d46a4ca03ba6efdcb180fcece929e94f7e067c96aa18e334ce394c9ac165abb49fa2a32f247cacf
+  data.tar.gz: 2f9541d313802c8769ccb3e420fed4a686a801f4299cfca0632a61dbf397d0833db4b193514904953ae07a5d14e681fb1925b00d15e9689c092e0b10a5cd37ef

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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.1.0] - 2026-08-20
+
+### Added
+- Initial release
+- `{% streetview %}` Liquid tag for embedding Google Street View Static API images
+- Latitude/longitude direct input
+- Address string geocoding via Google Geocoding API with local cache (`_streetview_cache.json`)
+- Parameters: `width`, `height`, `heading`, `fov`, `pitch`, `radius`, `source`, `alt`
+- Config-level defaults via `streetview:` 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,116 @@
+# jekyll-streetview
+
+A Jekyll plugin that adds a `{% streetview %}` Liquid tag for embedding Google Street View static images. No JavaScript required — just a responsive `<img>` tag powered by the Google Street View Static API.
+
+## Installation
+
+Add the gem to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "jekyll-streetview", "~> 0.1"
+```
+
+Then add it to the `plugins` list in `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-streetview
+```
+
+Run `bundle install` to install the gem.
+
+## Configuration
+
+Add a `streetview:` block to `_config.yml` with your Google API key:
+
+```yaml
+streetview:
+  key: AIzaSy...
+  width: 800          # optional default width
+  height: 400         # optional default height
+  fov: 90             # optional default field of view
+  pitch: 0            # optional default pitch
+```
+
+Your Google API key must have the **Street View Static API** enabled. If you use address strings, it also needs the **Geocoding API** enabled.
+
+## Usage
+
+### By latitude and longitude
+
+```liquid
+{% streetview lat=33.248329 lng=-84.263336 %}
+```
+
+### By address string
+
+Pass a quoted address string and the plugin geocodes it at build time via the Google Geocoding API. Results are cached in `_streetview_cache.json`.
+
+```liquid
+{% streetview "100 S Hill Street, Griffin, GA" %}
+```
+
+### Commit `_streetview_cache.json`
+
+Commit `_streetview_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) |
+| `width` | `800` | Image width in pixels |
+| `height` | `400` | Image height in pixels |
+| `heading` | auto | Camera compass heading (0-360). If omitted, Google points toward the location. |
+| `fov` | `90` | Horizontal field of view in degrees (10-120). Lower = more zoom. |
+| `pitch` | `0` | Camera up/down angle (-90 to 90). Positive = up, negative = down. |
+| `radius` | `50` | Search radius in meters for nearest panorama |
+| `source` | — | Set to `outdoor` to exclude indoor panoramas |
+| `alt` | `"Street View"` | Alt text for the `<img>` tag |
+
+## Examples
+
+```liquid
+{% streetview lat=33.248329 lng=-84.263336 %}
+
+{% streetview "100 S Hill Street, Griffin, GA" heading=180 %}
+
+{% streetview lat=33.248329 lng=-84.263336 fov=60 pitch=10 heading=90 width=1200 height=500 %}
+
+{% streetview "City Hall, Atlanta, GA" source=outdoor alt="Atlanta City Hall" %}
+```
+
+## Output
+
+The tag renders a single `<img>` element:
+
+```html
+<img src="https://maps.googleapis.com/maps/api/streetview?location=33.248329%2C-84.263336&size=800x400&fov=90&pitch=0&radius=50&key=..." alt="Street View" width="800" height="400" class="jekyll-streetview" loading="lazy">
+```
+
+Add styles for `.jekyll-streetview` in your site's CSS:
+
+```css
+.jekyll-streetview {
+  width: 100%;
+  height: auto;
+  border-radius: 4px;
+}
+```
+
+## Note on imagery availability
+
+If Street View imagery is not available at the specified location, Google returns a gray placeholder image. Use a nearby address or adjust `radius` to find available coverage. You can check coverage in [Google Maps Street View](https://maps.google.com) before embedding.
+
+## 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/streetview_tag.rb

@@ -0,0 +1,126 @@
+require "jekyll"
+require "net/http"
+require "uri"
+require "json"
+require "cgi"
+
+module Jekyll
+  class StreetviewTag < Liquid::Tag
+    STREETVIEW_BASE = "https://maps.googleapis.com/maps/api/streetview"
+    GEOCODE_BASE    = "https://maps.googleapis.com/maps/api/geocode/json"
+
+    DEFAULT_WIDTH  = 800
+    DEFAULT_HEIGHT = 400
+    DEFAULT_FOV    = 90
+    DEFAULT_PITCH  = 0
+    DEFAULT_RADIUS = 50
+
+    def initialize(tag_name, markup, tokens)
+      super
+      @raw_markup = markup.strip
+    end
+
+    def render(context)
+      site   = context.registers[:site]
+      config = site.config["streetview"] || {}
+      key    = config["key"]
+
+      raise "jekyll-streetview: streetview.key is required in _config.yml" if key.nil? || key.strip.empty?
+
+      params = parse_markup(@raw_markup)
+
+      lat, lng = resolve_coordinates(params, key, site)
+      raise "jekyll-streetview: could not resolve coordinates from markup: #{@raw_markup}" if lat.nil?
+
+      width   = (params["width"]   || config["width"]   || DEFAULT_WIDTH).to_i
+      height  = (params["height"]  || config["height"]  || DEFAULT_HEIGHT).to_i
+      fov     = (params["fov"]     || config["fov"]     || DEFAULT_FOV).to_i
+      pitch   = (params["pitch"]   || config["pitch"]   || DEFAULT_PITCH).to_i
+      radius  = (params["radius"]  || config["radius"]  || DEFAULT_RADIUS).to_i
+      heading = params["heading"] ? params["heading"].to_i : nil
+      source  = params["source"]  || config["source"]
+      alt     = params["alt"] || "Street View"
+
+      url = build_url(lat, lng, width, height, fov, pitch, radius, heading, source, key)
+
+      %(<img src="#{url}" alt="#{CGI.escapeHTML(alt)}" width="#{width}" height="#{height}" class="jekyll-streetview" loading="lazy">)
+    end
+
+    private
+
+    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 resolve_coordinates(params, key, site)
+      return [params["lat"].to_f, params["lng"].to_f] if params["lat"] && params["lng"]
+      return geocode(params["address"], key, site) if params["address"]
+      [nil, nil]
+    end
+
+    def geocode(address, key, site)
+      cache_key = address
+      cache     = load_cache(site)
+      return cache[cache_key] if cache.key?(cache_key)
+
+      uri      = URI.parse("#{GEOCODE_BASE}?address=#{URI.encode_www_form_component(address)}&key=#{key}")
+      response = Net::HTTP.get_response(uri)
+      raise "jekyll-streetview: geocoding failed (#{response.code}) for: #{address}" unless response.is_a?(Net::HTTPSuccess)
+
+      data    = JSON.parse(response.body)
+      results = data["results"]
+      raise "jekyll-streetview: no 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_url(lat, lng, width, height, fov, pitch, radius, heading, source, key)
+      params = {
+        location: "#{lat},#{lng}",
+        size:     "#{width}x#{height}",
+        fov:      fov,
+        pitch:    pitch,
+        radius:   radius,
+        key:      key
+      }
+      params[:heading] = heading if heading
+      params[:source]  = source  if source && !source.empty?
+
+      query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+      "#{STREETVIEW_BASE}?#{query}"
+    end
+
+    def cache_path(site)
+      File.join(site.source, "_streetview_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
+  end
+end
+
+Liquid::Template.register_tag("streetview", Jekyll::StreetviewTag)

data/lib/jekyll-streetview/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module Streetview
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll-streetview.rb

@@ -0,0 +1,3 @@
+require "jekyll"
+require_relative "jekyll-streetview/version"
+require_relative "jekyll/streetview_tag"

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-streetview
+version: !ruby/object:Gem::Version
+  version: 0.1.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-streetview adds a {% streetview %} Liquid tag to Jekyll sites.
+  Pass a latitude/longitude or an address string and get a static Street View image
+  with no JavaScript required. Powered by the Google Street View Static API.
+email:
+- jason@jasonchance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-streetview.rb
+- lib/jekyll-streetview/version.rb
+- lib/jekyll/streetview_tag.rb
+homepage: https://jasonchance.com/projects/jekyll-streetview/
+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 Google Street View static images with a simple
+  Liquid tag.
+test_files: []