dhis2 · BRaimbault · May 15, 2026 · May 15, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.prettierignore b/.prettierignore
@@ -4,7 +4,8 @@ src/locales
 build
 cypress/fixtures/*
 cypress.env.json
-docs
+docs/maps.md
+docs/resources/
 colorbrewer.js
 
 

diff --git a/docs/maps.md b/docs/maps.md
diff --git a/docs/resources/images/maps_ee_layer_dialog_DATA.png b/docs/resources/images/maps_ee_layer_dialog_DATA.png
diff --git a/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png
diff --git a/docs/resources/images/maps_ee_layer_dialog_PERIOD.png b/docs/resources/images/maps_ee_layer_dialog_PERIOD.png
diff --git a/docs/resources/images/maps_ee_layer_dialog_STYLE.png b/docs/resources/images/maps_ee_layer_dialog_STYLE.png
diff --git a/docs/resources/images/maps_event_layer_dialog_DATA.png b/docs/resources/images/maps_event_layer_dialog_DATA.png
diff --git a/docs/resources/images/maps_event_layer_dialog_FILTER.png b/docs/resources/images/maps_event_layer_dialog_FILTER.png
diff --git a/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png
diff --git a/docs/resources/images/maps_event_layer_dialog_PERIOD.png b/docs/resources/images/maps_event_layer_dialog_PERIOD.png
diff --git a/docs/resources/images/maps_event_layer_dialog_STYLE.png b/docs/resources/images/maps_event_layer_dialog_STYLE.png
diff --git a/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png
diff --git a/docs/resources/images/maps_facility_layer_dialog_STYLE.png b/docs/resources/images/maps_facility_layer_dialog_STYLE.png
diff --git a/docs/resources/images/maps_geojson_external_layer_style.png b/docs/resources/images/maps_geojson_external_layer_style.png
diff --git a/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png
diff --git a/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png b/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png
diff --git a/docs/resources/images/maps_thematic_layer_dialog_STYLE.png b/docs/resources/images/maps_thematic_layer_dialog_STYLE.png
diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png b/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png
diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png
diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png b/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png
diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png b/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png
diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png b/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png
diff --git a/docs/src/00-header.md b/docs/src/00-header.md
@@ -0,0 +1 @@
+# Using the Maps app { #using_maps }
diff --git a/docs/src/01-about.md b/docs/src/01-about.md
@@ -0,0 +1,84 @@
+## About the Maps app { #about_maps }
+
+The Maps app was introduced in release 2.29 as a replacement for the original GIS app, offering a
+more intuitive and user-friendly interface. Since version 2.34, the mapping engine is based on WebGL
+technology, capable of showing thousands of features on a map simultaneously.
+
+> **Note**
+>
+> The Maps app requires WebGL. Visit [get.webgl.org](https://get.webgl.org) to verify that WebGL is
+> working in your browser or to troubleshoot display issues.
+
+With the Maps app, you can overlay multiple layers and choose from different basemaps. Supported
+layer types include thematic maps, events, tracked entities, facilities, org unit boundaries, and
+Earth Engine data such as population, elevation, or climate indicators. You can label features,
+search and filter data, and save or share maps with other users, or download them as an image. Saved
+maps can be added to dashboards in the **Dashboard** app. Thematic layers also integrate with the
+**Data Visualizer** app, letting you open the same data as a chart.
+
+> **Note**
+>
+> To use predefined legends in the **Maps** app, you need to create them first in the
+> **Maintenance** app.
+
+![](../resources/images/maps_main.png)
+
+### Layers panel
+
+The **layer panel** on the left side of the workspace shows an overview of the layers for the
+current map:
+
+-   As layers are added, using the **(+) Add layer** button, they are arranged and managed in this
+    panel.
+
+-   The **basemap** card is always shown at the bottom of the panel. See
+    [Basemaps](#using_maps_basemaps) for available options.
+
+-   The small arrow button to the right of the layer panel, at the top, allows the panel to be
+    hidden or shown.
+
+Each layer is represented by a card in the panel. Along the top of the card are a grab handle for
+reordering layers with the mouse, the layer title, and an arrow to collapse or expand the card. The
+middle of the card shows the layer legend where applicable. Along the bottom of the card from left
+to right are:
+
+-   An edit (pencil) button opens the layer configuration dialog.
+
+-   An eye symbol toggles the visibility of the layer.
+
+-   A slider modifies the layer transparency.
+
+-   A more actions (three dots) button provides additional options, including showing or hiding the
+    data table, downloading the layer data, and removing the layer.
+
+### Map controls
+
+-   The **+** and **-** buttons on the map allow you to zoom in and out of the map respectively. The
+    mouse scroll wheel zoom is continuous, allowing you to fit the map perfectly to your content.
+
+-   The **rotate map** button (triangle arrows) allows you to rotate and tilt the map to enhance the
+    view of your data. Press and hold the button (or hold the Control key on your keyboard) while
+    moving your mouse to change the map view. Click the button again to reset the view.
+
+-   **Fullscreen** (four arrows) allows you to view the map in fullscreen. To exit fullscreen, click
+    the button again or press the escape key on your keyboard.
+
+-   **Zoom to content** (bounded magnifying glass symbol) automatically adjusts the zoom level and
+    map center position to put the data on your map in focus.
+
+-   **Search** (magnifying glass symbol) allows searching for and jumping to a location on the map.
+
+-   The **ruler** button allows you to measure distances and areas on the map.
+
+-   Right-click on the map to display the longitude and latitude of that location.
+
+### File menu
+
+-   The **File** button near the top left allows you to open and save maps. See
+    [using the maps file menu](#using_maps_file_menu) for more detailed information.
+
+-   The **Download** button next to the File button allows you to download the current map as a PNG
+    image.
+
+-   The **Interpretations** button at top right opens an interpretations panel on the right side of
+    the workspace. See [viewing interpretations](#mapsInterpretation) for more information.
diff --git a/docs/src/02-create-map.md b/docs/src/02-create-map.md
@@ -0,0 +1,35 @@
+## Create a new map { #using_maps_create_map }
+
+When you open the Maps app, you start with an empty map canvas and the default basemap selected. If
+a map is already open, start a new one using **File** > **New**. You can change the basemap at any
+time from the basemap card in the layer panel (see [Basemaps](#using_maps_basemaps)).
+
+To add a layer, click the **(+) Add layer** button in the top left. The layer selection dialog
+opens:
+
+![](../resources/images/maps_layer_selection.png)
+
+Available layer types are:
+
+-   [**Thematic**](#using_maps_thematic_layer): Visualize data values (indicators or data elements)
+    aggregated by org unit.
+-   [**Events**](#using_maps_event_layer): Display individual events from event or tracker programs.
+-   [**Tracked entities**](#using_maps_tracked_entity_layer): Display tracked entities and their
+    relationships on the map.
+-   [**Facilities**](#using_maps_facility_layer): Display facilities as icons based on their
+    coordinates.
+-   [**Org units**](#using_maps_org_unit_layer): Display org unit boundaries.
+
+In addition, several layers may be provided by [Google Earth Engine](#using_maps_gee) (such as
+population, elevation, or climate indicators) and
+[other external services](#using_maps_external_map_layers). Various Google Earth Engine layer
+sources are available if the Google Earth Engine API key has been set up (see
+[documentation](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API)).
+
+> **Note**
+>
+> The [**Maps app administrator**](#maps_app_administrator) can:
+>
+> -   Select the sources for Google Earth Engine layers available to other users via the **Manage
+>     available layer sources** button.
+> -   Add external layer sources in the Maintenance app.
diff --git a/docs/src/03-basemaps.md b/docs/src/03-basemaps.md
@@ -0,0 +1,36 @@
+## Basemaps { #using_maps_basemaps }
+
+A basemap provides the background map on which your data layers are displayed. You can select and
+configure the basemap from the **basemap** card at the bottom of the layer panel.
+
+The following basemaps are available by default:
+
+-   **OSM Light**: A minimal, light-colored map based on OpenStreetMap data. This is the default
+    basemap.
+-   **OSM Detailed**: Contains more map features and place names.
+-   **Sentinel-2 EOX**: Cloud-free satellite imagery showing natural-color views of the Earth's
+    surface at 10m resolution.
+
+If a Bing Maps or Azure Maps API key has been configured by a system administrator, four additional
+basemaps become available from each provider. Both providers offer the same four styles, prefixed
+with the provider name — for example, **Bing Road** and **Azure Road**:
+
+-   **Road**: Shows roads, borders and places.
+-   **Dark**: A dark-themed road map. Useful when the colors on your data layers are bright.
+-   **Aerial**: Satellite and detailed aerial imagery.
+-   **Aerial Labels**: Aerial imagery with place name labels.
+
+A [**Maps app administrator**](#maps_app_administrator) can also add external basemaps via the
+Maintenance app. These appear in the basemap card alongside the default basemaps.
+
+Basemap layers are represented by a card in the layer panel. The card shows the list of available
+basemaps with the current one highlighted. Controls at the bottom allow you to toggle the basemap
+visibility and adjust its transparency.
+
+![](../resources/images/maps_basemap_card.png)
+
+> **Note**
+>
+> Bing Maps is being retired. See the [Bing Maps Blog](https://aka.ms/BMERetirementAnnouncement) for
+> the retirement announcement. For migration to Azure Maps, consult the
+> [Bing Maps Migration Overview](https://learn.microsoft.com/azure/azure-maps/migrate-bing-maps-overview).