Merge remote-tracking branch 'origin/mb-pages'

Author: Lucas Wojciechowski

_config.mb-pages.yml

@@ -1,9 +1,9 @@
 url: https://www.mapbox.com
 api: https://www.mapbox.com/core
-tileApi: https://api.tiles.mapbox.com
+tileApi: https://api.mapbox.com
 source: docs
 permalink: /:categories/:title
-baseurl: /mapbox-gl-js
+baseurl: https://www.mapbox.com/mapbox-gl-js
 highlighter: pygments
 excerpt_separator: ""
 version: v0.18.0

docs/README.md

@@ -1,18 +1,17 @@
 Mapbox GL JS has [API documentation](#api-documentation) and [examples](#examples).
 
-## API Documentation
+## Writing API Documentation
 
-API documentation is written as [JSDoc comments](http://usejsdoc.org/) and processed with [documentationjs](http://documentation.js.org/). We aim to document all classes and methods, public and private. Mark private classes and methods with `@private`.
+API documentation is written as [JSDoc comments](http://usejsdoc.org/) and processed with [documentationjs](http://documentation.js.org/).
 
-Any interface not explicitly marked as `@private` will be displayed on the official [Mapbox GL JS documentation page](https://www.mapbox.com/mapbox-gl-js/api/). Internal interfaces can and should be documented with JSDoc comments but must be marked as `@private`.
+ - Classes, methods, events and anything else in the public interface must be documented with a JSDoc comment. Everything outside of the public interface may be documented and must be tagged as `@private`.
+ - Text within JSDoc comments may use markdown formatting. Code identifiers must be surrounded by \`backticks\`.
+ - Documentation must be written in complete gramatically-correct sentances.
+ - Documentation must specify measurement units when applicable.
+ - Documentation descriptions must contain more information than what is obvious from the identifier and JSDoc metadata.
+ - `@param` and `@property` descriptions should be capitalized and written as if completing a sentance beginning with "This is..." or "This...".
 
-References:
-
-* [Documentation.js Homepage](http://documentation.js.org)
-* [Documentation.js Getting Started Guide](https://github.com/documentationjs/documentation/blob/master/docs/GETTTING_STARTED.md)
-* [JSDoc Specification](http://usejsdoc.org/index.html)
-
-## Examples
+## Writing Examples
 
 Examples are written as Jekyll posts in `docs/_posts/examples`. The Jekyll front matter should include the following items:
 
@@ -28,7 +27,7 @@ In the post body, write the HTML and JavaScript constituting the example.
 * Do **not** use custom styles from your personal account. Use only the default `mapbox` account styles.
 * When embedding literal JSON (GeoJSON or GL style snippets) into script code, double-quote property names and string values. Elsewhere, use single-quoted strings.
 
-## Running Documentation Server Locally
+## Running the Documentation Server Locally
 
 To start a documentation server locally run
 ```bash
@@ -41,7 +40,7 @@ You can view the documentation at
 open http://127.0.0.1:4000/mapbox-gl-js
 ```
 
-## Troubleshooting
+### Troubleshooting
 
 Ensure you have the right version of all dependencies
 
@@ -56,7 +55,7 @@ jekyll -v
  > jekyll 2.5.3
 ```
 
-## Branch Usage
+## Committing and Publishing Documentation
 
 The mapbox-gl-js repository has both `master` and `mb-pages` as active branches. The **`master` branch** is used for mainline code development: the next version of mapbox-gl-js will come from the code in this branch, and it may contain documentation and examples for APIs that are not yet part of a public release. The **`mb-pages` branch** is published to https://www.mapbox.com/mapbox-gl-js/ on any push to the branch. For the purposes of documentation changes, use these two branches as follows:
 

docs/_layouts/default.html

@@ -41,6 +41,8 @@
       path: /contact
     - title: Education
       path: /education
+    - title: Humanitarian
+      path: /humanitarian
     - title: Security
       path: /security
   mapdesign:
@@ -105,8 +107,8 @@
   {% if page.card %}
   <meta name='twitter:site' content='@Mapbox' />
   <meta property='og:site_name' content='Mapbox' />
-  <meta name='twitter:url' content='{% if page.permalink %}{{page.permalink}}{% else %}{{page.url | replace:"index.html",""}}{% endif %}' />
-  <meta property='og:url' content='{% if page.permalink %}{{page.permalink}}{% else %}{{page.url | replace:"index.html",""}}{% endif %}' />
+  <meta name='twitter:url' content='{{site.url}}{{site.baseurl}}{% if page.permalink %}{{page.permalink}}{% else %}{{page.url | replace:"index.html",""}}{% endif %}' />
+  <meta property='og:url' content='{{site.url}}{{site.baseurl}}{% if page.permalink %}{{page.permalink}}{% else %}{{page.url | replace:"index.html",""}}{% endif %}' />
   <meta name='twitter:title' content='{{page.title | replace:"'","&rsquo;" | replace:"'","&rsquo;"}}' />
   <meta property='og:title' content='{{page.title | replace:"'","&rsquo;" | replace:"'","&rsquo;"}}' />
   <meta name='twitter:description' content='{% if page.description %}{{ page.description | truncatewords: 30 }}{% elsif page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | replace:"'","&rsquo;" | replace:"'","&rsquo;" | truncatewords: 30 }}{% else %}{{content | strip_html | truncatewords: 30 }}{% endif %}' />
@@ -258,7 +260,7 @@ <h3><a href='/developers/' class='rcon next'>Developer tools</a></h3>
             <a class='block pad1y icon compass' href='/api-documentation/#directions'>Directions API</a>
             <a class='block pad1y icon point-line' href='/api-documentation/#distance'>Distance API</a>
             <a class='block pad1y icon picture' href='/api-documentation/#static'>Static API</a>
-            <a class='block pad1y icon data' href='/api-documentation/#maps'>Tiles API</a>
+            <a class='block pad1y icon data' href='/api-documentation/#maps'>Maps API</a>
           </div>
         </div>
         <div class='col3 margin1r subnavcol'>

docs/_layouts/docs.html

@@ -5,7 +5,7 @@
 ---
 
 
-<div class='round doc clip fill-white keyline-all'>
+<div class='round doc clip fill-white keyline-all space-bottom'>
 
   <section class='pad4 keyline-bottom contain'>
 
@@ -18,39 +18,51 @@ <h1 class='space-bottom2'>
     </h1>
 
     <div class='prose space-bottom2'>
-      <p>Mapbox GL JS is a JavaScript library that uses WebGL to render interactive maps from <a href='https://www.mapbox.com/blog/vector-tiles'>vector tiles</a> and <a href='https://www.mapbox.com/mapbox-gl-style-spec'>Mapbox GL styles</a><p>
-      <p>It is part of the <a href='https://github.com/mapbox/mapbox-gl'>Mapbox GL ecosystem</a> which includes <a href='https://www.mapbox.com/mobile/'>Mapbox Mobile</a>, a suite of compatible SDKs for native desktop and mobile applications.</p>
-      <a href='https://www.mapbox.com/gallery/'><img width='981' alt='Mapbox GL JS gallery' src='{{site.baseurl}}/assets/gallery.png'></a>
+      <p>Mapbox GL JS is a JavaScript library that uses WebGL to render interactive maps from <a href='{{site.url}}/help/define-vector-tiles'>vector tiles</a> and <a href='{{site.url}}/mapbox-gl-style-spec'>Mapbox GL styles</a>.<p>
+      <p>It is part of the <a href='https://github.com/mapbox/mapbox-gl'>Mapbox GL ecosystem</a> which includes <a href='{{site.url}}/mobile/'>Mapbox Mobile</a>, a compatible renderer written in C++ with bindings for desktop and mobile platforms.</p>
     </div>
+    <a href='https://www.mapbox.com/gallery/'><img alt='Mapbox GL JS gallery' src='{{site.baseurl}}/assets/gallery.png'></a>
+  </section>
+</div>
 
-    <h2 class='space'>Using Mapbox GL JS with a <code>&lt;script&gt;</code> tag</h2>
+<div class='keyline-all fill-darken0 space-bottom round'>
+  <div class='pad1y pad2x keyline-bottom strong small clearfix'>
+    <span class='fill-darken1 pad1x round dark inline fr'>mapbox-gl.js {{site.version}}</span>
+    Get started
+  </div>
+  <div class='pad2'>
+    <div class='fill-white js-replace-token' id='head-code'>{% highlight html %}
+<script src='{{site.tileApi}}/mapbox-gl-js/{{site.version}}/mapbox-gl.js'></script>
+<link href='{{site.tileApi}}/mapbox-gl-js/{{site.version}}/mapbox-gl.css' rel='stylesheet' />{% endhighlight html %}
+    </div>
+    <a class='button icon clipboard col12 round-bottom js-clipboard space-bottom1' href='#' data-clipboard-target='head-code'>Copy code</a>
 
-    <div class='prose space-bottom2'>
-      <p>To use the <a href='https://www.mapbox.com/maps/'>vector tiles</a> and styles hosted on <a href='http://mapbox.com'>Mapbox</a>, you must <a href='https://www.mapbox.com/studio/signup/'>create an account</a> and <a href='https://www.mapbox.com/studio/account/tokens/'>obtain an access token</a>. You can learn more about access tokens <a href='https://www.mapbox.com/help/define-access-token/'>here</a>.
-
-      <pre>
-&lt;!DOCTYPE html&gt;
-&lt;html&gt;
-&lt;head&gt;
-  &lt;script src='https://api.tiles.mapbox.com/mapbox-gl-js/{{site.version}}/mapbox-gl.js'&gt;&lt;/script&gt;
-  &lt;link href='https://api.tiles.mapbox.com/mapbox-gl-js/{{site.version}}/mapbox-gl.css' rel='stylesheet'&gt;
-&lt;/head&gt;
-
-&lt;body&gt;
-  &lt;div id='map' style='width: 400px; height: 300px;' /&gt;
-
-  &lt;script&gt;
-    mapboxgl.accessToken = '&lt;your access token here&gt;';
-    var map = new mapboxgl.Map({
-      container: 'map',
-      style: 'mapbox://styles/mapbox/streets-v8'
-    });
-  &lt;/script&gt;
-&lt;/body&gt;
-&lt;/html&gt;
-      </pre>
+    <div class='pad1x small quiet space-bottom1'>
+      Include the JavaScript and CSS files in the <code>&lt;head&gt;</code> of your HTML file.
     </div>
-  </section>
 
+    <div class='fill-white js-replace-token' id='body-code'>
+{% capture getting_started_html %}
+<div id='map' style='width: 400px; height: 300px;'></div>
+<script>
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v8'
+});
+</script>
+{% endcapture %}
+
+      {% highlight html %}{{ getting_started_html | insert_token }}{% endhighlight %}
+    </div>
+    <a class='button icon clipboard col12 round-bottom js-clipboard space-bottom1' href='#' data-clipboard-target='body-code'>Copy code</a>
+
+    <div class='pad1x small quiet'>
+      Include this code in the <code>&lt;body&gt;</code> of your HTML file to initialize a map on the page.
+      <a class='truncate rcon next' href='{{site.baseurl}}/examples/'>View basic example</a>
+    </div>
+  </div>
+</div>
+
+<div class='round doc clip fill-white keyline-all space-top'>
   {{ content }}
 </div>

docs/_posts/examples/3400-01-04-color-switcher.html

@@ -85,7 +85,7 @@
 });
 
 var swatches = document.getElementById('swatches');
