Improve the guides serction (#3400)

* Add more guides, simplify main readme, fix incorrect links.

* Fix search issue that presents long text, fix missing image

README.md

@@ -49,42 +49,6 @@ Check out the features through [examples](https://maplibre.org/maplibre-gl-js/do
 
 <br />
 
-## Migrating from mapbox-gl to maplibre
-The libraries are very similar but diverge with newer features happening from v2 in both libraries where Mapbox turned proprietary.
-
-The overall migration happens by uninstalling `mapbox-gl` and installing `maplibre-gl` in your node packages (or see below for CDN links), and replacing `mapboxgl` with `maplibregl` throughout your TypeScript, JavaScript and HTML/CSS.
-
-```diff
--    var map = new mapboxgl.Map({
-+    var map = new maplibregl.Map({
-
--    <button class="mapboxgl-ctrl">
-+    <button class="maplibregl-ctrl">
-```
-
-#### Compatibility branch
-
-MapLibre GL JS v1 is completely backward compatible with Mapbox GL JS v1. This compatibility branch (named 1.x) is tagged v1 on npm, and its current version is 1.15.3. 
-
-#### CDN Links
-
-> MapLibre GL JS is distributed via [unpkg.com](https://unpkg.com). For more information, please see [MapLibre GL JS is on unpkg.com](./developer-guides/README-unpkg.md).
-
-```diff
--    <script src="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.js"></script>
--    <link
--      href="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.css"
--      rel="stylesheet"
--    />
-
-
-+    <script src="https://unpkg.com/maplibre-gl@#.#.#/dist/maplibre-gl.js"></script>
-+    <link
-+      href="https://unpkg.com/maplibre-gl@#.#.#/dist/maplibre-gl.css"
-+      rel="stylesheet"
-+    />
-
-```
 
 Want an example? Have a look at the official [MapLibre GL JS Documentation](https://maplibre.org/maplibre-gl-js/docs/examples/).
 

docs/assets/extra.css

@@ -0,0 +1,7 @@
+/* see https://github.com/squidfunk/mkdocs-material/issues/4278 */
+.md-search-result .md-typeset {
+    display: -webkit-box;
+    -webkit-line-clamp: 5;
+    -webkit-box-orient: vertical;
+    max-height: 200px;
+}

docs/guides/index.md

@@ -0,0 +1,8 @@
+# Guides
+
+This section of the docs' site is dedicated to some more complex examples and totorials.
+If you have something you would like to share with the community that is not straight forward and might be beneficial to others, this is the place!
+
+Things that are short enough and/or with lower complexity are probably already in the [Examples](../examples/index.md) section, but if not, feel free to add there.
+
+The process of adding examples or guides is pretty straight forward, see our `docs` folder in the [MpaLibre GL JS repo](https://github.com/maplibre/maplibre-gl-js/tree/main/docs) for more information.

docs/guides/mapbox-migration-guide.md

@@ -0,0 +1,44 @@
+# MapBox migration guide
+
+This part of the docs is dedicated to the migration from `mapbox-gl` to `maplibre-gl`.
+
+This guide might not be accurate depending on the current version of `mapbox-gl` but should be failry straight forward.
+
+The libraries are very similar but diverge with newer features happening from v2 in both libraries where Mapbox turned proprietary.
+
+The overall migration happens by uninstalling `mapbox-gl` and installing `maplibre-gl` in your node packages (or see below for CDN links), and replacing `mapboxgl` with `maplibregl` throughout your TypeScript, JavaScript and HTML/CSS.
+
+```diff
+-    var map = new mapboxgl.Map({
++    var map = new maplibregl.Map({
+
+-    <button class="mapboxgl-ctrl">
++    <button class="maplibregl-ctrl">
+```
+
+#### Compatibility branch
+
+MapLibre GL JS v1 is completely backward compatible with Mapbox GL JS v1. This compatibility branch (named 1.x) is tagged v1 on npm, and its current version is 1.15.3. 
+
+#### CDN Links
+
+> MapLibre GL JS is distributed via [unpkg.com](https://unpkg.com).
+
+```diff
+-    <script src="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.js"></script>
+-    <link
+-      href="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.css"
+-      rel="stylesheet"
+-    />
+
+
++    <script src="https://unpkg.com/maplibre-gl@#.#.#/dist/maplibre-gl.js"></script>
++    <link
++      href="https://unpkg.com/maplibre-gl@#.#.#/dist/maplibre-gl.css"
++      rel="stylesheet"
++    />
+
+```
+
+Don't forget to replace the version above `#.#.#` with the version you would like to use.
+In the upper right corner of this page you can find the number of the latest version.

docs/index.md

@@ -24,14 +24,14 @@ MapLibre GL JS is a TypeScript library that uses WebGL to render interactive map
 
 This documentation is divided into several sections:
 
-* [**Main**](./API/#main) - The Main section holds the following classes
-    * [`Map`](./API/classes/maplibregl.Map/) object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
-    * [`MaplibreGL`](./API/classes/default/) object is MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
-* [**Markers and Controls**](./API/#markers-and-controls) - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element. This consists of `Marker`, `Popup` and all the controls.
-* [**Geography and geometry**](./API/#geography-and-geometry) - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
-* [**User interaction handlers**](./API/#handlers) - The items in this section relate to the ways in which the map responds to user input.
-* [**Sources**](./API/#sources) - This section describes the source types MapLibre GL JS can handle besides the ones described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
-* [**Event Related**](./API/#event-related) - This section describes the different types of events that MapLibre GL JS can raise.
+* [**Main**](./API/README.md) - The Main section holds the following classes
+    * [`Map`](./API/classes/maplibregl.Map.md) object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
+    * [`MaplibreGL`](./API/classes/default.md) object is MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
+* [**Markers and Controls**](./API/README.md#markers-and-controls) - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element. This consists of `Marker`, `Popup` and all the controls.
+* [**Geography and geometry**](./API/README.md#geography-and-geometry) - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
+* [**User interaction handlers**](./API/README.md#handlers) - The items in this section relate to the ways in which the map responds to user input.
+* [**Sources**](./API/README.md#sources) - This section describes the source types MapLibre GL JS can handle besides the ones described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
+* [**Event Related**](./API/README.md#event-related) - This section describes the different types of events that MapLibre GL JS can raise.
 
 Each section describes classes or objects as well as their **properties**, **parameters**, **instance members**, and associated **events**. Many sections also include inline code examples and related resources.
 

mkdocs.yml

@@ -1,6 +1,8 @@
 site_name: MapLibre GL JS
 site_url: https://www.maplibre.org/maplibre-gl-js/docs/
 repo_url: https://github.com/maplibre/maplibre-gl-js/
+extra_css:
+  - assets/extra.css
 theme:
   name: 'material'
   favicon: https://maplibre.org/favicon.ico

test/examples/cooperated-gestures.html → test/examples/cooperative-gestures.html

@@ -18,15 +18,14 @@
 <script>
     const map = new maplibregl.Map({
         container: 'map',
-        style:
-        'https://api.maptiler.com/maps/streets/style.json?key=get_your_own_OpIi9ZULNHzrESv6T2vL',
+        style: 'https://demotiles.maplibre.org/style.json',
         center: [-74.5, 40],
         cooperativeGestures: {
             windowsHelpText: 'Utilice Ctrl + desplazamiento para hacer zoom en el mapa.',
             macHelpText: 'Use ⌘ + desplazamiento para hacer zoom en el mapa.',
             mobileHelpText: 'Usa dos dedos para mover el mapa.',
         },
-        zoom: 9
+        zoom: 4
     });
     map.addControl(new maplibregl.FullscreenControl());
 </script>