Maps4HTML · ahmadayubi · Mar 23, 2021 · Mar 17, 2021 · Mar 23, 2021 · Mar 23, 2021
diff --git a/docs/assets/img/mapml-viewer.png b/docs/assets/img/mapml-viewer.png
diff --git a/docs/intro.md b/docs/intro.md
@@ -4,6 +4,18 @@ title: Introduction
 slug: /
 ---
 
-:::info
-Under construction
-:::
+The web-map custom element suite provides a Web map viewer 'widget' which is modelled somewhat after the HTML5 `<video>` tag: a fairly simple way to get started publishing Web content of the mapping variety.  If you're familiar with that HTML `<video>` developer and user experience you may find developing with and using the web-map custom element suite familiar.
+
+For example, markup such as this:
+
+```html
+<mapml-viewer projection="CBMTILE" zoom="3" lat="62.7" lon="-90.3" controls>
+    <layer- label="CBMT" src="https://geogratis.gc.ca/mapml/en/cbmtile/cbmt/" checked></layer->
+    <layer- label="Restaurants" src="demo/restaurants.mapml" checked></layer->
+    <layer- label="Canada's Provinces and Territories" src="demo/canada.mapml" checked></layer->
+</mapml-viewer>
+```
+
+can be used to create a map like this:
+
+![The web-map in action](assets/img/mapml-viewer.png)
diff --git a/docs/maps/mapml-viewer.md b/docs/maps/mapml-viewer.md
@@ -0,0 +1,56 @@
+---
+id: mapml-viewer
+title: <mapml-viewer>
+slug: /maps/mapml-viewer
+---
+
+## Introduction
+
+The `<mapml-viewer>` element is the main element you can use to put a custom Web map on your page.  To create a (really) simple Web map, you might use it like this:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+   <head>
+     <meta charset="utf-8" />
+     <title>A Simple Web Map[tm]</title>
+     <meta name="viewport" content="width=device-width, initial-scale=1">
+     <script type="module" src="web-map/mapml-viewer.js"></script>
+   </head>
+   <body>
+    <mapml-viewer projection="OSMTILE" zoom="0" lat="0.0" lon="0.0" controls>
+        <layer- label="OpenStreetMap" src="https://geogratis.gc.ca/mapml/en/osmtile/osm/" checked></layer->
+    </mapml-viewer>
+   </body>
+</html>    
+```
+Note that for the above example to run properly on your own site, you need to get a built copy of the `<mapml-viewer>` project in your site's folder. In the example, the `<mapml-viewer>` files are copied into the folder named "web-map" in your site root folder. Your own site's path to these files will depend on how you structure your folders.
+
+`<mapml-viewer>` is an "[autonomous custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)" in HTML.  You can distinguish a custom element of any category from a "native" HTML element by the "-" anywhere in the element name. Autonomous custom elements are supported by all modern browsers, but don't work in old browsers (e.g. Internet Explorer and old Edge).
+
+The `<mapml-viewer>` element has several attributes to control the presentation and initial location of the map.  
+
+### Attributes
+
+
+`projection` - an enumerated attribute. Case-sensitive values are: "`OSMTILE`", "`WGS84`", "`CBMTILE`" and "`APSTILE`".  
+
+  - `OSMTILE` corresponds to the widely-used "Web Mercator" projected coordinate reference system, implying a "tile pyramid" zoom range from 0 to 23 (minimum tile size ~2.4m).
+
+  - `WGS84` provides an implementation of the "pseudo plate carée" projected coordinate reference system, wherein the easting and northing axis units are decimal degrees (not meters). In `WGS84`, zoom level 0 contains two tiles that each cover a hemisphere of Earth's surface. `WGS84` is defined with 21 zoom levels (0 to 20).  
+
+  - `CBMTILE` is the de facto standard grid layout for the Canadian Geospatial Data Infrastructure (CGDI), defined by Natural Resources Canada, and is based on the Lambert Conformal Conic projection (EPSG:3978). Zoom levels are based on a numeric map scale denominator (e.g. 10000 corresponding to a map scale of 1:10,000), with a particular pixel resolution selected, and as a result, successive zoom levels' tiles do not nest exactly (as they do in `OSMTILE`, `WGS84` and `APSTILE`). 
+
+  - `APSTILE` is based on the Alaska Polar Stereographic (EPSG:5936) projected coordinate reference system, and has 20 zoom levels (0 to 19).
+
+  - other projections are possible, using the "[Custom Projections](https://github.com/Maps4HTML/Web-Map-Custom-Element/blob/8723e4d8bad8e3629bc9dca7a6fe81d724e8418f/demo/CustomProjection.html#L1-L158)" API
+
+`zoom` - a non-negative integer.  The value establishes the initial zoom level of the map.  For a small scale view of the world, use a lower value.  Use larger values for larger scales (smaller area maps). The maximum value depends on the particular `projection` and data source. Many map data sources have limited zoom levels available.
+
+`lat` - a real number latitude. The value establishes the initital latitide of the of the center of the map. Latitudes on Earth range from -90.0 (south) to 90.0 (north).  Many projections are not able to display all latitudes, and most projections have a limited range of locations where distortion is controlled or limited. In particular, OSMTILE (Web Mercator) can only display content between the latitude range -84 to 84.
+
+`lon` - a real number longitude. The value establishes the initital longitude of the of the center of the map.Longitudes on Earth range from -180.0 (west) to 180.0 (east). Similar comments related to distortion apply to those for latitude. Be careful, this attribute is named "lon" NOT "long", and if you use "long" your map won't work properly.
+
+`controls` - a "boolean" attribute. Turns map controls on (if present) or off (if omitted). In HTML "boolean" attributes don't have values of "true" or "false" per se - they have the implied value of "true" if the attribute exists, and an implied value of "false" if the attribute is not present.  Sometimes the default map controls may not be useful for your map, so you may turn them off and design your own.
+
+`controlslist` - an enumerated attribute, possible values are: "`nofullscreen`", "`nolayer`", "`noreload`" and "`nozoom`".  Occasionally, you may not want your users to have access to a particular control, so you may prune the set of controls automatically presented (when you have used the `controls` boolean attribute).
diff --git a/docs/maps/web-map.md b/docs/maps/web-map.md
@@ -0,0 +1,39 @@
+---
+id: web-map
+title: <map is="web-map">
+slug: /maps/web-map
+---
+
+The HTML `<map>` element has been deployed and in use in browsers since the mid-90's. It was used to provide visually appealing yet accessible home pages, by giving the Web developer the ability to design links as invisible yet interactive polygonal areas on top of one or more images.  Use of this facility became known as "client side image maps", and was often used to provide site navigation links.
+
+In recent years, client side image maps have fallen out of wide use, due to improvements in other areas of the Web platform.  However, some sites still use image maps to provide a simple, accessible, but simultaneously visual user experience.
+
+The web-map custom element suite provides a set of proof-of-concept "[customized built-in](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)" elements based on `<map>`, `<area>` and `<img>` that will "fall back" to a client side image map in older browsers, or in the absence of JavaScript (scripting disabled).
+
+:::caution
+
+Note that because not all modern Web browsers implement HTML's customized built-in elements, it is not recommended to use this proof-of-concept on a public Web site, as end-user confusion may be the result.
+
+:::
+
+The following markup may work on Chrome and Firefox, although it may take some fine tuning:
+
+```html
+<img usemap="#mymap" src="../map1.png" width="700" height="400" alt="Map area">
+<map name="mymap" is="web-map" zoom="17" lat="45.398043" lon="-75.70683" controls>
+    <layer- id="osm" src="https://geogratis.gc.ca/mapml/osmtile/osm/" label="Open Street Map" checked></layer->
+    <layer- id="marker" label="Marker layer" src="../marker.mapml"></layer->
+    <area is="map-area" href='http://example.com/marker/' alt="rectangle" coords="255,145,275,190" shape="rect">
+    <area is="map-area" id="donut" alt="Circle" href='http://example.com/circle/' coords="250,250,25" shape="circle">
+    <area is="map-area" id="hole" coords="250,250,7" shape="circle">
+    <area is="map-area" id="rect" href='http://example.com/rectangle/' alt="Rectangle" coords="345,290,415,320" shape="rect">
+    <area is="map-area" id="poly" href='http://example.com/polygon/' alt="Polygon" coords="392,116,430,100,441,128,405,145" shape="poly">
+</map>
+```
+
+To experiment with the `web-map` and `map-area` custom elements, you should link your `<script type="module" src="web-map.js"></script>` to the `web-map.js` file that is built by the web-map custom element suite build process.
+
+In theory, if you take steps to provde the fallback markup, a normal (progressive) Web map experience will be had by most users, while those using an older browser or perhaps even Safari may get the "fallback" client side image map experience.  
+
+An older example of such a Web map may be found in [this](https://maps4html.org/Web-Map-Custom-Element/blog/progressive-web-maps.html) blog post.  Please raise an [issue](https://github.com/Maps4HTML/Web-Map-Custom-Element/issues) if you have comments about how that example works for you.
+
diff --git a/docs/resources/resources.md b/docs/resources/resources.md
@@ -0,0 +1,9 @@
+---
+id: resources
+title: Resources
+slug: /resources/resources
+---
+
+:::info
+Under construction
+:::
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -97,15 +97,9 @@ module.exports = {
       {
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
-          // Please change this to your repo.
-          editUrl:
-            'https://github.com/Maps4HTML/web-map-doc',
         },
         blog: {
           showReadingTime: true,
-          // Please change this to your repo.
-          editUrl:
-            'https://github.com/facebook/docusaurus/edit/master/website/blog/',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),