-var layers = document.getElementById('layers');
+var layer = document.getElementById('layer');
 var colors = [
     '#ffffcc',
     '#a1dab4',

docs/_posts/examples/3400-01-05-queryrenderedfeatures.html

@@ -14,6 +14,9 @@
         overflow: auto;
         background: rgba(255, 255, 255, 0.8);
     }
+    #map canvas {
+        cursor: crosshair;
+    }
 </style>
 <div id='map'></div>
 <pre id='features'></pre>

docs/_posts/examples/3400-01-08-data-driven-circle-colors.html

@@ -0,0 +1,46 @@
+---
+layout: example
+category: example
+title: Data-driven circle coloring by ethnicity
+description: Using a categorical circle-color property for a visualization
+---
+<div id='map'></div>
+<script>
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/light-v8',
+    zoom: 12,
+    center: [-122.447303, 37.753574]
+});
+
+map.on('load', function () {
+    map.addSource('population', {
+        type: 'vector',
+        url: 'mapbox://examples.8fgz4egr'
+    });
+    map.addLayer({
+        'id': 'population',
+        'type': 'circle',
+        'source': 'population',
+        'source-layer': 'sf2010',
+        'paint': {
+            // make circles larger as the user zooms from z12 to z22
+            'circle-radius': {
+                'base': 1.75,
+                'stops': [[12, 2], [22, 180]]
+            },
+            // color circles by ethnicity, using data-driven styles
+            'circle-color': {
+                property: 'ethnicity',
+                type: 'categorical',
+                stops: [
+                    ['White', '#fbb03b'], 
+                    ['Black', '#223b53'], 
+                    ['Hispanic', '#e55e5e'], 
+                    ['Asian', '#3bb2d0'], 
+                    ['Other', '#ccc']]
+            }
+        }
+    });
+});
+</script>

docs/_posts/examples/3400-01-12-mapbox-gl-geocoder.html

@@ -7,8 +7,8 @@
   - plugins
   - mapbox-geocoding
 ---
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.css' type='text/css' />
+<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.js'></script>
+<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.css' type='text/css' />
 <div id='map'></div>
 
 <script>

docs/_posts/examples/3400-01-16-point-from-geocoder-result.html

@@ -7,8 +7,8 @@
   - plugins
   - mapbox-geocoding
 ---
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.css' type='text/css' />
+<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.js'></script>
+<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.css' type='text/css' />
 <style>
 #geocoder-container {
     position: absolute;

docs/_posts/plugins/0100-01-01-mapbox-gl-geocoder.html

@@ -9,5 +9,5 @@
 code: https://github.com/mapbox/mapbox-gl-geocoder
 license: BSD
 ---
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.0.0/mapbox-gl-geocoder.css' type='text/css' />
+<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.js'></script>
+<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v1.1.0/mapbox-gl-geocoder.css' type='text/css' />