Hello! 👋

This is a rehab of a map I created in 2013 using TileMill. For many years this was hosted via my Mapbox account and displayed here, but support from Mbtiles 1.0 was deprecated in 2020, with no easy path to update. I also had no incentive really to keep this map from early in my career live on the internet, so I let it die and archived my ancient blog, including the dead links.

Recently I became curious whether I could create a similar workflow without relying on Mapbox hosting or any paid hosting. The answer is, yes I can! The rebuilt version as 3 key technical dependencies and one optional one:

1. PMTiles - for storing my GIS analysis in a web-suitable format
2. Maplibre JL JS - for rendering my map and adding interactivity
3. Github Pages - for hosting all components of my web map, including the PMTiles
4. (Optional) Stadia Maps - for providing me with easy-to-customize reference layers for context (regional land/water/roads/labels) via a stylesheet and OpenMapTiles. Free so long as I stay below 200,000 credits / month. I'm calling this optional because it was included in my original project, but I probably don't need it.

This documentation is for those with no front-end development experience. That is, no prior knowledge of HTML, Javascript, or coding in general is required or assumed to follow the steps below.

Skills assumed in this guide:

• Ability to install and use commandline tools, I'll provide some but not complete details for how I did it on an a M1 MacBook Air
• Basic knowledge of GIS tools, e.g. coordinate systems, raster versus vector data
• Ability to create a repo on Github and use basic Git commands to work with it locally
• Ability to use a plain-text code editor, such as VS Code
• Familiarity with how Mapbox / MapLibre stylesheets work.

If you are less confident with any of these skills and have questions, please don't hesitate to ask. I didn't include many details here because there are good guides elsewhere and lots of options.

Steps to create

1. Update MBTILES First I had to deal with a spec issue: MBtiles version 1.0 did not include format=png in the metadata because back then, MBTiles was only for rasters. These days the conversion tools need you to specify this attribute, otherwise they assume your data is in a vector format (much more common these days). For this I used mbtiles, a commandline utility with binaries downloadable here. Once installed, the command is just: mbtiles meta-set INPUT.mbtiles format png, where INPUT is the name of the file. View the metadata stored in the archive, or check it before and after with this command: mbtiles meta-all INPUT.mbtiles
2. Convert to PMTILES Now I can use the PMTiles commandline tool to convert MBTiles to PMtiles. This I installed via Homebrew (brew install pmtiles) and then ran this command: pmtiles convert INPUT.mbtiles OUTPUT.pmtiles.
3. Upload to Github / Enable Github Pages Follow the instructions here. As long as your PMTiles file size is under 1 GB this is just a matter of creating a repo or adding to an existing one. Obviously I created this repo for the purpose.
4. Create an HTML page to show your map via the Maplibre PMTiles extension Here is the example I used as a starting point. Can be as simple as duplicating this file and plugging in the Github Pages link to the PMTiles file. Name it index.html and add it to your Github repo, and voila! It should work. But, for the sake of any next steps, you should really test it locally. This is the hardest part if you don't have front-end development experience. I use VS Code with a Live Server extension, but you can use anything that edits plain text and you can set up a local server to test everything from your desktop computer via Node or Python if those are installed on your computer.
5. Add reference layers In the original project I used a Mapbox base map to provide context around this analysis, e.g. to show San Francisco in the larger regional context of the San Franciso Bay Area. Here I grabbed a stylesheet from Stadia Maps, which allows me to style some default reference layers hosted by Stadia and built based on OpenMapTiles, and added it to my repo. I turned off a bunch of labels I don't want to see (via visibility=none, but really I could just delete them from the JSON) and then integrated the layers around my data by (a) adding in the PMtiles as a source in the stylesheet and then (b) adding a style layer where I want it to render, i.e. after or on top of all the land and water features, but before or under the labels I didn't suppress. Here's how to start with a Stadia Maps basemap style and customize it. Stadia recommends using Maputnik to customize your stylesheet. If you have local testing set up, you can also just download and edit the JSON right in your text editor.
6. Add tooltip data Zooming in and out is nice, but it isn't really a web map unless you can search, click, or hover. In the original TileMill project, there was an option to add tooltips, so this project included a tooltip that showed how many full-time jobs you'd need to afford a one bedroom apartment on average in each neighborood. Here I used a vector data source. I had an old Shapefile that contained the analysis, but it was projected as California FIPS II NAD84. I used QGIS to convert it to unprojected coordinates, WGS84 datum, since that's what webmapping libraries generally expect, and then added it to my repo.
7. Add interactivity I used Maplibre JS to create the interactivity. This definitely requires setting up a local server if you haven't done so already, primarily because the order of operations (e.g. asynchronously loading the data from various sources and rendering it) gets tricky.