Upgrade docusaurus (#153)

* Upgrade docusaurus to 3.5.2, requires a bunch of changes and validation of md/mdx files. Fix links reported broken, as possible (some mis- reporting there). * Update README.md --------- Co-authored-by: prushfor <[email protected]>
Maps4HTML · Sep 26, 2024 · 7ccbab6 · 7ccbab6
1 parent c03e878
commit 7ccbab6
Show file tree

Hide file tree

Showing 28 changed files with 16,695 additions and 14,182 deletions.
diff --git a/README.md b/README.md
@@ -2,9 +2,21 @@
 
 ![Sync Repositories](https://github.com/Maps4HTML/MapML.js/workflows/Sync%20Repositories/badge.svg)
 
-## What is the `<mapml-viewer>` and `<layer->` element suite?
+## This documentation is available at https://maps4html.org/web-map-doc/
 
-The `<mapml-viewer>` custom element is a prototype implementation of the
-[`<map>` media element](https://maps4html.org/MapML-Specification/spec/#web-maps)
-defined in the MapML (Map Markup Language)
-[specification](https://maps4html.org/MapML-Specification/spec/). This repository is the documentation for this suite of elements, available [here](https://maps4html.org/web-map-doc/).
+This repository is the documentation for the [polyfill](https://www.w3.org/2001/tag/doc/polyfills/) implementation of
+[Map Markup Language](https://maps4html.org/MapML-Specification/spec/).
+
+To build and run this documentation locally, do the following:
+
+$ cd github/web-map-doc # or whatever you name your clone of this repo
+$ npm install
+$ npm audit fix # typically necessary to resolve some error messages
+$ npm run build
+$ npm run serve # should fire up a browser and point it to http://localhost:30001/web-map-doc/
+
+If you have suggestions or want to open a pull request for an improved API or 
+documentation thereof, it's a good idea to open an issue and discuss with the
+community in advance. 
+
+Thank you and happy pollyfilling!
diff --git a/blog/2019-05-28-hola.md b/blog/2019-05-28-hola.md
diff --git a/blog/2019-05-29-hello-world.md b/blog/2019-05-29-hello-world.md
diff --git a/blog/2019-05-30-welcome.md b/blog/2019-05-30-welcome.md
diff --git a/docs/api/geojson-api.mdx b/docs/api/geojson-api.mdx
@@ -29,7 +29,7 @@ The **GeoJSON API** is provided as a library to convert GeoJSON to and from MapM
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-|<code>geojson2mapml(<Object&nbsp;\|&nbsp;String\>&nbsp;json,&nbsp;<Object\>&nbsp;options)</code> | A MapML `<layer->` element. | Convert a GeoJSON feature or feature collection string or object to MapML `<layer->` containing one or more `<map-feature>` elements.|
+|<code>geojson2mapml(\<Object \| String\> json, \<Object\>options)</code> | A MapML `<layer->` element. | Convert a GeoJSON feature or feature collection string or object to MapML `<layer->` containing one or more `<map-feature>` elements.|
 
 :::tip
 
@@ -41,20 +41,20 @@ Check out [this application](https://maps4html.org/experiments/api/custom-map-ui
 
 | Parameter | Description |
 |------|---------------------|
-| <String&nbsp;\|&nbsp;Object>&nbsp;json | A GeoJSON string or object. |
-| &ltObject&gt options | A set of key/value pairs that customize the output MapML layer. All options are optional and described below. |
+| \<String | Object> json | A GeoJSON string or object. |
+| \<Object> options | A set of key/value pairs that customize the output MapML layer. All options are optional and described below. |
 
 ### Options
 
-&ltObject&gt A set of key/value pairs that customize the output MapML layer. All options are optional and detailed below.
+\<Object> A set of key/value pairs that customize the output MapML layer. All options are optional and detailed below.
 
 | Option | Type | Default | Description |
 |------|------|---------------|--------|
-| `label` | <String\> | `json.name`, `json.title` or "Layer" | Sets the output layer's [label](https://maps4html.org/web-map-doc/docs/layers/layer/#label). |
-| `projection` |  <String\> | `OSMTILE` | Sets the output layer's [projection](https://maps4html.org/web-map-doc/docs/elements/mapml-viewer/#projection). Defined values include: `OSMTILE`, `CBMTILE`, `WGS84`, and `APSTILE`.|
-| `caption` | <String&nbsp;\|&nbsp;Function\> | Uses the `label` value | A function that accepts the feature JSON and returns a string, OR a string that is the name of a property to be mapped to the [featurecaption](https://maps4html.org/web-map-doc/docs/elements/feature/#map-featurecaption). If a matching property is not found, the string provided will be used as the feature caption value. See [basic options usage](#basic-options-usage) for an example. |
-| <span id="option-properties">`properties`</span> | <Function&nbsp;\|&nbsp;String&nbsp;\|&nbsp;HTMLElement\> | _Properties will be mapped to an HTML [table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table)._ | Specifies how the properties are mapped. <Function\> - A function that accepts one argument - the GeoJSON feature object - and which must return an HTMLElement that becomes the single child element of the <properties\> element. <String\> - A string that will be parsed and used as the single child element of the `<properties>` element for all features. <HTMLElement\> - an element that will be used as the single child element of `<properties>` element for all features. See [basic options usage](#basic-options-usage) for an example.|
-| `geometryFunction` | <Function\> | _MapML geometry will mirror the GeoJSON geometry value_ | <Function\> A function to modify the generated [descendants](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) of `<map-geometry>` which can add classes, [hyperlinks](https://maps4html.org/web-map-doc/docs/other-elements/map-a/) and [span's](https://maps4html.org/web-map-doc/docs/other-elements/span/) to the instance. Plain `<map-geometry>` element will be created by default. The function accepts two arguments: The generated [child element](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) of `<map-geometry>` and the [feature json object](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) to return a modified child element of the `<map-geometry>` element. See [basic options usage](#basic-options-usage) for an example. |
+| `label` | \<String\> | `json.name`, `json.title` or "Layer" | Sets the output layer's [label](https://maps4html.org/web-map-doc/docs/layers/layer/#label). |
+| `projection` |  \<String\> | `OSMTILE` | Sets the output layer's [projection](https://maps4html.org/web-map-doc/docs/elements/mapml-viewer/#projection). Defined values include: `OSMTILE`, `CBMTILE`, `WGS84`, and `APSTILE`.|
+| `caption` | \<String \| Function> | Uses the `label` value | A function that accepts the feature JSON and returns a string, OR a string that is the name of a property to be mapped to the [featurecaption](https://maps4html.org/web-map-doc/docs/elements/feature/#map-featurecaption). If a matching property is not found, the string provided will be used as the feature caption value. See [basic options usage](#basic-options-usage) for an example. |
+| <span id="option-properties">`properties`</span> | \<Function \| String \| HTMLElement\> | _Properties will be mapped to an HTML [table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table)._ | Specifies how the properties are mapped. \<Function\> - A function that accepts one argument - the GeoJSON feature object - and which must return an HTMLElement that becomes the single child element of the \<map-properties\> element. \<String\> - A string that will be parsed and used as the single child element of the `<map-properties>` element for all features. \<HTMLElement\> - an element that will be used as the single child element of `<map-properties>` element for all features. See [basic options usage](#basic-options-usage) for an example.|
+| `geometryFunction` | \<Function\> | _MapML geometry will mirror the GeoJSON geometry value_ | \<Function\> A function to modify the generated [descendants](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) of `<map-geometry>` which can add classes, [hyperlinks](https://maps4html.org/web-map-doc/docs/elements/map-a/) and [span's](https://maps4html.org/web-map-doc/docs/elements/span/) to the instance. Plain `<map-geometry>` element will be created by default. The function accepts two arguments: The generated [child element](https://maps4html.org/web-map-doc/docs/elements/geometry/#child-elements) of `<map-geometry>` and the [feature json object](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) to return a modified child element of the `<map-geometry>` element. See [basic options usage](#basic-options-usage) for an example. |
 
 ---
 ### Examples
@@ -280,7 +280,7 @@ let output = geojson2mapml(json);
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| <code>mapml2geojson(<HTMLLayerElement\>&nbsp;element,&nbsp;<Object\>&nbsp;options)</code> | A JavaScript (GeoJSON) feature collection object | This function transforms the `<feature>` element children of a `<layer->` element to a GeoJSON FeatureCollection object. You supply [options](#options-1) to control the transformation. This function must be used inside a windows.onload event.
+| <code>mapml2geojson(\<HTMLLayerElement\> element, \<Object\> options)</code> | A JavaScript (GeoJSON) feature collection object | This function transforms the `<feature>` element children of a `<layer->` element to a GeoJSON FeatureCollection object. You supply [options](#options-1) to control the transformation. This function must be used inside a windows.onload event.
 
 :::caution
 
@@ -298,17 +298,17 @@ window.onload = (event) => {
 
 | Parameter | Description |
 |------|--------------|
-| <HTMLLayerElement\> element | A `<layer->` element. |
-| <Object\>&nbsp;options | You supply parameters via an options object with [predefined option names](#options-1). |
+| \<HTMLLayerElement\> element | A `<layer->` element. |
+| \<Object\> options | You supply parameters via an options object with [predefined option names](#options-1). |
 
 ### Options
 
-<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
+\<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
 
 | Option | Type | Default | Description |
 |------|------|---------------|--------|
-| `propertyFunction` | <Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](#option-properties). |
-| `transform` | <Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
+| `propertyFunction` | \<Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](#option-properties). |
+| `transform` | \<Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
 ###### Notes
 
 `mapml2geojson`, by default, will transform coordinates to `gcrs` before serialization, if 

diff --git a/docs/api/layer-api.md b/docs/api/layer-api.md
@@ -145,7 +145,7 @@ layer.zoomTo();
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| <code>mapml2geojson(<Object\>&nbsp;options)</code> | A JavaScript (GeoJSON) feature collection object | This function transforms the `<feature>` element children of a `<layer->` element to a GeoJSON FeatureCollection object. You supply [options](#options) to control the transformation. This function must be used inside a windows.onload event.
+| <code>mapml2geojson(\<Object\> options)</code> | A JavaScript (GeoJSON) feature collection object | This function transforms the `<feature>` element children of a `<layer->` element to a GeoJSON FeatureCollection object. You supply [options](#options) to control the transformation. This function must be used inside a windows.onload event.
 
 :::caution
 
@@ -164,16 +164,16 @@ window.onload = (event) => {
 
 | Parameter | Description |
 |------|--------------|
-| <Object\>&nbsp;options | Optional. You supply parameters via an options object with [predefined option names](#options). |
+| \<Object\> options | Optional. You supply parameters via an options object with [predefined option names](#options). |
 
 #### Options
 
-<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
+\<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
 
 | Option | Type | Default | Description |
 |------|------|---------------|--------|
-| `propertyFunction` | <Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](mapml-viewer-api#options). |
-| `transform` | <Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
+| `propertyFunction` | \<Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](mapml-viewer-api#options). |
+| `transform` | \<Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
 ###### Notes
 
 `mapml2geojson`, by default, will transform coordinates to `gcrs` before serialization, if 

diff --git a/docs/api/map-feature-api.md b/docs/api/map-feature-api.md
@@ -301,7 +301,7 @@ None ([undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refere
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| <code>mapml2geojson(<Object\>&nbsp;options)</code> | A JavaScript (GeoJSON) feature object | This function transforms the `<feature>` element to a GeoJSON Feature object. You supply [options](#options) to control the transformation. 
+| <code>mapml2geojson(\<Object\> options)</code> | A JavaScript (GeoJSON) feature object | This function transforms the `<feature>` element to a GeoJSON Feature object. You supply [options](#options) to control the transformation. 
 
 :::caution
 
@@ -322,16 +322,16 @@ window.onload = (event) => {
 
 | Parameter | Description |
 |------|--------------|
-| <Object\>&nbsp;options | <span className="badge">Optional</span> You supply parameters via an options object with [predefined option names](#options). |
+| \<Object\>&nbsp;options | <span className="badge">Optional</span> You supply parameters via an options object with [predefined option names](#options). |
 
 ##### Options
 
-<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
+\<Object\> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.
 
 | Option | Type | Default | Description |
 |------|------|---------------|--------|
-| `propertyFunction` | <Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](mapml-viewer-api#options). |
-| `transform` | <Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
+| `propertyFunction` | \<Function\> | _n/a_ | A function you supply that maps the features' `<map-properties>` element to a [GeoJSON "properties" member](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the [default properties option function from geojson2mapml](mapml-viewer-api#options). |
+| `transform` | \<Boolean\> | `true` | Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON [recommends](https://www.rfc-editor.org/rfc/rfc7946.html#section-4) using WGS 84 longitude,latitude coordinates, so this is the default behaviour. |
 ###### Notes
 
 :::caution
@@ -356,7 +356,7 @@ A GeoJSON object representing the feature
 | Event name      	| Description                                          	|
 |--------------	|--------------------------------------------------------	|
 | click | The click event occurs when the user clicks or touches the feature with the keyboard or pointer, or when the [click()](#click) method is called. |
-| focus | The focus event occurs when the feature gains focus with a keyboard or pointer, or when the [focus()](#focus) method is called. |
+| focus | The focus event occurs when the feature gains focus with a keyboard or pointer, or when the [focus()](#focusoptions) method is called. |
 | blur  | The blur event occurs when the feature loses focus with a keyboard or pointer, or when the [blur()](#blur) method is called. |
 ---