Hugo Maps

Beautiful Maps for Hugo #

hugo-maps is a Hugo module that allows you to easily add beautiful maps to your Hugo site. It uses MapLibre GL JS to render vector maps.

You can either use a commercial map server (e.g., Maptiler) or a self-hosted map server (e.g., Tileserver GL) to generate the vector map tiles.

You can go to the examples or look at the included themes.

Features #

  • 🌍 High-quality interactive vector maps.
  • 🎨 Comes with lots of styles. You can also use your own custom style if you want.
  • 🅰️ Glyphs for all included styles are included in the module.
  • 📍 Support for custom markers.
  • 💾 Supports download of vector tiles at deploy time (no external API calls at runtime).

Local maps are currently not supported, pending minor changes to Hugo’s template engine.

Getting Started #

1. Add the module to your site #

Add the following to your site’s config file:

module:
  imports:
    - path: github.com/marcpabst/hugo-maps

2. Add a tile source #

You need to add a tile source to your site’s config file. You can either use a commercial tile server (e.g., Maptiler) or a self-hosted tile server. If you want to use Maptiler, you need to register for an account and get an API key.

Add the URL of the tile server to your site’s config file (you can also do this on a per-map basis):

params:
  hugo-maps:
      default:
        tileJSON: https://api.maptiler.com/tiles/v3/tiles.json?key={key}

3. Define a map and add it to your site #

You can define a map in your site’s config file. The following example defines a map named my_map:

params:
  hugo-maps:
    default:
        tileJSON: https://api.maptiler.com/tiles/v3/tiles.json?key={key}
    my_map:
        center: [0, 0]
        zoom: 2

You can add a map to your site by using the map shortcode and the name argument:

{{< map name="my_map" >}}

Optionally, you can override the default configuration for the map by passing additional arguments to the shortcode. For example, you can change the height of the map by passing a height argument.

{{< map name="my_map" height="350px" >}}

Configuration #

Maps are configured using the hugo-maps parameter in your site’s config file. A map is defined by a unique name and a configuration. The default configuration is used for all maps unless you override it for a specific map.

params:
    hugo-maps:
        default:
            ... default configuration ...
        my_map:
            ... configuration for "my_map" ...

Here are the available configuration options with their default values:

style: osm-bright # theme to use
type: remote # type of map, either remote or local
tilesMinZoom: # minimum zoom level for local maps
tilesMaxZoom: # maximum zoom level for local maps
center: [-0.127758, 51.507351] # center of the map
minZoom: 0 # minimum zoom level
maxZoom: 23 # maximum zoom level
zoom: 11 # initial zoom level
minPitch: 0 # minimum pitch
maxPitch: 60 # maximum pitch
pitch: 0 # initial pitch
bearing: 0 # initial bearing
antialias: false # whether to use antialiasing
width: 100% # width of the map
height: 300px # height of the map
attributionControl: true # whether to show attribution
customAttribution: "" # custom attribution
interactive: true # whether the map is interactive
navigationControl: true # whether to show navigation controls

Examples #

All examples use the following default configuration. You can override this configuration for each map. Please note that to use Maptiler’s tile sever, you need to register for an account and get an API key.

params:
  hugo-maps:
      default:
        tiles: https://api.maptiler.com/tiles/v3/{z}/{x}/{y}.pbf?key={key}

Example 1: Custom map center # 

params:
  hugo-maps:
    new_york_map:
        center: [-74.005833, 40.712778]

Example 2: Styling the map # 

params:
  hugo-maps:
    my_london_map:
        style: toner
        center: [-0.127758, 51.507351]

Example 3: 3D map with marker # 

params:
  hugo-maps:
    my_london_map:
        type: local
        style: maptiler-3d
        center: [-0.127758, 51.507351]
        tilesBoundingBox: [0.49956765, 0.3325506204915718, 0.4997617583333333, 0.3323975306107756]
        tilesMinZoom: 0
        tilesMaxZoom: 15
        minZoom: 4
        maxZoom: 24
        zoom: 14
        pitch: 45
        antialias: true
        markers:
          - location: [-0.127758, 51.507351]
            text: 'Welcome to London'

Openmaptiles Styles #

OSM-Bright (osm-bright) #

MapTiler Basic (maptiler-basic) #

MapTiler 3D (maptiler-3d) #

Toner (toner) #

Positron (positron) #

Fjord Color (fjord-color) #

Darkmatter (darkmatter) #

Custom Styles #

Ordnance Survey’s OS Open Zoomstack covers the whole of Great Britain. It is not compatible with the OpenMapTiles styles. However, you can create a custom style using the Maputnik editor. You can even combine the OS Open Zoomstack with the OpenMapTiles sources.

CVL 3D (cvl-3d) #

License #

This project is licensed under the MIT License - see the LICENSE file for details. OpenMapTiles styles are licensed under the BSD 3-Clause License. Please make sure that you comply with the license of the map tiles you use.