We're evolving to serve you better! This current forum has transitioned to read-only mode. For new discussions, support, and engagement, we've moved to GitHub Discussions.

Tutorial: Adding OpenStreetMap to your website!

  • #1908
    Avatar photo[anonymous]

    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.
      “name”: “loadMapbox”,
      “label”: “Load Mapbox”,
      “value”: 0,
      “type”: “select”,
      “options”: [{“label”: “Enabled”,”value”: 1},{“label”: “Disabled”,”value”: 0}]
      <link href=’; rel=’stylesheet’ />
      <script src=’’></script&gt;
    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:
      {{> mapbox}}
    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’
    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!

    Avatar photo[anonymous]

    The forum software removed the HTML code :-|.

    The HTML code should be:

    bracket      div id=’openstreetmap’ style=’height: 420px’        bracket

    Avatar photo[anonymous]

    I’m going to write a little but more ‘staccato’ because otherwise writing this tutorial is going to take me too much more time.

    Avatar photo[anonymous]

    Zooming in a particular location

    Add the option center to the map object.

    `var map = new mapboxgl.Map({
    container: ‘openstreetmap’,
    style: ‘mapbox://styles/mapbox/streets-v11’,
    center: [longitude, latitude],
    zoom: 15

    You can find the longitude and latitude of your location by using the Mapbox Playground.

    You can find the Mapbox Playground here:

    Search for your location and click once on the button Toggle JSON panel (in the top right of the website).

    Avatar photo[anonymous]


    Add a zoom in and a zoom out button.


    Add the controls.


    `map.addControl(new mapboxgl.NavigationControl({showCompass: false}), ‘top-right’);`


    Because I didn’t want the see the compass I added ‘showCompass:false’ to the NavigationControl function. With the last argument you set the location of the controls (‘top-right’).

    Avatar photo[anonymous]


    Add a satellite view.


    Add the correct HTML, CSS and JavaScript code :-).

    HTML code

    ` `
    ` ` ` ` ` `
    ` `

    CSS code

    `#openstreetmap {`
    `position: relative;`

    `#mapbox-menu {`
    `position: absolute;`
    `background: #fff;`
    `padding: 10px;`
    `color: #000;`
    `z-index: 99;`

    JavaScript code


    Avatar photo[anonymous]

    Sorry, I’m giving up!

    I can’t work with this WordPress forum!

    It constantly makes a mess of what I’m writing 🙁 !

    And who in the world thought it was a good idea to create a new paragraph every time you press enter???? Biggest UI mistake ever!!!

    Avatar photo[anonymous]

    [anonymous] you can delete this thread.

    Avatar photoBob

    Why do you not insert a code by the dedicated option?


    Ps: Please prepare this tutorial in Google docs, then I will publish it in our documentation.

    Avatar photo[anonymous]

    I don’t have that option in the top bar.
    I use Shift + Alt + X but every time it works differently.
    I’m on Fedora 31 and Firefox 73.

    Avatar photo[anonymous]

    When I use GNOME Web (WebKit), the option is also not shown.

    Avatar photoBob

    I thought it is enabled, I found a solution and now it should work for a “normal” users too.

    Avatar photo[anonymous]

    I can confirm: it’s now shown in Firefox and GNOME Web!

    Avatar photo[anonymous]

    Please don’t give up Verhoeckx! I am sure many of us are very much interested

    in a non-g**gle solution 🙂

    But take your time, No reason to stress.


    Avatar photo[anonymous]

    Hello Bert,

    Thanks 🙂 !

    I will write a new tutorial (somewhere in the coming weeks) and send it to Bob so he can add it to the documentation!


    Avatar photo[anonymous]

    A big thank you to @Verhoeckx for persisting, and @Bob for publishing in the Publii documentation. @Verhoeckx’s final tutorial looks like it could be really good!

    Avatar photo[anonymous]

    Hello! Where has the full tutorial been published? 🙂

    Avatar photo[anonymous]

    Here it is (see attachment)!