Safe chars and maplibre examples (#85)

* add details on file name limitation to s3 safe characters.

* bump basemap package version to 4.3

* add additional maplibre links and global maxzoom example

basemaps/maplibre.md

@@ -80,7 +80,7 @@ the default export from `protomaps-themes-base` is a function that takes 2 argum
 Loading the `protomaps-themes-base` package from NPM will define the `protomaps_themes_base` global variable.
 
 ```html
-<script src="https://unpkg.com/protomaps-themes-base@3/dist/protomaps-themes-base.js" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/protomaps-themes-base@4/dist/protomaps-themes-base.js" crossorigin="anonymous"></script>
 ```
 
 ```js

deploy/aws.md

@@ -13,9 +13,9 @@ At the end of this walkthrough, you'll have a CDN-cached ZXY API, compatible wit
 
 ### 1. Upload to S3
 
-The CloudFormation template is designed to work with an existing S3 bucket.
+The CloudFormation template is designed to work with an existing S3 bucket. File names must include only [S3 safe characters](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines).
 
-If you need to create a new one:
+If you need to create a new bucket:
 
 * Open the [S3 Console](https://s3.console.aws.amazon.com/s3/home) and choose **Create Bucket**.
 * Choose a globally unique bucket name, and any region, just remember the **region name.**

deploy/azure.md

@@ -4,7 +4,7 @@ PMTiles can be served from a [Azure Container App]() using the [go-pmtiles Docke
 
 ## Blob Storage
 
-PMTiles should stored in a [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs) container.
+PMTiles should stored in a [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs) container. File names must include only [S3 safe characters](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines).
 
 Make note of the **Storage Account Name**, region and **container name** (e.g. `main`) for the below steps.
 

deploy/cloudflare.md

@@ -21,7 +21,7 @@ Use [rclone](/pmtiles/cloud-storage#uploading) to upload larger PMTiles archives
 
 This requires a token from **R2 > Manage R2 API Tokens**. Note **Access Key ID**, the **Secret Access Key** and the **Endpoint for S3 Clients** from the API key creation screen. The S3-compatible endpoint should look like: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`.
 
-Name your uploads to storage with the `.pmtiles` extension. Your tile requests to the Workers URL will look like `/NAME/0/0/0.<mvt | png>` or `/NAME.json` ([TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/3.0.0)) for the archive `NAME.pmtiles`.
+Name your uploads to storage with the `.pmtiles` extension. Your tile requests to the Workers URL will look like `/NAME/0/0/0.<mvt | png>` or `/NAME.json` ([TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/3.0.0)) for the archive `NAME.pmtiles`. File names must include only [S3 safe characters](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines).
 
 ### 2. Manual Option: Create Worker with Web Console
 

deploy/google-cloud.md

@@ -18,7 +18,7 @@ If you need to create a new Bucket:
 
 5. Uncheck **Data Protection > Soft Delete Policy**.
 
-6. Upload a sample PMTiles into your bucket.
+6. Upload a sample PMTiles into your bucket. File names must include only [S3 safe characters](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines).
 
 ## Creating a Cloud Run container
 

guide/getting-started.md

@@ -50,9 +50,15 @@ pmtiles extract https://build.protomaps.com/{{ dateNoDashes }}.pmtiles my_area.p
 
 > **Note:** You can find the bounding box of your own area, using tools, such as [http://bboxfinder.com/](http://bboxfinder.com/#51.830755,4.742883,52.256198,5.552837)
 
+We can also create a subset of the whole planet that is only zoom levels 0 to 6 and ~60 MB:
+
+```bash-vue
+pmtiles extract https://build.protomaps.com/{{ dateNoDashes }}.pmtiles planet_z6.pmtiles --maxzoom=6
+```
+
 ## 4. View the basemap
 
-[maps.protomaps.com](https://maps.protomaps.com) is a viewer for basemaps. Drag our file `my_area.pmtiles` onto the `Drop Zone` to view the map:
+[maps.protomaps.com](https://maps.protomaps.com) is a viewer for basemaps. Drag our file `my_area.pmtiles` or `planet_z6.pmtiles` onto the `Drop Zone` to view the map:
 
 ![utrecht image](./utrecht.png)
 

package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "maplibre-gl": "^4.7.1",
     "pmtiles": "^3.2.0",
-    "protomaps-themes-base": "4.1.0",
+    "protomaps-themes-base": "4.3.0",
     "vitepress": "^1.0.0-rc.15"
   },
   "devDependencies": {

pmtiles/maplibre.md

@@ -5,6 +5,10 @@ outline: deep
 
 # PMTiles for MapLibre GL
 
+PMTiles is designed to be read directly in the browser by the MapLibre GL renderer, for either thematic overlay tilesets or basemap tilesets.
+
+For a guide on integrating the Protomaps basemap tileset into MapLibre GL, see [Basemaps for MapLibre](/basemaps/maplibre).
+
 ## Installation
 
 For reading PMTiles directly from cloud storage, you'll need the `pmtiles` JavaScript library.
@@ -87,3 +91,7 @@ Protomaps also distributes terrain tilesets in the [Terrarium RGB encoding](http
   }
 }
 ```
+
+## Next Steps
+
+* Integrating [Basemap Styles](/basemaps/maplibre) into MapLibre