diff --git a/doc-pages/src/constants/pages.js b/doc-pages/src/constants/pages.js
index 05be5281..6a75a913 100644
--- a/doc-pages/src/constants/pages.js
+++ b/doc-pages/src/constants/pages.js
@@ -30,19 +30,40 @@ const docPages = {
paths: generatePath([
{
name: 'Overview',
+ children: [
+ {
+ name: 'Overview',
+ content: getDocUrl('README.md')
+ },
+ {
+ name: 'What\'s New',
+ content: getDocUrl('whats-new.md')
+ },
+ {
+ name: 'Upgrade Guide',
+ content: getDocUrl('upgrade-guide.md')
+ }
+ ]
+ },
+ {
+ name: 'Getting Started',
children: [
{
name: 'Get Started',
content: getDocUrl('get-started/README.md')
},
{
- name: 'What\'s New',
- content: getDocUrl('get-started/whats-new.md')
+ name: 'Using with Redux',
+ content: getDocUrl('get-started/using-with-redux.md')
},
{
- name: 'Upgrade Guide',
- content: getDocUrl('get-started/upgrade-guide.md')
+ name: 'Using with Isomorphic Rendering',
+ content: getDocUrl('get-started/using-with-isomorphic-rendering.md')
},
+ {
+ name: 'About Mapbox Tokens',
+ content: getDocUrl('get-started/mapbox-tokens.md')
+ }
]
},
{
@@ -70,6 +91,23 @@ const docPages = {
},
]
},
+ {
+ name: 'Overlays',
+ children: [
+ {
+ name: 'SVGOverlay',
+ content: getDocUrl('overlays/svg-overlay.md')
+ },
+ {
+ name: 'CanvasOverlay',
+ content: getDocUrl('overlays/canvas-overlay.md')
+ },
+ {
+ name: 'HTMLOverlay',
+ content: getDocUrl('overlays/html-overlay.md')
+ },
+ ]
+ },
{
name: 'Util Functions',
children: [
diff --git a/docs/README.md b/docs/README.md
index bbe91f81..311aa2a3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,6 @@
-React friendly API wrapper around MapboxGL JS
+# Overview
+
+react-map-gl is a react friendly API wrapper around MapboxGL JS.
diff --git a/docs/get-started/about mapbox-tokens.md b/docs/get-started/mapbox-tokens.md
similarity index 100%
rename from docs/get-started/about mapbox-tokens.md
rename to docs/get-started/mapbox-tokens.md
diff --git a/docs/get-started/using-with-isomorphic-rendering.md b/docs/get-started/using-with-isomorphic-rendering.md
index e69de29b..8c7c5835 100644
--- a/docs/get-started/using-with-isomorphic-rendering.md
+++ b/docs/get-started/using-with-isomorphic-rendering.md
@@ -0,0 +1,5 @@
+# Using with Isomorphic Rendering
+
+Running under Node.js
+
+TBA
\ No newline at end of file
diff --git a/docs/get-started/whats-new.md b/docs/get-started/whats-new.md
deleted file mode 100644
index 9d2fc410..00000000
--- a/docs/get-started/whats-new.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# What's New
-
-
-
-## v3.0
-
-Release date: TBD
-
-## Highlights
-
-- **Separated Event Handling**: Event handling in `v3` is decoupled from the `React`
-component.
-- **Added Touch Support**: Using `hammer.js` to back our new event handling
-process means we can leverage its great support for touch events for our map interactions.
-- **Static and Interactive Map Component**: We now expose a `StaticMap` component
-which is meant to be completely stateless. The default component is now `InteractiveMap`,
-which will take care of handling interactions and states for you.
-- **Addional MapboxGL Components**: The following `MapboxGL` pieces have been
-given their own `React` components as well: `Popup`, `Marker`, `NavigationControl`.
-- **New fitBounds**: `fitBounds` has also been rewritten to remove dependency
-on `MapboxGL`'s utility functions.
-- **Documentation**: Improved and updated, and now uses a consistent style to
-other Uber Visualization open source projects.
-
-
-## v2.0
-
-Date: Jan 17, 2017
-
-### New Features
-- Bump `mapbox-gl` to v0.31.0
-- Add `maxZoom` prop and defaults to `20`
-- Add `onLoad` event handler
-- Add `onClick` prop handler (#140)
-
-### Breaking Changes
-- `mapbox-gl` 0.31.0 introduced a hard dependency on Node >= v4. `react-map-gl` now requires that you are on Node >= v4 and npm >= v3.
-
-
-## v1.0.0
-
-* **Perspective Mode** - Now supports `bearing` and `pitch` properties, per mapbox-gl-js api documentation. These props default to 0 which means that maps will still be rendered in flat/ortographic mode when they are not provided
-* **Support for ES6 imports** - The map overlay components (HTMLOverlay, CanvasOverlay, SVGOverlay etc) previously had to be imported via their relative source paths can now be imported directly using `import {SVGOverlay} from 'react-map-gl'.
diff --git a/docs/get-started/upgrade-guide.md b/docs/upgrade-guide.md
similarity index 64%
rename from docs/get-started/upgrade-guide.md
rename to docs/upgrade-guide.md
index f7e46d95..cbb6e923 100644
--- a/docs/get-started/upgrade-guide.md
+++ b/docs/upgrade-guide.md
@@ -2,7 +2,7 @@
## v3
-v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed features, a few breaking changes could not be avoided.
+v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed or removed features, a few breaking changes could not be avoided.
### Breaking Changes
@@ -17,7 +17,12 @@ Previously, the `viewport` object passed to these callbacks **did not** include
// GOOD: Width and Height below will override what's in `viewport`
```
-**Please double check** your render code if you relied on this behavior. If you rely on manually specifying the width and height, swapping the order should work:
+Please double check your render code if you relied on this behavior. If you rely on manually specifying the width and height, swapping the order should work:
+
+
+#### Some Overlays Moved to Examples
+
+Some less frequently used overlays (`DraggablePointsOverlay`, `ChoroplethOverlay`, `ScatterplotOverlay`), ... have been moved to examples. Most users have moved to map styles or deck.gl layers and removing these overlays reduces the size of the react-map-gl library for the majority of users that don't need them. If you still use them, simply copy the overlay source file(s) into your application.
### Deprecations
@@ -32,28 +37,31 @@ We have started to deprecate a few React props. In all the cases below, the old
| `perspectiveEnabled [default: false]` | `dragRotate [default: true]` |
+
## v2
v2 is API compatible with v1, however if you are still using `v1` of react-map-gl, make sure that you first upgrade:
* Your `node` version to `v4` or higher
* Your `react` version to `15.4` or higher.
+Background: `mapbox-gl` 0.31.0 introduced a hard dependency on Node >= v4.
+
## v1
(Upgrading from 0.6.x)
* **Importing Overlays** - The map overlay components (`HTMLOverlay`, `CanvasOverlay`, `SVGOverlay` etc) are now named exports. They previously had to be imported via their relative source paths:
+
```js
// v1.0
import MapGL, {SVGOverlay} from 'react-map-gl';
-// or
-var MapGL = require(`react-map-gl`);
-var SVGOverlay = MapGL.SVGOverlay;
// v0.6
import MapGL from 'react-map-gl';
-import SVGOverlay from 'react-map-gl/src/overlays/svg-overlays';.
+import SVGOverlay from 'react-map-gl/src/overlays/svg-overlay';.
```
-* **Map State** - The map state reported by `onViewportChanged` will now contain additional state fields (tracking not only `pitch` and `bearing` needed for perspective mode, but also transient information about how the projection is being changed by the user). This information must be passed back to the react-map-gl component in the next render. To simplify and future proof applications, it is recommended to simply save the entire `mapState` in your app store whenever it changes and then pass it back to the component rather than trying to keep track of individual fields (like `longitude`, `latitude` and `zoom`).
+* **Map State** - The map state reported by `onViewportChanged` will now contain additional state fields (tracking not only `pitch` and `bearing` needed for perspective mode, but also transient information about how the projection is being changed by the user).
+ * This information must be passed back to the react-map-gl component in the next render.
+ * To simplify and future proof applications, it is recommended to simply save the entire `mapState` in your app store whenever it changes and then pass it back to the component rather than trying to keep track of individual fields (like `longitude`, `latitude` and `zoom`).
diff --git a/docs/whats-new.md b/docs/whats-new.md
new file mode 100644
index 00000000..83ae98ba
--- /dev/null
+++ b/docs/whats-new.md
@@ -0,0 +1,51 @@
+# react-map-gl v3.0
+
+Release date: End of Q2, 2017 (TBD)
+
+## Highlights
+
+- **Event Handling**: New event handling architecture that enables full customization of event handling (experimental).
+- **Multi-Touch Support**: Full support for multi-touch gestures such as pinch-to-zoom and rotate.
+- **New Components**: `Popup`, `Marker`, `NavigationControl` have been added to provide parity with mapbox-gl.
+- **Documentation**: Significantly expanded and linked with our other geospatial frameworks.
+- **Examples**: Additional stand-alone examples to get you instantly started with new features.
+- **Latest mapbox-gl**: Bumps `mapbox-gl` to 0.37 and enables us to stay in sync with future versions.
+
+
+## Deprecations
+
+- **Property Names** - some prop names have been modernized, the old ones will still work for now with a warning.
+
+
+## Breaking Changes
+
+- **Overlays** - Three overlays (`ScatterplotOverlay`, `DraggablePointsOverlay`, `ChoroplethOverlay`), ... are now only provided as examples.
+- **fitBounds**: `fitBounds` has been rewritten to provide a better interface.
+
+For more information, see `Upgrade Guide`.
+
+
+# react-map-gl v2.0
+
+Date: Jan 17, 2017
+
+## Highlights
+- **Latest mapbox-gl**: Bump `mapbox-gl` to v0.31.0
+- **new maxZoom prop** - Add `maxZoom` prop and defaults to `20`
+- **New onLoad prop** - Add `onLoad` event handler
+- **new onClick prop** - Add `onClick` prop handler (#140)
+
+## Breaking Changes
+
+- **Node version bump** `react-map-gl` now requires that you are on Node >= v4 and npm >= v3.
+
+
+# react-map-gl v1.0
+
+* **Perspective Mode** - Now supports `bearing` and `pitch` properties, per mapbox-gl-js api documentation. These props default to 0 which means that maps will still be rendered in flat/ortographic mode when they are not provided
+* **Support for ES6 imports** - The map overlay components (HTMLOverlay, CanvasOverlay, SVGOverlay etc) previously had to be imported via their relative source paths can now be imported directly using `import {SVGOverlay} from 'react-map-gl'.
+
+
+# react-map-gl v0.6
+
+Initial public version