Adding Maps to Hugo with uMap and OpenStreetMap

I needed to put a map on an article I was writing. Specifically, I wanted to overlay some information on top of an existing street map. The terms of service for Google Maps were too punitive and could potentially lead to me paying to use the service, but a quick search on the internet revealed another map service - OpenStreetMap.

OpenStreetMap, or OSM for short, is free to use and to embed maps in websites, so long as attribution is given to OpenStreetMap and any contributors. It is constantly enhanced by a community of mappers and engineers and there are many different overlays available - from bicycle routes, to transport links, to aerial imagery.

There is a further service - uMap - which lets you create custom maps using the OSM layers.

Creating a Map with uMap and OSM

Let’s get started building a map and embedding it…

I’m going to build a map of a coffee trail in Melbourne’s CBD as an example for this article.

Creating a Login

Although it is possible to create a map in uMap without having a login, it means anyone with the link will be able to edit it. Having a login means the map owner can choose who can edit the map.

• Navigate to https://umap.openstreetmap.fr/en/.

• Click the Log In / Sign In link at the top of the page to reveal the login popup.

Login options for uMap - Github, Bitbucket, Twitter, OpenStreetMap

• The login options for uMap are pretty limited. Unless you have a Github, Bitbucket or Twitter account, the best one to choose is OpenStreetMap.
  • An OSM login allows you to also contribute to OpenStreetMaps.
  • OSM has many additional login options - including Google, Facebook, Yahoo! and WordPress.

Login options for OpenStreetMap

• I chose to create an OSM login and use that to access uMap. Clicking on the OSM icon in uMap asks you to log in to OSM and then to grant access to uMap from your OSM account. Click the Grant Access button to proceed.

Creating a Map

To start creating a map, click the Create a map button on the top right of the uMap main page. This navigates to a new page displaying the map and editing controls. The uMap controls and editor are surprisingly easy to use - much easier than the editing tools available through OSM itself.

Map editing controls in uMap

• Give your new map a name by clicking on the existing Untitled map name. The name will be used later to include the map in a page in Hugo and is also used to open the map for future edits in uMap, so make sure it is named appropriately, especially if you end up creating a lot of maps over time; it will make them easier to locate in your uMap account.

• Choose a default location for your map by clicking the magnifying glass search control on the left-hand controls and entering a location. You can force uMap to open at this location later.

• Set the default zoom level by clicking the plus/minus controls, also located in the left-hand controls.

• Next, on the right-hand controls, click the Save map centre and zoom control (the icon with 2 arrows pointing at a dot). This will set the map location and zoom level, so whenever it is opened in future it will be positioned in the correct place.

• Finally (for now), set the tile layer for the map by clicking the Change tilelayers control on the right-hand set of controls (the icon that looks like sheets of paper on top of each other, highlighted in red, below). The tile layer is the layer you wish to use as the base for your map. Lots of different options exist - cycle paths, public transport maps, terrain, aerial images - there is even a watercolour painting version! I chose OSM Light (jawgmaps) for my example because the tile layer is not too prominent.

• After picking a tile layer, scroll up to the top of the tile layers and click the Close button to hide the control.

Changing the tile layer in uMap

• It is a good idea to click the Save button at the top right-hand side of the screen at this point. Further editing can be done later, as required.

Adding to the Map

For my example, I’m going to put markers on cafes I like, with a suggested walking path between them. The distance between each cafe should not be too great and cafes. Each cafe will have a link to Beanhunter, so readers can see reviews of the cafe.

• To add a marker on the map, click the Draw a marker control, which changes the mouse icon to crosshairs.

• Click on the location where you want the marker to appear. Don’t worry if it is not exactly right - it is easy to click on the marker to drag it around later.

• Give the marker a name, which will display on the map.

• Add a description if required. In my example, I want readers to be able to click on a marker and then access Beanhunter reviews for that cafe, so I put a link into the description field as shown below.

