Tutorial: Adding OpenStreetMap to your website!

Hello Publii developers!

I would like to share how to add an OpenStreetMap map to your website. Why? Well, because it took me much more time than expected and by sharing the code I hope it can save you a lot of time and frustration!

Let’s get started!

First thing you have to understand is that you can’t use OpenStreetMap directly but that you have to look for a provider that provides the images (tiles) of which an OpenStreetMap map is made. There are many providers and you can view a list of those providers here. I chose Mapbox because it is, as far as I know, one of the largest OpenStreetMap provider and because their tiles look very beautiful by default (IMHO).

Step 1: Create a Mapbox account

You can create a Mapbox account here.

Step 2: Follow the steps for adding Mapbox to your website

1. On the account page: choose Web.
2. Choose for ‘Use the Mapbox CDN’.
3. Add the JavaScript and stylesheet to the head of the website.I used the Starter theme and I had to insert the two lines in the head.hbs partial. Look in your theme directory for the relevant partial.
   Because I didn’t want this code to be loaded on every webpage I added a new variable (loadMapbox) to the post array in the config.json file. This way I can select in every post if the code should be loaded or not.
   config.json
   {
   “name”: “loadMapbox”,
   “label”: “Load Mapbox”,
   “value”: 0,
   “type”: “select”,
   “options”: [{“label”: “Enabled”,”value”: 1},{“label”: “Disabled”,”value”: 0}]
   },head.hsb{{#if @config.post.loadMapbox}}
   <link href=’https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.css&#8217; rel=’stylesheet’ />
   <script src=’https://api.mapbox.com/mapbox-gl-js/v1.8.0/mapbox-gl.js’></script&gt;
   {{/if}}
4. Add the HTML-code to a postThe only thing you have to add to a post is:

   I removed the width because the width of a block element is always 100 percent so it’s not necessary to mention this. I also added the id openstreetmap so I could add some custom CSS-code to it. The height of the element is, of course, completely up to you!

5. Create a new partial for all the custom JavaScript code
   Instead of adding the custom JavaScript code directly to the footer partial (footer.hbs), I created a new partial (mapbox.hbs) and added this to the footer partial. Why? Well, because the custom JavaScript can become (and will be) quite long and I didn’t want to create a mess in the footer partial.
   The complete code (in the footer partial) is:
   {{#if @config.post.loadMapbox}}
   {{> mapbox}}
   {{/if}}
6. Add the custom JavaScript code to the mapbox partial.The custom JavaScript code is:
   <script>mapboxgl.accessToken = ‘[YOUR ACCESS TOKEN]’;
   var map = new mapboxgl.Map({
   container: ‘map’,
   style: ‘mapbox://styles/mapbox/streets-v11’
   });
   </script>
7. Save all files and preview your post with Publii.If you have done everything correctly you should see an OpenStreetMap map in your post that points to somewhere at the east coast of Africa (probably the middle of the complete OpenStreetMap map?).

Because this is still quite boring I will explain in a second post how to further customize the OpenStreetMap/Mapbox map!