Why you should use qgis2web plugin + GitHub pages to produce interactive maps
We at Gispo are always looking for different ways to publish and visualize spatial data. Sometimes we encounter needs where the best way to accomplish this is to provide an interactive map that the end user can digest in the way they please. Most commonly these needs are related to work projects but this is not the whole truth…
In this article we’ll be looking at the possibilities of combining qgis2web QGIS plugin with GitHub Pages. These two together offer a simple way for creating an interactive and customised map to play with! With these tools you can minimize the implementation effort and focus rather on the style tuning and refining the data itself.
Why qgis2web?
qgis2web generates a web map from your current QGIS project. In the background the plugin utilizes either OpenLayers, Leaflet or Mapbox GL JS. qgis2web replicates as many aspects of the project as possible. In practice, the plugin will create a web map containing your layers, styles (including labels or categorized / graduated symbols) and extent.
Prepare your map as far as possible in QGIS, as you want it to appear in your web map <-> do not leave any extra layers hanging in the QGIS project! Specific tasks you can carry out to improve your web map include:
- Modifying the data you want to display by adding / removing objects in a layer or adding / removing attribute data column
- Use QGIS’s tools / algorithms to create new layers highlighting some property in your original “raw” data layer
- Configure style of your layers (symbols, labels, scale-dependent visibility..)
- Give your layers human-friendly names in the Layers panel
- Give your layer columns human-friendly names
- Hide the columns you don’t want to appear in your popups (but still don’t want to remove) by changing their Edit widget to “Hidden”
- If any of your fields contain image filenames, change their Edit widget to “Photo” to have the images appear in popups
- Set your project title, background and highlight colours
Installation procedure
Launch QGIS. In the upper menu bar select Plugins > Manage and Install Plugins… -> a pop-up window opens. Navigate to the All tab and type qgis2web into the search box:
After finding the correct plugin, just click Install Plugin button!
Usage
Run qgis2web from QGIS’s upper menu bar by navigating Web > qgis2web > Create web map, or via its icon. A new pop-up window should emerge. In the pop-up window’s right panel you will see a preview of your QGIS project as an interactive map. Notice that not all properties necessary show in the preview (e.g. highlight objects on hover).
The pop-up window’s left panel lets you set options separately for each layer. The pop up window’s bottom panel sets overall options for your project. Remember to click “Update preview” to see the effect of each choice. All options are written to your QGIS project, so save your project if you want to keep these settings. Since there is a bunch of decisions to make, here is a collection of screenshots representing the choices I made in order to create my interactive demo map:
Remember to set the path for saving the folder qgis2web plugin creates, before clicking Export button! After a successful export, the plugin automatically opens index.html file into browser. Check that the result satisfies you. If not, make alterations and export a new version of the interactive map.
Why GitHub pages?
GitHub is a very important and useful community to get involved in. First of all, Git/GitHub is a very popular version control system. GitHub has also a very useful feature called GitHub Pages, which allows you to publish website code live on the web. GitHub Pages are public web pages for users, organizations and repositories. GitHub Pages are freely hosted on GitHub’s github.io domain (or on a custom domain name of your choice).
You can store any code you like in a GitHub repository. In order to use the GitHub Pages feature to full effect, your code should be structured as a typical website, e.g. with the primary entry point being an HTML file called index.html.
Your site will be automatically generated by GitHub Pages when you push your source files. With GitHub Pages it is possible to just push generated HTML and you’re good to go without any further setup. In our case, we can use GitHub Pages for publishing the interactive map we just created with qgis2web plugin!
Usage
- If you do not yet have a GitHub account, please go and create one. It is completely free. Log in to your Github account and click on Your repositories in the upper right corner:
- Create a new repository by clicking the green New button:
Note that you can create this repository also under your organization if you wish:
While creating a repository you need to
- Provide a name for the repository
- Select whether this repository is going to be public or private (using GitHub pages on a private repository requires Pro version of GitHub)
In addition to this obligatory piece of information it is strongly recommended also to
- Provide a description of the repository
- Choose a licence for the repository
- Tick Add README file box
- Navigate to Settings > Pages. In here, choose main and /root ja press Save. In addition to that, select an appropriate theme for your GitHub pages (I chose Architect theme, but whatever pleases you):
- Modify README.md file by replacing the template text with your own text. Down below you can see a screenshot of my README. Note that .md files have its own syntax.
Commit your changes directly to the main branch:
- Add files to the repository by clicking Add file > Upload files button
and dragging all files from the exported qgis2web folder into the uploading area:
Note that you can drag and drop both individual files and complete folders!
Let the folder structure be as qgis2web plugin created it. You can again commit changes directly to the main.
- Rename index.html file into map.html by first opening the index.html file and then clicking on the pencil icon:
- Create a new file to the repository by clicking Add files > Create new file and setting its name to index.md. Below you can see a screenshot of my index.md. In this file you specify the content of the web page containing your interactive map.
Commit to the main branch and test whether anything appears in https://<github_user_name>.github.io/<repository_name>/
It might take a couple of minutes to update the changes so do not get worried if the link does not work right away after committing your latest changes.
End result
Repository: https://github.com/GispoCoding/demo_map
- In here you can find the source code and more information about the functionalities provided in the interactive demo map
GitHub page: https://gispocoding.github.io/demo_map/
- In here you can find more information about the data provided in the demo map
Map in the full view extent:
https://gispocoding.github.io/demo_map/map.html
Note that on the upper right corner you have a layer menu available:
Note also that by clicking a star symbol a pop up window with that particular pub’s attribute data emerges:
Now you know everything you need to know in order to create an interactive map of your choice!
Disclaimer
Inspiration for this map originated from free-time duties in organizing the bachelorette party; hence the content. The data set of pubs reflects only one subjective opinion on which pubs might be worth a visit (and why). The decisions on whether to include a certain pub into the custom data set or not are based on exhausting internet browsing.