Adding a marker with a clickable link in uMap

Various options are available for customising the marker:

• In Shape Properties, Colour, Icon shape and Icon symbol can all be set. Note that Icon symbol only displays if Icon shape is left as Default. In my example, I want to change the Icon shape to Ball, which will display like a dropped pin on the map.

• Under Interaction options it is possible to set how users can interact with the marker. The Display label option can be set to display always, never, or on hover and the Label direction can be defined. The Popup shape can be set as either a Popup or to display in a Side panel. For my example, I want the labels to always display with the cafe name and clicking on the pin will result in a link to the cafe on Beanhunter being displayed.

To add a line between two points,

• Click the Draw a polyline control, just below the Draw a marker control. The mouse will change to crosshairs.

• Set the crosshairs where you want the line to start and then click the mouse to set the first point on the line.

• Move around the map and click each subsequent point where you want the line to go; the lines will draw straight. Don’t worry if you make a mistake, the lines can be adjusted at a later time.

• When you have reached the point where you want your line to end, double-click the mouse to finish off the line; the crosshairs will turn back to a normal mouse cursor.

Similar customisation options are available for polylines, as they are for markers. I did not set any customisation of the line in my example map.

Finishing off - View and Edit Settings

It is always good to validate the viewing and editing settings to make sure the map has the security you want applied to it, even if you end up leaving the map with its default settings.

• Click the Edit map settings control (the cog icon) on the right-hand controls to edit your map settings. This displays a side panel menu.

• Click on the User interface options button to display what controls you want to make available to people when viewing the map. I chose to set all options to never, other than the zoom controls.

• The Limit bounds button allows you to set how far out the people viewing your map can zoom, or whether they can search and display other locations on the map. For my map, I wanted to limit them to the Melbourne CBD only. This is done by zooming out as far as you want to allow viewers to go and then clicking the Use current bounds button to set the coordinate limits of the map.

• Click the Credits button to display the licence and credits which will be displayed on the bottom right corner of the map. Although it is not possible to change the licence, you can credit yourself with a link to your website, using the following syntax to add a URL link:

  [[https://<your site URL>|<display text>]]
  
  

• Next, click the Permission settings control (the key icon) in the right-hand controls to update the permission settings on the map.

• Choose what view permissions you want for your map. I chose to allow anyone with the link to view the map, as I would be providing the link in my blog to allow it to be viewed.

• Finally set the edit permissions. For editing, I left the default for my map, which was to only allow the owner to edit the map.

• Remember to save your map when you are finished!

Including a Map in Hugo

Kudos to Hanzei, who produced the OSM theme for Hugo, allowing uMaps to be easily included in Hugo sites.

• To include a map, the OSM theme first needs to be included in your Hugo site. The easiest way to do this is to link a submodule into your site. That way, you can update to get future enhancements to the theme.

  $ git submodule add https://github.com/Hanzei/hugo-component-osm.git themes/osm
  

• Next, the OSM theme needs to be linked in to your Hugo installation, within the config.toml or config.yaml file. The below example is for a config.toml file.

theme = ["osm", "<your other themes>"]

• Now, you are able to link your uMap maps into your Hugo blog articles, using the following shortcode (replacing <your map name> with an actual map name).

 
{{< openstreetmap mapName="<your map name>" >}}

Note that even though you may specify map interaction settings in uMap, the OSM theme in Hugo does not respect them, so they need to be additionally specified in the shortcode when you embed your map. In my example, I want the search, tile layers, embed control and data layers all to be hidden, so my shortcode looks like this:

 
{{< openstreetmap mapName="<your map name>" searchControl="false" datalayersControl="false" embedControl="false" tilelayersControl="false" moreControl="false" >}}

Here is my finished Melbourne CBD coffee trail map:

A big thank you must go to Divinerites and Hanzei for their work on using OSM in Hugo and the OSM theme for Hugo. Their work makes it very easy to include maps in Hugo and has made this blog article possible.