From 9d463e29102910f101d14ce35e6832247b99d5eb Mon Sep 17 00:00:00 2001
From: Fraser Crichton <fraser.crichton.developer@gmail.com>
Date: Tue, 7 Apr 2020 17:43:07 +1200
Subject: [PATCH] Doco for adding a custom Mapbox map

---
 docs/mapbox.md    | 38 ++++++++++++++++++++++++++++++++++++++
 example.config.js |  1 +
 2 files changed, 39 insertions(+)
 create mode 100644 docs/mapbox.md

diff --git a/docs/mapbox.md b/docs/mapbox.md
new file mode 100644
index 0000000..df736dc
--- /dev/null
+++ b/docs/mapbox.md
@@ -0,0 +1,38 @@
+
+# Timemap and custom Mapbox maps
+
+You can use satellite images and maps from [https://www.mapbox.com/](https://www.mapbox.com/) to customise the map in Timemap. 
+
+Sign up for an account at [https://www.mapbox.com/](https://www.mapbox.com/) and use Mapbox's studio to create a custom map. To use the map you need to configure Timemap with the following: 
+
+## Token
+
+To access your Mapbox account Timemap needs an access token that you create under your Mapbox account. 
+
+Sign in to Mapbox and then navigate to: 
+
+Account > Access Tokens 
+
+* Create a Token - add a token and optionally restrict it to the url of your timemap instance.
+* Add it to Timemap - copy the token and then add it to Timemap's `config.js` at the top level:
+
+ ```
+  MAPBOX_TOKEN: 'mapbox_token',
+ ```
+
+Timemap can now access your account but you need to associate any maps you want to use with that account using Mapbox Studio. Once you have done that you can then reference the Mapbox Map id.
+
+## Mapbox Map Id
+
+To reference a map you have created in Mapbox Studio you need the map's id which is available under 'share' > 
+
+* Style URL (which looks like this: `mapbox://styles/your-mapbox-account-name/x5678-map-id`)
+
+Now go back to `config.js` and under the UI settings add (don't copy the 'mapbox://styles/' bit): 
+
+```
+   ui: {
+      tiles: 'your-mapbox-account-name/x5678-map-id',
+``` 
+
+If you restart your time map instance you should now see the Mapbox map.
diff --git a/example.config.js b/example.config.js
index 3c8661b..0b52ed2 100644
--- a/example.config.js
+++ b/example.config.js
@@ -35,6 +35,7 @@ module.exports = {
         shapes: {},
         narratives: {},
         selectedEvent: {}
+        // tiles: 'your-mapbox-account-name/x5678-map-id'
       }
     }
   }