From 65514159320e9e395e764d3b7528a184eabf6f47 Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Thu, 7 Aug 2025 17:28:10 +0200
Subject: [PATCH 1/6] Format and organize pages in Visualize Data section

---
 .vitepress/config.mts       |   9 +-
 docs/3d-tiles.md            |  82 +++++
 docs/3d.md                  |  82 -----
 docs/mapbox-vector-tiles.md | 189 +++++++---
 docs/terrain-service.md     |  67 ++++
 docs/wms.md                 | 123 ++++++-
 docs/wmts.md                | 701 +++++++-----------------------------
 docs/xyz.md                 |  68 ++++
 8 files changed, 586 insertions(+), 735 deletions(-)
 create mode 100644 docs/3d-tiles.md
 delete mode 100644 docs/3d.md
 create mode 100644 docs/terrain-service.md
 create mode 100644 docs/xyz.md

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index d8b4a13..6e9184d 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -147,13 +147,18 @@ function visualizeDataItems(): DefaultTheme.SidebarItem[] {
   return [
     { text: "WMS", link: "/docs/wms" },
     { text: "WMTS", link: "/docs/wmts" },
+    { text: "XYZ", link: "/docs/xyz" },
     {
       text: "Mapbox Vector Tiles",
       link: "/docs/mapbox-vector-tiles",
     },
     {
-      text: "3D",
-      link: "/docs/3d",
+      text: "Terrain Service",
+      link: "/docs/terrain-service",
+    },
+    {
+      text: "3D Tiles",
+      link: "/docs/3d-tiles",
     },
   ];
 }
diff --git a/docs/3d-tiles.md b/docs/3d-tiles.md
new file mode 100644
index 0000000..4b48fee
--- /dev/null
+++ b/docs/3d-tiles.md
@@ -0,0 +1,82 @@
+# 3D Tiles
+
+A RESTFul implementation of [Cesium 3D Tiles specification](https://github.com/CesiumGS/3d-tiles).
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/<Z>/<X>/<Y>.b3dm" method="GET" />
+
+## Request Details
+
+### Path Parameters
+
+| Parameter | Example                          | Description                                             |
+| --------- | -------------------------------- | ------------------------------------------------------- |
+| layerName | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer (see below)          |
+| Version   | v1                               | API version. `v1` means tiles generated with 3D Tiles   |
+| Time      | 20240501                         | Date of tileset generation in (ISO-8601, e.g. YYYYMMDD) |
+| Z         | 7                                | Zoom level                                              |
+| X         | 54                               | Tile column index                                       |
+| Y         | 21                               | Tile row index                                          |
+
+**Available values for `<layerName>`:**
+
+- `ch.swisstopo.swissbuildings3d.3d`
+- `ch.swisstopo.swisstlm3d.3d`
+- `ch.swisstopo.swissnames3d.3d`
+- `ch.swisstopo.vegetation.3d`
+
+### Metadata Service
+
+The `tileset.json` file describes the available set of tiles.
+In order to use this service you can use [CesiumJS](https://github.com/CesiumGS/cesium).
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/tileset.json" method="GET" />
+
+| Parameter       | Example                          | Description                                    |
+| --------------- | -------------------------------- | ---------------------------------------------- |
+| Time (optional) | 20201203                         | Date of tile generation in (ISO-8601).         |
+| LayerName       | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer (see below) |
+
+## Examples
+
+A 3D tile
+
+```http
+https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm
+```
+
+<ExampleCodeBlock
+request="curl https://3d.geo.admin.ch/ch.swisstopo.vegetation.3d/v1/tileset.json"
+example='{
+  "asset": {
+    "version": "1.0",
+    "extras": {
+      "ion": {
+        "georeferenced": true,
+        "movable": false
+      }
+    }
+  },
+  "geometricError": 54.7213621044866,
+  "root": {
+    "boundingVolume": {
+      "region": [
+        0.10395173048091878, 0.799669540091651, 0.18307746929258154,
+        0.83441919811829, -10003.500000067055, 2799.070391970873
+      ]
+    },
+    "geometricError": 54.7213621044866,
+    "refine": "ADD",
+    "children": [...]
+  }
+}'
+/>
+
+## Examples: Cesium
+
+Example Geoadmin Terrain, Buildings and WMTS implementation using Cesium.
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
+  Geoadmin Terrain, Buildings and WMTS CesiumJS integration</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/3d.md b/docs/3d.md
deleted file mode 100644
index 7c12fb2..0000000
--- a/docs/3d.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# 3D
-
-## Terrain Service
-
-A RESTFul implementation of "[Cesium](http://cesiumjs.org/)" [Quantized
-Mesh](https://github.com/AnalyticalGraphicsInc/quantized-mesh) terrain
-service. Terrain tiles are served according to the [Tile Map Service
-(TMS)](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) layout
-and global-geodetic profile.
-
-### URL
-
-<https://3d.geo.admin.ch>
-
-### Metadata Service
-
-The <span class="title-ref">layer.json</span> file determines which
-terrain tiles are available.
-
-- <https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/layer.json>
-  (alway most recent terrain tiles)
-- <https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/layer.json>
-  (terrain tiles of the date 20201203)
-
-### Parameters
-
-A request is in the form:
-
-    GET https://<ServerName>/ch.swisstopo.terrain.3d/<Version>/<Time>/<Zoom>/<X>/<Y>.<FormatExtension>
-
-with the following parameters:
-
-| Parameter       | Example                            | Explanation                                                          |
-| --------------- | ---------------------------------- | -------------------------------------------------------------------- |
-| ServerName      | 3d.geo.admin.ch                    |                                                                      |
-| Version         | v1                                 | v1 means terrain tiles generated with cesium tiles                   |
-| Layername       | ch.swisstopo.terrain.3d (constant) | The name of the terrain layer. (only one terrain layer is available) |
-| Time            | 20201203                           | Date of tile generation in (ISO-8601).                               |
-| Zoom            | 12                                 | Zoom level (see below)                                               |
-| X               | 4309                               | The longitue index                                                   |
-| Y               | 3111                               | The latitude index                                                   |
-| FormatExtension | terrain                            | The file extension (a gzipped binary terrain file)                   |
-
-### Example
-
-- A [Terrain
-  tile](https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/7/136/98.terrain?v=3924.0.0)
-
-## 3D Tiles
-
-A RESTFul implementation of "[Cesium](http://cesiumjs.org/)" [3D Tiles
-specification](https://github.com/CesiumGS/3d-tiles).
-
-### URL
-
-- <https://3d.geo.admin.ch>
-
-### Metadata Service
-
-The <span class="title-ref">tileset.json</span> file describes the
-available set of tiles. In order to use this service you can use
-[CesiumJS](https://github.com/CesiumGS/cesium).
-
-Currently, 3 technical layers (ch.swisstopo.swisstlm3d.3d,
-ch.swisstopo.swissnames3d.3d, ch.swisstopo.vegetation.3d) are available
-and they contains all available 3D objects.
-
-Most recent 3D tiles:
-
-- <https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/tileset.json>
-- <https://3d.geo.admin.ch/ch.swisstopo.vegetation.3d/v1/tileset.json>
-
-3D tiles of a specific date:
-
-- <https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/tileset.json>
-- <https://3d.geo.admin.ch/ch.swisstopo.vegetation.3d/v1/20240412/tileset.json>
-- <https://3d.geo.admin.ch/3d-tiles/ch.swisstopo.swissnames3d.3d/20180716/tileset.json>
-
-### Example
-
-- A [3D
-  tile](https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm)
diff --git a/docs/mapbox-vector-tiles.md b/docs/mapbox-vector-tiles.md
index 13ec4aa..4642764 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/mapbox-vector-tiles.md
@@ -1,65 +1,148 @@
 # Mapbox Vector Tiles
 
-A RESTFul implementation of [Mapbox Vector
-Tiles](https://www.mapbox.com/vector-tiles). See
-[description](https://www.geo.admin.ch/en/geo-services/geo-services/portrayal-services-web-mapping/vector_tiles_service.html)
+A RESTFul implementation of [Mapbox Vector Tiles](https://www.mapbox.com/vector-tiles).
 
-The service provides both _tiles_ and _styles_ that the customer can
-use.
+The service provides both tiles and styles with the following operations:
 
-### GetStyle
+::: tip Available datasets and styles as Mapbox Vector Tiles
 
-A current (latest version) style request is in the following form:
-
-    GET <Scheme>://<ServerName>/styles/<layername>/style.json
-
-example of current maplibre styles of light base map and imagery base
-map:
-
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.basemap.vt/style.json>
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/style.json>
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.imagerybasemap.vt/style.json>
-
-### GetTile
-
-A tile request is in the following form:
-
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>/<zoomlevel>/<x>/<y>.pbf
-
-example of one pbf tile:
+The list of current datasets and styles is available visiting the [official service description](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data).
+:::
 
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/7/67/44.pbf>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf>
+## GetStyle
 
-### GetTileSets
-
-MBTiles for storing tiled map data in SQLite databases for immediate or
-offline usage and for efficient transfer. A MBtileSet request is in the
-following form:
-
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>/<LayerName>.mbtiles
-
-example of the .mbtiles file:
-
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/ch.swisstopo.relief.vt.mbtiles>
-
-### Available datasets and styles as mapbox vector tiles
-
-The list of current datasets and styles is available visiting the
-[official service
-description](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data)
+A current (latest version) style request is in the following form:
 
-### Metadata Service
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/styles/{layerName}/style.json" method="GET" />
 
-Each tileset has a corresponding metatdata <span
-class="title-ref">json</span> file that describes the available set of
-tiles. The URL of the metadata <span class="title-ref">json</span> file
-is :
+| **Parameter**            | **Description**              |
+| ------------------------ | ---------------------------- |
+| **layerName (optional)** | Layer to perform the request |
 
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json
+## GetTile
 
-example of tileset:
+A tile request is in the following form:
 
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/tiles.json>
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{zoomLevel}/{x}/{y}.pbf" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+| zoomLevel     | 7                    | Zoom level (integer)                        |
+| x             | 67                   | Tile column (X coordinate in the tile grid) |
+| y             | 44                   | Tile row (Y coordinate in the tile grid)    |
+
+## GetTileSets
+
+MBTiles for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
+A MBtileSet request is in the following form:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{layerName}.mbtiles" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+
+## Metadata Service
+
+Each tileset has a corresponding metatdata json file that describes the available set of tiles.
+The URL of the metadata file is :
+
+<!-- GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json -->
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/tiles.json" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+
+## Examples
+
+**GetStyle** example for light base map:
+
+<ExampleCodeBlock
+request="curl https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/style.json"
+example='{
+  "version": 8,
+  "id": "0197406a-5d2f-7168-bee5-f191641499b7",
+  "name": "lightbasemap_v1.19.0",
+  "sources": {
+    "relief_v1.0.0": {
+      "url": "https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/tiles.json",
+      "type": "vector"
+    },
+    "base_v1.0.0": {
+      "url": "https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json",
+      "type": "vector"
+    }
+  },
+  "layers": [...],
+  "metadata": {...},
+  "glyphs": "https://vectortiles.geo.admin.ch/fonts/{fontstack}/{range}.pbf",
+  "sprite": "https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/sprite/sprite",
+  "bearing": 0,
+  "pitch": 0,
+  "center": [8.349961425056108, 46.81133904939108],
+  "zoom": 7.2512975045452235,
+  "transition": {...}
+}'
+/>
+
+**GetTile** request example for one `.pbf` tile in relief layer:
+
+```http
+https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf
+```
+
+<br/>
+
+**GetTileSet** example for `.mbtiles` file in base layer:
+
+```http
+https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
+```
+
+<br/>
+
+**Metadata** example for base layer:
+
+<ExampleCodeBlock
+request="curl https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json"
+example='{
+  "basename": "tiles/ch.swisstopo.base.vt/v1.0.0",
+  "name": "Basiskarte_v1.0.0",
+  "description": "A tileset showcasing all SwissTopo layers.",
+  "attribution": "© swisstopo",
+  "version": "v1.0.0",
+  "format": "pbf",
+  "minzoom": 0,
+  "maxzoom": 14,
+  "scale": 1,
+  "vector_layers": [...],
+  "profile": "mercator",
+  "scheme": "xyz",
+  "bounds": [...],
+  "center": [...],
+  "tilejson": "2.0.0",
+  "tiles": [
+    "https://vectortiles0.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles1.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles2.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles3.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles4.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf"
+  ]
+}
+'
+/>
+
+## Examples: MapLibre
+
+Light Base Map example using MapLibre
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Maplibre Vector Tiles" src="https://codepen.io/geoadmin/embed/GvgLvj?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/GvgLvj">
+  Maplibre Vector Tiles</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/terrain-service.md b/docs/terrain-service.md
new file mode 100644
index 0000000..53446ec
--- /dev/null
+++ b/docs/terrain-service.md
@@ -0,0 +1,67 @@
+# Terrain Service
+
+A RESTFul implementation of [Cesium Quantized Mesh](https://github.com/AnalyticalGraphicsInc/quantized-mesh) terrain service.
+Terrain tiles are served according to the [Tile Map Service (TMS)](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) layout and global-geodetic profile.
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/<Version>/<Time>/<Zoom>/<X>/<Y>.terrain" method="GET" />
+
+## Request Details
+
+### Path Parameters
+
+| Parameter  | Example         | Description                                        |
+| ---------- | --------------- | -------------------------------------------------- |
+| ServerName | 3d.geo.admin.ch |                                                    |
+| Version    | v1              | v1 means terrain tiles generated with cesium tiles |
+| Time       | 20201203        | Date of tile generation in (ISO-8601).             |
+| Zoom       | 12              | Zoom level                                         |
+| X          | 4309            | The longitue index                                 |
+| Y          | 3111            | The latitude index                                 |
+
+## Metadata Service
+
+The `layer.json` file determines which terrain tiles are available.
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/<Time>/layer.json" method="GET" />
+
+| Parameter       | Example  | Description                            |
+| --------------- | -------- | -------------------------------------- |
+| Time (optional) | 20201203 | Date of tile generation in (ISO-8601). |
+
+## Examples
+
+A terrain tile:
+
+```http
+https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/7/136/98.terrain?v=3924.0.0
+```
+
+<br/>
+
+Metadata for the date `20201203`:
+<ExampleCodeBlock
+request="curl https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/layer.json"
+example='{
+  "attribution": "Put something there",
+  "available": [...],
+  "bounds": [-180, -90, 180, 90],
+  "description": "Nice terrains",
+  "format": "quantized-mesh-1.0",
+  "minzoom": 0,
+  "projection": "EPSG:4326",
+  "scheme": "tms",
+  "tilejson": "2.1.0",
+  "tiles": ["{z}/{x}/{y}.terrain?v={version}"],
+  "version": "3924.0.0"
+}'
+/>
+
+## Examples: Cesium
+
+Example Geoadmin Terrain, Buildings and WMTS implementation using Cesium.
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
+  Geoadmin Terrain, Buildings and WMTS CesiumJS integration</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/wms.md b/docs/wms.md
index 96489a0..6347dfe 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -1,25 +1,20 @@
-# Web Mapping Services WMS: Available services an data
+# Web Map Service (WMS)
 
-The BGDI supports the federal offices by setting up WMS services. You can freely use the following examples and integrate them into any GIS system.
+Federal offices make part of their data available via the WMS - Federal Spatial Data Infrastructure (FSDI) service.
+The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are also presented in map.geo.admin.ch.
+The WMS-FSDI can be used free of charge and provides access to public geodata.
 
-Federal offices make part of their data available via the WMS-FSDI service. Users of geographic information systems (GIS) can integrate these services into their software using the service's metadata (Capabilities).
+WMS requests can perform the following operations:
 
-The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are also presented in map.geo.admin.ch. The WMS-FSDI can be used free of charge and provides access to public geodata. The requests GetCapabilities, GetMap, GetFeatureInfo and GetLegendGraphic are supported.
+## GetCapabilities
 
-The WMS-FSDI is accessible via a secure connection. The URL is https://wms.geo.admin.ch/.
+The GetCapabilites document provides informations about the service, along with layer description, both in german and french.
 
-In most geographic information systems, specifying the above URL is sufficient for using the data. Otherwise, the GetCapabilities request is: https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities
-(the choice of the language [de,fr,it,en] is done by adding the parameterlang=en)
+<ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities&LANG=<Lang>" method="GET" />
 
-Example of a GetMap request:
-https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
-
-Example of a GetFeatureInfo request:
-https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&FORMAT=image%2Fpng&TRANSPARENT=true&QUERY_LAYERS=ch.bafu.bundesinventare-bln&LAYERS=ch.bafu.bundesinventare-bln&FEATURE_COUNT=10&INFO_FORMAT=text%2Fplain&LANG=en&I=50&J=50&CRS=EPSG%3A2056&STYLES=&WIDTH=101&HEIGHT=101&BBOX=2609000%2C1123050%2C2614050%2C1128100
-(the choice of the language [de,fr,it,en] is done by adding the parameter lang=en)
-
-Example of a GetLegendGraphic request:
-https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+| **Parameter**       | **Description**                                               |
+| ------------------- | ------------------------------------------------------------- |
+| **Lang (optional)** | The language. Supported values: `de`, `fr` (Defaults to `de`) |
 
 ### Supported projections:
 
@@ -38,9 +33,61 @@ https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAY
 - EPSG:32633 WGS 84 / UTM zone 33N
 - EPSG:900913 Google Maps Global Mercator -- Spherical Mercator (unofficial - used in open source projects / OSGEO)
 
-### Intended use
+## GetMap
+
+<ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=<Layers>&STYLES=<Styles>&CRS=<CRS>&BBOX=<BBOX>&WIDTH=<Width>&HEIGHT=<Height>&FORMAT=<Format>" method="GET" />
+
+Use the following parameters to define your request:
+
+| **Parameter** | **Example**                     | **Description**                                                                     |
+| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                     |
+| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                            |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
+| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
+| Width         | 800                             | Width of the output image in pixels.                                                |
+| Height        | 582                             | Height of the output image in pixels.                                               |
+| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                              |
+
+## GetFeatureInfo
+
+<ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&LAYERS=<Layers>&QUERY_LAYERS=<QueryLayers>&STYLES=<Styles>&CRS=<CRS>&BBOX=<BBOX>&WIDTH=<Width>&HEIGHT=<Height>&I=<I>&J=<J>&INFO_FORMAT=<InfoFormat>&FEATURE_COUNT=<FeatureCount>&LANG=<Lang>&FORMAT=<Format>&TRANSPARENT=<Transparent>" method="GET" />
+
+Use the following parameters to define your request:
+
+| **Parameter** | **Example**                     | **Description**                                                                     |
+| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                     |
+| QueryLayers   | ch.bafu.bundesinventare-bln     | Comma-separated list of layers to query for information.                            |
+| Styles        |                                 | Comma-separated list of styles. Use `default` or leave empty if unsure.             |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
+| BBOX          | 2609000,1123050,2614050,1128100 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
+| Width         | 101                             | Width of the output image in pixels.                                                |
+| Height        | 101                             | Height of the output image in pixels.                                               |
+| I             | 50                              | X coordinate (pixel column) of the point to query, starting from 0 (left).          |
+| J             | 50                              | Y coordinate (pixel row) of the point to query, starting from 0 (top).              |
+| InfoFormat    | text/plain                      | Format of the returned feature info (e.g., `text/plain`, `application/json`).       |
+| FeatureCount  | 10                              | Maximum number of features to return.                                               |
+| Lang          | en                              | Language for the response. Supported values: `de`, `fr`, `it`, `en`.                |
+| Format        | image/png                       | Output image format (should match the map request).                                 |
+| Transparent   | true                            | Whether the background should be transparent (`true` or `false`).                   |
+
+## GetLegendGraphic
+
+<ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS={Layers}&STYLES={Styles}&LANG={Lang}&CRS={CRS}&BBOX={BBOX}&WIDTH={Width}&HEIGHT={Height}&FORMAT={Format}" method="GET" />
+
+Use the following parameters to define your request:
 
-Web Map Services are especially interesting if you want to use continuously updated geodata in a predefined representation. Internet access is mandatory.
+| **Parameter** | **Example**                     | **Description**                                                                     |
+| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names for which to request the legend.                |
+| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                            |
+| Lang          | en                              | Language for the legend. Supported values: `de`, `fr`, `it`, `en`.                  |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
+| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
+| Width         | 800                             | Width of the output image in pixels.                                                |
+| Height        | 582                             | Height of the output image in pixels.                                               |
+| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                              |
 
 ### Further information
 
@@ -52,3 +99,43 @@ Web Map Services are especially interesting if you want to use continuously upda
 - [MapInfo](http://www.twiav.nl/files/TWIAV_TIP_MI002.pdf)
 - [Quantum GIS](http://www.qgis.org/en/docs/index.html)
 - [Exemple 1 - Mappetizer](http://www.mappetizer.de/de/beispiele/wms_bafu_suisse/index.html)
+
+## Examples
+
+Example of GetMap request:
+
+```bash
+curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+display demo.jpg
+```
+
+The request will display the following image:
+
+<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
+
+Example of a GetFeatureInfo request:
+
+<ExampleCodeBlock
+request="curl https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&FORMAT=image%2Fpng&TRANSPARENT=true&QUERY_LAYERS=ch.bafu.bundesinventare-bln&LAYERS=ch.bafu.bundesinventare-bln&FEATURE_COUNT=10&INFO_FORMAT=text%2Fplain&LANG=en&I=50&J=50&CRS=EPSG%3A2056&STYLES=&WIDTH=101&HEIGHT=101&BBOX=2609000%2C1123050%2C2614050%2C1128100"
+exampleLang="txt"
+example="GetFeatureInfo results:
+Layer 'ch.bafu.bundesinventare-bln'
+  Feature 1362: 
+    No. = '1716'
+    Name = 'Pfynwald – Illgraben'
+    Area_ha = '5064.29'
+    Objectsheet = 'https://data.geo.admin.ch/ch.bafu.bundesinventare-bln/objectsheets/2017revision/nr1716.pdf'
+    Subarea-No. = '0'
+    Subarea = ''"
+/>
+
+Example of a GetLegendGraphic request:
+
+```bash
+curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+display demo.jpg
+```
+
+The request will display the following image:
+
+<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
diff --git a/docs/wmts.md b/docs/wmts.md
index c5c3c44..da804d0 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -1,526 +1,25 @@
-# WMTS
+# Web Map Tile Service (WMTS)
 
-A RESTFul implementation of the
-[WMTS](http://www.opengeospatial.org/standards/wmts)
-[OGC](http://www.opengeospatial.org/) standard. For detailed
-information, see [WMTS OGC
-standard](http://www.opengeospatial.org/standards/wmts)
+A RESTFul implementation of the [WMTS OGC Standard](http://www.opengeospatial.org/standards/wmts).
 
-<div class="note">
-
-<div class="title">
-
-Note
-
-</div>
-
-Only the RESTFul request encoding to <span
-class="title-ref">GetTile</span> is implemented, not the <span
-class="title-ref">GetLegend</span> and <span
-class="title-ref">GetFeatureInfo</span>. No KVP and SOAP request
+:::warning
+Only the RESTFul request encoding to `GetTile` is implemented, not the `GetLegend` and `GetFeatureInfo`. No KVP and SOAP request
 encoding is supported.
+:::
 
-</div>
-
-### GetCapabilities
-
-The GetCapabilites document provides informations about the service,
-along with layer description, both in german and french.
-
-<https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml>
-
-<https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml?lang=fr>
-
-### GetTile
-
-    GET <Scheme>://<ServerName>/<ProtocoleVersion>/<LayerName>/<Stylename>/<Time>/<TileMatrixSet>/<TileSetId>/<TileRow>/<TileCol>.<FormatExtension>
-
-with the following parameters:
-
-| Parameter                 | Example                        | Explanation                                                                                                                                                                                                                                                                                                                                                               |
-| ------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scheme ServerName         | https wmts\[0-9\].geo.admin.ch | The scheme type                                                                                                                                                                                                                                                                                                                                                           |
-| Version                   | 1.0.0                          | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                     |
-| Layername                 | ch.bfs.arealstatistik-1997     | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
-| StyleName                 | default                        | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
-| Time                      | 2010, 2010-01                  | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
-| TileMatrixSet             | 2056 (constant)                | EPSG code for LV03/CH1903                                                                                                                                                                                                                                                                                                                                                 |
-| TileSetId TileRow TileCol | 22 236 284                     | Zoom level (see below)                                                                                                                                                                                                                                                                                                                                                    |
-| FormatExtension           | png                            | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
-
-The _\<TileMatrixSet\>_ **21781** is as follow defined:
-
-    MinX              420000
-    MaxX              900000
-    MinY               30000
-    MaxY              350000
-    TileWidth            256
-
-With the _\<tileOrigin\>_ in the top left corner of the bounding box.
-
-<table>
-<thead>
-<tr class="header">
-<th>Resolution [m]</th>
-<th>Zoomlevel</th>
-<th>Map zoom</th>
-<th>Tile width m</th>
-<th>Tiles X</th>
-<th>Tiles Y</th>
-<th>Tiles</th>
-<th>Approx. scale at 96 dpi per zoom level</th>
-</tr>
-</thead>
-<tbody>
-<tr class="odd">
-<td><blockquote>
-<p>4000 3750 3500 3250 3000 2750 2500 2250 2000 1750 1500 1250 1000
-750</p>
-</blockquote></td>
-<td><blockquote>
-<p>0 1 2 3 4 5 6 7 8 9 10 11 12 13</p>
-</blockquote></td>
-<td></td>
-<td><blockquote>
-<dl>
-<dt>1024000</dt>
-<dd>
-<p>960000 896000 832000 768000 704000 640000 576000 512000 448000 384000
-320000 256000 192000</p>
-</dd>
-</dl>
-</blockquote></td>
-<td><blockquote>
-<p>1 1 1 1 1 1 1 1 1 2 2 2 2 3</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 1 1 1 1 1 1 1 1 1 1 1 2 2</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 1 1 1 1 1 1 1 1 2 2 2 4 6</p>
-</blockquote></td>
-<td></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>650</p>
-</blockquote></td>
-<td><blockquote>
-<p>14</p>
-</blockquote></td>
-<td><blockquote>
-<p>0</p>
-</blockquote></td>
-<td><blockquote>
-<p>166400</p>
-</blockquote></td>
-<td><blockquote>
-<p>3</p>
-</blockquote></td>
-<td><blockquote>
-<p>2</p>
-</blockquote></td>
-<td><blockquote>
-<p>6</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 2'456'694</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>500</p>
-</blockquote></td>
-<td><blockquote>
-<p>15</p>
-</blockquote></td>
-<td><blockquote>
-<p>1</p>
-</blockquote></td>
-<td><blockquote>
-<p>128000</p>
-</blockquote></td>
-<td><blockquote>
-<p>4</p>
-</blockquote></td>
-<td><blockquote>
-<p>3</p>
-</blockquote></td>
-<td><blockquote>
-<p>12</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 1'889'765</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>250</p>
-</blockquote></td>
-<td><blockquote>
-<p>16</p>
-</blockquote></td>
-<td><blockquote>
-<p>2</p>
-</blockquote></td>
-<td><blockquote>
-<p>64000</p>
-</blockquote></td>
-<td><blockquote>
-<p>8</p>
-</blockquote></td>
-<td><blockquote>
-<p>5</p>
-</blockquote></td>
-<td><blockquote>
-<p>40</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 944'882</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>100</p>
-</blockquote></td>
-<td><blockquote>
-<p>17</p>
-</blockquote></td>
-<td><blockquote>
-<p>3</p>
-</blockquote></td>
-<td><blockquote>
-<p>25600</p>
-</blockquote></td>
-<td><blockquote>
-<p>19</p>
-</blockquote></td>
-<td><blockquote>
-<p>13</p>
-</blockquote></td>
-<td><blockquote>
-<p>247</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 377'953</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>50</p>
-</blockquote></td>
-<td><blockquote>
-<p>18</p>
-</blockquote></td>
-<td><blockquote>
-<p>4</p>
-</blockquote></td>
-<td><blockquote>
-<p>12800</p>
-</blockquote></td>
-<td><blockquote>
-<p>38</p>
-</blockquote></td>
-<td><blockquote>
-<p>25</p>
-</blockquote></td>
-<td><blockquote>
-<p>950</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 188'976</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>20</p>
-</blockquote></td>
-<td><blockquote>
-<p>19</p>
-</blockquote></td>
-<td><blockquote>
-<p>5</p>
-</blockquote></td>
-<td><blockquote>
-<p>5120</p>
-</blockquote></td>
-<td><blockquote>
-<p>94</p>
-</blockquote></td>
-<td><blockquote>
-<p>63</p>
-</blockquote></td>
-<td><blockquote>
-<p>5'922</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 75'591</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>10</p>
-</blockquote></td>
-<td><blockquote>
-<p>20</p>
-</blockquote></td>
-<td><blockquote>
-<p>6</p>
-</blockquote></td>
-<td><blockquote>
-<p>2560</p>
-</blockquote></td>
-<td><blockquote>
-<p>188</p>
-</blockquote></td>
-<td><blockquote>
-<p>125</p>
-</blockquote></td>
-<td><blockquote>
-<p>23'500</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 37'795</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>5</p>
-</blockquote></td>
-<td><blockquote>
-<p>21</p>
-</blockquote></td>
-<td><blockquote>
-<p>7</p>
-</blockquote></td>
-<td><blockquote>
-<p>1280</p>
-</blockquote></td>
-<td><blockquote>
-<p>375</p>
-</blockquote></td>
-<td><blockquote>
-<p>250</p>
-</blockquote></td>
-<td><blockquote>
-<p>93'750</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 18'898</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>2.5</p>
-</blockquote></td>
-<td><blockquote>
-<p>22</p>
-</blockquote></td>
-<td><blockquote>
-<p>8</p>
-</blockquote></td>
-<td><blockquote>
-<p>640</p>
-</blockquote></td>
-<td><blockquote>
-<p>750</p>
-</blockquote></td>
-<td><blockquote>
-<p>500</p>
-</blockquote></td>
-<td><blockquote>
-<p>375'000</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 9'449</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>2 1.5</p>
-</blockquote></td>
-<td><blockquote>
-<p>23 24</p>
-</blockquote></td>
-<td><blockquote>
-<p>9</p>
-</blockquote></td>
-<td><blockquote>
-<p>512 384</p>
-</blockquote></td>
-<td><blockquote>
-<p>938 1250</p>
-</blockquote></td>
-<td><blockquote>
-<p>625 834</p>
-</blockquote></td>
-<td><blockquote>
-<p>586'250 1'042'500</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 7'559</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>1</p>
-</blockquote></td>
-<td><blockquote>
-<p>25</p>
-</blockquote></td>
-<td><blockquote>
-<p>10</p>
-</blockquote></td>
-<td><blockquote>
-<p>256</p>
-</blockquote></td>
-<td><blockquote>
-<p>1875</p>
-</blockquote></td>
-<td><blockquote>
-<p>1250</p>
-</blockquote></td>
-<td><blockquote>
-<p>2'343'750</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 3'780</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>0.5</p>
-</blockquote></td>
-<td><blockquote>
-<p>26</p>
-</blockquote></td>
-<td><blockquote>
-<p>11</p>
-</blockquote></td>
-<td><blockquote>
-<p>128</p>
-</blockquote></td>
-<td><blockquote>
-<p>3750</p>
-</blockquote></td>
-<td><blockquote>
-<p>2500</p>
-</blockquote></td>
-<td><blockquote>
-<p>9'375'000</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 1'890</p>
-</blockquote></td>
-</tr>
-<tr class="even">
-<td><blockquote>
-<p>0.25</p>
-</blockquote></td>
-<td><blockquote>
-<p>27</p>
-</blockquote></td>
-<td><blockquote>
-<p>12</p>
-</blockquote></td>
-<td><blockquote>
-<p>64</p>
-</blockquote></td>
-<td><blockquote>
-<p>7500</p>
-</blockquote></td>
-<td><blockquote>
-<p>5000</p>
-</blockquote></td>
-<td><blockquote>
-<p>37'500'000</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 945</p>
-</blockquote></td>
-</tr>
-<tr class="odd">
-<td><blockquote>
-<p>0.1</p>
-</blockquote></td>
-<td><blockquote>
-<p>28</p>
-</blockquote></td>
-<td><blockquote>
-<p>13</p>
-</blockquote></td>
-<td><blockquote>
-<p>25.6</p>
-</blockquote></td>
-<td><blockquote>
-<p>18750</p>
-</blockquote></td>
-<td><blockquote>
-<p>12500</p>
-</blockquote></td>
-<td><blockquote>
-<p>234'375'000</p>
-</blockquote></td>
-<td><blockquote>
-<p>1 : 378</p>
-</blockquote></td>
-</tr>
-</tbody>
-</table>
-
-**Notes**
-
-1.  The projection for the tiles is **LV95** (EPSG:2056). Other
-    projection are supported, see further down.
-2.  The tiles are generated on-the-fly and stored in a cache (hundreds
-    of requests per second)
-3.  The zoom level 24 (resolution 1.5m) has been generated, but is not
-    currently used in the API.
-4.  The zoom levels 27 and 28 (resolution 0.25m and 0.1m) are only
-    available for a few layers, e.g. swissimage or cadastral web map.
-    For the others layers it is only a client zoom (tiles are
-    stretched).
-5.  You **have** to use the <span
-    class="title-ref">\<ResourceURL\></span> to construct the <span
-    class="title-ref">GetTile</span> request.
-6.  **Axis order**: for historical reasons, EPSG:21781 WMTS tiles use
-    the non-standard **row/col** order, while all other projections use
-    the usual **col/row** order. However, most desktop GIS allow you to
-    either use the advertized order or to override it.
-7.  The tiles of a given layer might be updated **withtout** resulting
-    in a new \<Time\> dimension in the GetCapabilities dimension. In
-    case your application is caching tiles locally, you need to
-    invalidate your local cache for this layer. To check the latest
-    change of any layer, use the [Cache Update](#cache-update) service.
-
-### Result
-
-A tile.
-
-<http://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg>
-
-or
-<https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg>
-
-## Cache Update
-
-As noted in the `wmts_description` service, the Tiles of a given
-\<Time\> dimension might be updated for technical reasons. If you are
-caching Tiles locally, this might result in your cache being outdated.
-Use the Cache Update service to query the Date of the last update for a
-given layer. If your cache is older than the returned Date, you have to
-clear your local cache.
+WMTS requests can perform the following operations:
 
-### URL
+## GetCapabilities
 
-    GET https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/cacheUpdate
+The GetCapabilites document provides informations about the service, along with layer description, both in german and french.
 
-### Example
+<ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml?<Lang>" method="GET" />
 
-- The the latest Cache Update for SwissImage Product:
-  **https://api3.geo.admin.ch/rest/services/api/MapServer/ch.swisstopo.swissimage-product/cacheUpdate**
+| **Parameter**       | **Description**                                               |
+| ------------------- | ------------------------------------------------------------- |
+| **Lang (optional)** | The language. Supported values: `de`, `fr` (Defaults to `de`) |
 
-## Supported projections
+### Supported projections
 
 Four projections are supported. The same tiles are offered in four other
 _tilematrixsets/projection_.
@@ -551,89 +50,131 @@ Note:
   WMTS client may either stretch the tiles from the last available
   level or display nothing.
 
-## XYZ
-
-XYZ tile layers are layers comprised of multiple tiles. The XYZ tile
-service provides tiles based on a URL template with values substituted
-in for Zoom Level and X and Y counts of the tile. Unlike WMTS that
-follow the OGC standard, the XYZ tile service is often used in Web
-Mapping Context and is therefore a de facto standard. The XYZ tile
-service is provided with a fixed projection ( EPSG:3857).
+## GetTile
+
+<ApiCodeBlock url="http://wmts.geo.admin.ch/<Version>/<LayerBodId>/<StyleName>/<Time>/<TileMatrixSet>/<TileSetId>/<TileRow>/<TileCol>.<FormatExtension>" method="GET" />
+
+Use the following parameters to define your request:
+
+| **Parameter**             | **Example**                | **Description**                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Version                   | 1.0.0                      | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                     |
+| Layername                 | ch.bfs.arealstatistik-1997 | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
+| StyleName                 | default                    | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
+| Time                      | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
+| TileMatrixSet             | 2056 (constant)            | EPSG code for LV03/CH1903                                                                                                                                                                                                                                                                                                                                                 |
+| TileSetId TileRow TileCol | 22 236 284                 | Zoom level (see below)                                                                                                                                                                                                                                                                                                                                                    |
+| FormatExtension           | png                        | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
+
+With the `tileOrigin` in the top left corner of the bounding box:
+
+| **Resolution [m]** | **Zoom Level** | **Map zoom** | **Tile width [m]** | **Tiles X** | **Tiles Y** | **Tiles**   | **Approx. scale at 96 dpi per zoom level** |
+| ------------------ | -------------- | ------------ | ------------------ | ----------- | ----------- | ----------- | ------------------------------------------ |
+| 4000               | 0              | 1024000      | 1                  | 1           | 1           | 1           |                                            |
+| 3750               | 1              | 960000       | 1                  | 1           | 1           | 1           |                                            |
+| 3500               | 2              | 896000       | 1                  | 1           | 1           | 1           |                                            |
+| 3250               | 3              | 832000       | 1                  | 1           | 1           | 1           |                                            |
+| 3000               | 4              | 768000       | 1                  | 1           | 1           | 1           |                                            |
+| 2750               | 5              | 704000       | 1                  | 1           | 1           | 1           |                                            |
+| 2500               | 6              | 640000       | 1                  | 1           | 1           | 1           |                                            |
+| 2250               | 7              | 576000       | 1                  | 1           | 1           | 1           |                                            |
+| 2000               | 8              | 512000       | 1                  | 1           | 1           | 1           |                                            |
+| 1750               | 9              | 448000       | 2                  | 1           | 2           | 2           |                                            |
+| 1500               | 10             | 384000       | 2                  | 1           | 2           | 2           |                                            |
+| 1250               | 11             | 320000       | 2                  | 1           | 2           | 2           |                                            |
+| 1000               | 12             | 256000       | 2                  | 2           | 4           | 4           |                                            |
+| 750                | 13             | 192000       | 3                  | 2           | 6           | 6           |                                            |
+| 650                | 14             | 0            | 166400             | 3           | 2           | 6           | 1 : 2’456’694                              |
+| 500                | 15             | 1            | 128000             | 4           | 3           | 12          | 1 : 1’889’765                              |
+| 250                | 16             | 2            | 64000              | 8           | 5           | 40          | 1 : 944’882                                |
+| 100                | 17             | 3            | 25600              | 19          | 13          | 247         | 1 : 377’953                                |
+| 50                 | 18             | 4            | 12800              | 38          | 25          | 950         | 1 : 188’976                                |
+| 20                 | 19             | 5            | 5120               | 94          | 63          | 5’922       | 1 : 75’591                                 |
+| 10                 | 20             | 6            | 2560               | 188         | 125         | 23’500      | 1 : 37’795                                 |
+| 5                  | 21             | 7            | 1280               | 375         | 250         | 93’750      | 1 : 18’898                                 |
+| 2.5                | 22             | 8            | 640                | 750         | 500         | 375’000     | 1 : 9’449                                  |
+| 2                  | 23             | 9            | 512                | 938         | 625         | 586’250     | 1 : 7’559                                  |
+| 1.5                | 24             |              | 384                | 1250        | 834         | 1’042’500   |                                            |
+| 1                  | 25             | 10           | 256                | 1875        | 1250        | 2’343’750   | 1 : 3’780                                  |
+| 0.5                | 26             | 11           | 128                | 3750        | 2500        | 9’375’000   | 1 : 1’890                                  |
+| 0.25               | 27             | 12           | 64                 | 7500        | 5000        | 37’500’000  | 1 : 945                                    |
+| 0.1                | 28             | 13           | 25.6               | 18750       | 12500       | 234’375’000 | 1 : 378                                    |
 
-> [!TIP]
-> We encourage users to use WMTS layer service which provides predefined
-> tiles (like an XYZ service) with an option to use a RESTful templated
-> URL or a KVP request and with a variety of projections and grids.
-> Moreover, using WMTS GetCapabilities provides an up to date Metadata
-> Service for the available layers.
-
-### GetTile
-
-```bash
-GET <Scheme>://<ServerName>/<ProtocoleVersion>/<LayerName>/<Stylename>/<Time>/<TileMatrixSet>/{z}/{x}/{y}.<FormatExtension>
-```
-
-with the following parameters:
-
-| Parameter                 | Example                        | Explanation                                                                                                                                                                                                                                                                                                                                                               |
-| ------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scheme ServerName         | https wmts\[0-9\].geo.admin.ch | The scheme type                                                                                                                                                                                                                                                                                                                                                           |
-| Version                   | 1.0.0                          | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                     |
-| Layername                 | ch.bfs.arealstatistik-1997     | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
-| StyleName                 | default                        | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
-| Time                      | 2010, 2010-01                  | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
-| TileMatrixSet {z} {x} {y} | 3857 (constant) {z} {x} {y}    | EPSG code for Webmercator                                                                                                                                                                                                                                                                                                                                                 |
-| FormatExtension           | png                            | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
-
-::: warning
-
-The tiles of a given layer might be updated **without** resulting in
-a new \<Time\> dimension. In case your application is caching tiles
-locally, you need to invalidate your local cache for this layer. To
-check the latest change of any layer, use the [Cache
-Update](#cache-update) service.
+**Notes**
 
-:::
+1.  The projection for the tiles is **LV95** (EPSG:2056). Other
+    projection are supported, see further down.
+2.  The tiles are generated on-the-fly and stored in a cache (hundreds
+    of requests per second)
+3.  The zoom level 24 (resolution 1.5m) has been generated, but is not
+    currently used in the API.
+4.  The zoom levels 27 and 28 (resolution 0.25m and 0.1m) are only
+    available for a few layers, e.g. swissimage or cadastral web map.
+    For the others layers it is only a client zoom (tiles are
+    stretched).
+5.  You **have** to use the <span
+    class="title-ref">\<ResourceURL\></span> to construct the <span
+    class="title-ref">GetTile</span> request.
+6.  **Axis order**: for historical reasons, EPSG:21781 WMTS tiles use
+    the non-standard **row/col** order, while all other projections use
+    the usual **col/row** order. However, most desktop GIS allow you to
+    either use the advertized order or to override it.
+7.  The tiles of a given layer might be updated **withtout** resulting
+    in a new \<Time\> dimension in the GetCapabilities dimension. In
+    case your application is caching tiles locally, you need to
+    invalidate your local cache for this layer. To check the latest
+    change of any layer, use the [Cache Update](#cache-update) service.
 
-### Result
+## Cache Update
 
-Access to ch.swisstopo.swissimage.
+As noted in the introduction, the tiles of a given `<Time>` dimension might be updated for technical reasons.
+If you are caching tiles locally, this might result in your cache being outdated.
+Use the Cache Update service to query the date of the last update for a given layer.
+If your cache is older than the returned date, you have to clear your local cache.
 
-<https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.swissimage/default/current/3857/%7Bz%7D/%7Bx%7D/%7By%7D.jpeg>
+### URL
 
-### Supported projections
+<ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/<LayerBodId>/cacheUpdate" method="GET" />
 
-Unlike WMTS that follow the OGC standard, the XYZ tile service are often
-used in Web Mapping Context and therefore one projection is supported.
+## Examples
 
-- WGS84/Pseudo-Mercator (EPSG:3857, as used in OSM, Bing, Google Map)  
-  <https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.swissimage/default/current/>**3857**/{z}/{x}/{y}.jpeg
+The latest cache update for SwissImage Product:
 
-## Examples
+<ExampleCodeBlock
+request="curl https://api3.geo.admin.ch/rest/services/api/MapServer/ch.swisstopo.swissimage-product/cacheUpdate"
+example='{
+  "cache_type": "wmts_native",
+  "cache_update": "2025-06-12T08:44:38"
+}'
+/>
 
-## Fetch a single tile
+Fetch a single tile:
 
 ```bash
-curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg
+curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg
 display demo.jpg
 ```
 
-Will display the following image
+The request will display the following image:
+
+<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg" />
+
+## Examples: OpenLayers
 
-<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg" />
+An OpenLayers3 example showing the Cadastralwebmap as WMTS and Tiled WMS
 
-## Using WMTS in OpenLayers
+<iframe height="600" style="width: 100%;" scrolling="no" title="WMTS in (EPSG:21781) and WMS (EPSG:21781)" src="https://codepen.io/geoadmin/embed/xVKLdV?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/xVKLdV">
+  WMTS in (EPSG:21781) and WMS (EPSG:21781)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
 
-- An OpenLayers3 application using the [pseudo-Mercator
-  projection](http://codepen.io/geoadmin/pen/pyzwwL?editors=0010)
-- An OpenLayers3 example showing the [Cadastralwebmap as
-  WMTS](http://codepen.io/geoadmin/pen/xVKLdV?editors=0010)
-- Switzerland is now adopting the new [LV95
-  frame](http://codepen.io/geoadmin/pen/GZKEam?editors=0010).
-- All [available layers as
-  WMTS](http://codepen.io/geoadmin/pen/MyYYXR?editors=0010).
+<br/>
 
-### Example
+Using geo.admin.ch WMTS tiles in the new LV95 frame (EPSG:2056).
 
-- An OpenLayers example showing the [Swissimage as
-  XYZ](https://codepen.io/geoadmin/pen/xxYEwjQ)
+<iframe height="600" style="width: 100%;" scrolling="no" title="WMTS layer (EPSG:2056)" src="https://codepen.io/geoadmin/embed/GZKEam?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/GZKEam">
+  WMTS layer (EPSG:2056)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/xyz.md b/docs/xyz.md
new file mode 100644
index 0000000..b0fc611
--- /dev/null
+++ b/docs/xyz.md
@@ -0,0 +1,68 @@
+# XYZ
+
+The XYZ tile service provides tiles based on a URL template with values substituted in for zoom level and X and Y counts of the tile.
+Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context and is therefore a de facto standard.
+
+<ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/{LayerName}/{StyleName}/{Time}/3857/{z}/{x}/{y}.{FormatExtension}" method="GET" />
+
+:::tip
+We encourage users to use WMTS layer service which provides predefined tiles (like an XYZ service) with an option to use a RESTful templated URL or a KVP request and with a variety of projections and grids.
+Moreover, using WMTS GetCapabilities provides an up to date Metadata Service for the available layers.
+:::
+
+### Supported projections
+
+Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context (OSM, Bing, Google Map) and therefore only the WGS84/Pseudo-Mercator (EPSG:3857) is supported.
+
+## Request details
+
+with the following parameters:
+
+| Parameter                 | Example                     | Explanation                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Layername                 | ch.bfs.arealstatistik-1997  | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
+| StyleName                 | default                     | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
+| Time                      | 2010, 2010-01               | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
+| TileMatrixSet {z} {x} {y} | 3857 (constant) {z} {x} {y} | EPSG code for Webmercator                                                                                                                                                                                                                                                                                                                                                 |
+| FormatExtension           | png                         | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
+
+::: warning
+
+The tiles of a given layer might be updated **without** resulting in a new `<Time\>` dimension.
+In case your application is caching tiles locally, you need to invalidate your local cache for this layer.
+To check the latest change of any layer, use the [Cache Update](/docs/wmts#cache-update) service.
+
+:::
+
+## Examples
+
+Fetch a single tile:
+
+```bash
+curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg
+display demo.jpg
+```
+
+The request will display the following image:
+
+<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg" />
+
+## Examples: OpenLayers
+
+An OpenLayers3 application using the pseudo-Mercator projection:
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="WMTS layer (EPSG:3857)" src="https://codepen.io/geoadmin/embed/pyzwwL?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/pyzwwL">
+  WMTS layer (EPSG:3857)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+<br/>
+
+An OpenLayers example showing the Swissimage as XYZ:
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="xyz example" src="https://codepen.io/geoadmin/embed/xxYEwjQ?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/geoadmin/pen/xxYEwjQ">
+  xyz example</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>

From def8180b94dc0e67f48e57403761a29caef07123 Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Wed, 13 Aug 2025 16:24:13 +0200
Subject: [PATCH 2/6] fixes for PR review

---
 docs/3d-tiles.md            |  47 ++++++---------
 docs/mapbox-vector-tiles.md | 113 +++++++++++++++++-------------------
 docs/terrain-service.md     |  35 +++++------
 docs/wms.md                 | 106 ++++++++++++++++++---------------
 docs/wmts.md                |  93 ++++++++++++++---------------
 docs/xyz.md                 |  40 +++++++------
 6 files changed, 212 insertions(+), 222 deletions(-)

diff --git a/docs/3d-tiles.md b/docs/3d-tiles.md
index 4b48fee..723f176 100644
--- a/docs/3d-tiles.md
+++ b/docs/3d-tiles.md
@@ -1,33 +1,30 @@
 # 3D Tiles
 
-A RESTFul implementation of [Cesium 3D Tiles specification](https://github.com/CesiumGS/3d-tiles).
+This service provides 3D tiles through a RESTful API, implementing the [Cesium 3D Tiles specification](https://github.com/CesiumGS/3d-tiles).
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/<Z>/<X>/<Y>.b3dm" method="GET" />
 
-## Request Details
+Use the following parameters to define your request:
 
-### Path Parameters
+| Parameter | Example                          | Description                                                                                                                                                                             |
+| --------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| layerName | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer. Possible values are: `ch.swisstopo.swissbuildings3d.3d`, `ch.swisstopo.swisstlm3d.3d`, `ch.swisstopo.swissnames3d.3d`, `ch.swisstopo.vegetation.3d` |
+| Version   | v1                               | API version. `v1` means tiles generated with 3D Tiles                                                                                                                                   |
+| Time      | 20240501                         | Date of tileset generation in (ISO-8601, e.g. YYYYMMDD)                                                                                                                                 |
+| Z         | 7                                | Zoom level                                                                                                                                                                              |
+| X         | 54                               | Tile column index                                                                                                                                                                       |
+| Y         | 21                               | Tile row index                                                                                                                                                                          |
 
-| Parameter | Example                          | Description                                             |
-| --------- | -------------------------------- | ------------------------------------------------------- |
-| layerName | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer (see below)          |
-| Version   | v1                               | API version. `v1` means tiles generated with 3D Tiles   |
-| Time      | 20240501                         | Date of tileset generation in (ISO-8601, e.g. YYYYMMDD) |
-| Z         | 7                                | Zoom level                                              |
-| X         | 54                               | Tile column index                                       |
-| Y         | 21                               | Tile row index                                          |
+A 3D tile request for swissBUILDINGS3D dataset:
 
-**Available values for `<layerName>`:**
-
-- `ch.swisstopo.swissbuildings3d.3d`
-- `ch.swisstopo.swisstlm3d.3d`
-- `ch.swisstopo.swissnames3d.3d`
-- `ch.swisstopo.vegetation.3d`
+```http
+curl -o demo.b3dm https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm
+```
 
-### Metadata Service
+## Metadata
 
 The `tileset.json` file describes the available set of tiles.
-In order to use this service you can use [CesiumJS](https://github.com/CesiumGS/cesium).
+It can be used directly by [CesiumJS](https://github.com/CesiumGS/cesium).
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/tileset.json" method="GET" />
 
@@ -36,13 +33,7 @@ In order to use this service you can use [CesiumJS](https://github.com/CesiumGS/
 | Time (optional) | 20201203                         | Date of tile generation in (ISO-8601).         |
 | LayerName       | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer (see below) |
 
-## Examples
-
-A 3D tile
-
-```http
-https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm
-```
+A metadata request for the Vegetation dataset:
 
 <ExampleCodeBlock
 request="curl https://3d.geo.admin.ch/ch.swisstopo.vegetation.3d/v1/tileset.json"
@@ -71,9 +62,9 @@ example='{
 }'
 />
 
-## Examples: Cesium
+## Example: Cesium
 
-Example Geoadmin Terrain, Buildings and WMTS implementation using Cesium.
+An example Cesium application using terrain tiles, 3D buildings and WMTS.
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
diff --git a/docs/mapbox-vector-tiles.md b/docs/mapbox-vector-tiles.md
index 4642764..b923147 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/mapbox-vector-tiles.md
@@ -1,66 +1,22 @@
 # Mapbox Vector Tiles
 
-A RESTFul implementation of [Mapbox Vector Tiles](https://www.mapbox.com/vector-tiles).
+This service delivers vector map tiles and styles through a RESTful API, implementing the [Mapbox Vector Tiles specification](https://www.mapbox.com/vector-tiles).
 
-The service provides both tiles and styles with the following operations:
-
-::: tip Available datasets and styles as Mapbox Vector Tiles
-
-The list of current datasets and styles is available visiting the [official service description](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data).
+::: tip
+[The corresponding page on geo.admin.ch](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data) lists the available datasets and styles.
 :::
 
 ## GetStyle
 
-A current (latest version) style request is in the following form:
+To get the style of certain layer:
 
 <ApiCodeBlock url="https://vectortiles.geo.admin.ch/styles/{layerName}/style.json" method="GET" />
 
-| **Parameter**            | **Description**              |
-| ------------------------ | ---------------------------- |
-| **layerName (optional)** | Layer to perform the request |
-
-## GetTile
-
-A tile request is in the following form:
-
-<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{zoomLevel}/{x}/{y}.pbf" method="GET" />
+| **Parameter** | **Description**              |
+| ------------- | ---------------------------- |
+| layerName     | Layer to perform the request |
 
-| **Parameter** | **Example**          | **Description**                             |
-| ------------- | -------------------- | ------------------------------------------- |
-| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
-| version       | v1.0.0               | Version of the tileset                      |
-| zoomLevel     | 7                    | Zoom level (integer)                        |
-| x             | 67                   | Tile column (X coordinate in the tile grid) |
-| y             | 44                   | Tile row (Y coordinate in the tile grid)    |
-
-## GetTileSets
-
-MBTiles for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
-A MBtileSet request is in the following form:
-
-<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{layerName}.mbtiles" method="GET" />
-
-| **Parameter** | **Example**          | **Description**                             |
-| ------------- | -------------------- | ------------------------------------------- |
-| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
-| version       | v1.0.0               | Version of the tileset                      |
-
-## Metadata Service
-
-Each tileset has a corresponding metatdata json file that describes the available set of tiles.
-The URL of the metadata file is :
-
-<!-- GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json -->
-<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/tiles.json" method="GET" />
-
-| **Parameter** | **Example**          | **Description**                             |
-| ------------- | -------------------- | ------------------------------------------- |
-| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
-| version       | v1.0.0               | Version of the tileset                      |
-
-## Examples
-
-**GetStyle** example for light base map:
+A GetStyle request for the Light Base Map dataset:
 
 <ExampleCodeBlock
 request="curl https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/style.json"
@@ -90,23 +46,58 @@ example='{
 }'
 />
 
-**GetTile** request example for one `.pbf` tile in relief layer:
+## GetTile
+
+A tile request is in the following form:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{zoomLevel}/{x}/{y}.pbf" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+| zoomLevel     | 7                    | Zoom level (integer)                        |
+| x             | 67                   | Tile column (X coordinate in the tile grid) |
+| y             | 44                   | Tile row (Y coordinate in the tile grid)    |
+
+A GetTile request for one `.pbf` tile in the Relief dataset:
 
 ```http
-https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf
+curl -o demo.pbf https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf
 ```
 
-<br/>
+## GetTileSets
+
+MBTiles for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
+A MBtileSet request is in the following form:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{layerName}.mbtiles" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
 
-**GetTileSet** example for `.mbtiles` file in base layer:
+A GetTileSet request for `.mbtiles` file in the Base Map dataset:
 
 ```http
-https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
+curl -o demo.mbtiles https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
 ```
 
-<br/>
+## Metadata
+
+Each tileset has a corresponding metadata json file that describes the available set of tiles.
+The URL of the metadata file is:
+
+<!-- GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json -->
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/tiles.json" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
 
-**Metadata** example for base layer:
+A Metadata request for the Base Map dataset:
 
 <ExampleCodeBlock
 request="curl https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json"
@@ -137,9 +128,9 @@ example='{
 '
 />
 
-## Examples: MapLibre
+## Example: MapLibre
 
-Light Base Map example using MapLibre
+An example using MapLibre to display the Light Base Map:
 
 <iframe height="300" style="width: 100%;" scrolling="no" title="Maplibre Vector Tiles" src="https://codepen.io/geoadmin/embed/GvgLvj?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href="https://codepen.io/geoadmin/pen/GvgLvj">
diff --git a/docs/terrain-service.md b/docs/terrain-service.md
index 53446ec..48e39df 100644
--- a/docs/terrain-service.md
+++ b/docs/terrain-service.md
@@ -1,13 +1,11 @@
 # Terrain Service
 
-A RESTFul implementation of [Cesium Quantized Mesh](https://github.com/AnalyticalGraphicsInc/quantized-mesh) terrain service.
-Terrain tiles are served according to the [Tile Map Service (TMS)](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) layout and global-geodetic profile.
+This service delivers multi-resolution 3D terrain data as quantized mesh tiles, fully compliant with the [Cesium Quantized Mesh 1.0 specification](https://github.com/AnalyticalGraphicsInc/quantized-mesh).
+Tiles are organized and served following the [Tile Map Service (TMS) specification](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) using a global-geodetic profile (latitude/longitude coordinates),
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/<Version>/<Time>/<Zoom>/<X>/<Y>.terrain" method="GET" />
 
-## Request Details
-
-### Path Parameters
+Use the following parameters to define your request:
 
 | Parameter  | Example         | Description                                        |
 | ---------- | --------------- | -------------------------------------------------- |
@@ -15,12 +13,18 @@ Terrain tiles are served according to the [Tile Map Service (TMS)](http://wiki.o
 | Version    | v1              | v1 means terrain tiles generated with cesium tiles |
 | Time       | 20201203        | Date of tile generation in (ISO-8601).             |
 | Zoom       | 12              | Zoom level                                         |
-| X          | 4309            | The longitue index                                 |
+| X          | 4309            | The longitude index                                |
 | Y          | 3111            | The latitude index                                 |
 
-## Metadata Service
+An example of a terrain tile request:
+
+```http
+curl -o demo.terrain https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/7/136/98.terrain?v=3924.0.0
+```
+
+## Metadata
 
-The `layer.json` file determines which terrain tiles are available.
+The `layer.json` file provides metadata that describes the availability and structure of the terrain tiles at a given timestamp.
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/<Time>/layer.json" method="GET" />
 
@@ -28,17 +32,8 @@ The `layer.json` file determines which terrain tiles are available.
 | --------------- | -------- | -------------------------------------- |
 | Time (optional) | 20201203 | Date of tile generation in (ISO-8601). |
 
-## Examples
-
-A terrain tile:
-
-```http
-https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/7/136/98.terrain?v=3924.0.0
-```
-
-<br/>
+Example of a metadata request for the date `20201203`:
 
-Metadata for the date `20201203`:
 <ExampleCodeBlock
 request="curl https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/layer.json"
 example='{
@@ -56,9 +51,9 @@ example='{
 }'
 />
 
-## Examples: Cesium
+## Example: Cesium
 
-Example Geoadmin Terrain, Buildings and WMTS implementation using Cesium.
+An example Cesium application using terrain tiles, 3D buildings and WMTS.
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
diff --git a/docs/wms.md b/docs/wms.md
index 6347dfe..e7d7a4f 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -1,22 +1,25 @@
+---
+outline: [2, 3]
+---
+
 # Web Map Service (WMS)
 
 Federal offices make part of their data available via the WMS - Federal Spatial Data Infrastructure (FSDI) service.
-The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are also presented in map.geo.admin.ch.
-The WMS-FSDI can be used free of charge and provides access to public geodata.
+The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are presented in map.geo.admin.ch.
 
 WMS requests can perform the following operations:
 
 ## GetCapabilities
 
-The GetCapabilites document provides informations about the service, along with layer description, both in german and french.
+The GetCapabilities document provides information about the service, along with layer description, both in German and French.
 
 <ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities&LANG=<Lang>" method="GET" />
 
-| **Parameter**       | **Description**                                               |
-| ------------------- | ------------------------------------------------------------- |
-| **Lang (optional)** | The language. Supported values: `de`, `fr` (Defaults to `de`) |
+| **Parameter**   | **Description**                                               |
+| --------------- | ------------------------------------------------------------- |
+| Lang (optional) | The language. Supported values: `de`, `fr` (Defaults to `de`) |
 
-### Supported projections:
+### Supported Projections
 
 - EPSG:2056 CH1903+ / LV95 -- Swiss CH1903+ / LV95
 - EPSG:21781 CH1903 / LV03 -- Swiss CH1903 / LV03
@@ -39,15 +42,15 @@ The GetCapabilites document provides informations about the service, along with
 
 Use the following parameters to define your request:
 
-| **Parameter** | **Example**                     | **Description**                                                                     |
-| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
-| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                     |
-| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                            |
-| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
-| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
-| Width         | 800                             | Width of the output image in pixels.                                                |
-| Height        | 582                             | Height of the output image in pixels.                                               |
-| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                              |
+| **Parameter** | **Example**                     | **Description**                                                                                     |
+| ------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                                     |
+| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                                            |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see [Supported Projections](#supported-projections). |
+| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.                            |
+| Width         | 800                             | Width of the output image in pixels.                                                                |
+| Height        | 582                             | Height of the output image in pixels.                                                               |
+| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                                              |
 
 ## GetFeatureInfo
 
@@ -55,22 +58,22 @@ Use the following parameters to define your request:
 
 Use the following parameters to define your request:
 
-| **Parameter** | **Example**                     | **Description**                                                                     |
-| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
-| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                     |
-| QueryLayers   | ch.bafu.bundesinventare-bln     | Comma-separated list of layers to query for information.                            |
-| Styles        |                                 | Comma-separated list of styles. Use `default` or leave empty if unsure.             |
-| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
-| BBOX          | 2609000,1123050,2614050,1128100 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
-| Width         | 101                             | Width of the output image in pixels.                                                |
-| Height        | 101                             | Height of the output image in pixels.                                               |
-| I             | 50                              | X coordinate (pixel column) of the point to query, starting from 0 (left).          |
-| J             | 50                              | Y coordinate (pixel row) of the point to query, starting from 0 (top).              |
-| InfoFormat    | text/plain                      | Format of the returned feature info (e.g., `text/plain`, `application/json`).       |
-| FeatureCount  | 10                              | Maximum number of features to return.                                               |
-| Lang          | en                              | Language for the response. Supported values: `de`, `fr`, `it`, `en`.                |
-| Format        | image/png                       | Output image format (should match the map request).                                 |
-| Transparent   | true                            | Whether the background should be transparent (`true` or `false`).                   |
+| **Parameter** | **Example**                     | **Description**                                                                                     |
+| ------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names to display.                                                     |
+| QueryLayers   | ch.bafu.bundesinventare-bln     | Comma-separated list of layers to query for information.                                            |
+| Styles        |                                 | Comma-separated list of styles. Use `default` or leave empty if unsure.                             |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see [Supported Projections](#supported-projections). |
+| BBOX          | 2609000,1123050,2614050,1128100 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.                            |
+| Width         | 101                             | Width of the output image in pixels.                                                                |
+| Height        | 101                             | Height of the output image in pixels.                                                               |
+| I             | 50                              | X coordinate (pixel column) of the point to query, starting from 0 (left).                          |
+| J             | 50                              | Y coordinate (pixel row) of the point to query, starting from 0 (top).                              |
+| InfoFormat    | text/plain                      | Format of the returned feature info (e.g., `text/plain`, `application/json`).                       |
+| FeatureCount  | 10                              | Maximum number of features to return.                                                               |
+| Lang          | en                              | Language for the response. Supported values: `de`, `fr`, `it`, `en`.                                |
+| Format        | image/png                       | Output image format (should match the map request).                                                 |
+| Transparent   | true                            | Whether the background should be transparent (`true` or `false`).                                   |
 
 ## GetLegendGraphic
 
@@ -78,18 +81,18 @@ Use the following parameters to define your request:
 
 Use the following parameters to define your request:
 
-| **Parameter** | **Example**                     | **Description**                                                                     |
-| ------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
-| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names for which to request the legend.                |
-| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                            |
-| Lang          | en                              | Language for the legend. Supported values: `de`, `fr`, `it`, `en`.                  |
-| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see "Supported projections" section. |
-| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.            |
-| Width         | 800                             | Width of the output image in pixels.                                                |
-| Height        | 582                             | Height of the output image in pixels.                                               |
-| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                              |
+| **Parameter** | **Example**                     | **Description**                                                                                    |
+| ------------- | ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Layers        | ch.bafu.bundesinventare-bln     | Comma-separated list of layer names for which to request the legend.                               |
+| Styles        | default                         | Comma-separated list of styles. Use `default` if unsure.                                           |
+| Lang          | en                              | Language for the legend. Supported values: `de`, `fr`, `it`, `en`.                                 |
+| CRS           | EPSG:2056                       | Coordinate Reference System. Supported values: see [Supported Projections](#supported-projections) |
+| BBOX          | 2550000,1060000,2660000,1140000 | Bounding box of the map image (minX,minY,maxX,maxY) in the selected CRS.                           |
+| Width         | 800                             | Width of the output image in pixels.                                                               |
+| Height        | 582                             | Height of the output image in pixels.                                                              |
+| Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                                             |
 
-### Further information
+#### Further information
 
 - [General Terms of Use and Operating Conditions of the Federal Spatial Data Infrastructure FSDI](https://www.geo.admin.ch/en/geo-services/geo-services/terms-of-use.html)
 - [WMS-BGDI system status](http://status.geo.admin.ch/3380881)
@@ -102,14 +105,23 @@ Use the following parameters to define your request:
 
 ## Examples
 
-Example of GetMap request:
+Example of a GetMap request:
 
 ```bash
-curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+curl -o demo.jpg "https://wms.geo.admin.ch/?\
+  SERVICE=WMS&REQUEST=GetMap&\
+  VERSION=1.3.0&\
+  LAYERS=ch.bafu.bundesinventare-bln&\
+  STYLES=default&\
+  CRS=EPSG:2056&\
+  BBOX=2550000,1060000,2660000,1140000&\
+  WIDTH=800&\
+  HEIGHT=582&\
+  FORMAT=image/png"
 display demo.jpg
 ```
 
-The request will display the following image:
+The output image:
 
 <img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
 
@@ -136,6 +148,6 @@ curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&
 display demo.jpg
 ```
 
-The request will display the following image:
+The output image:
 
 <img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
diff --git a/docs/wmts.md b/docs/wmts.md
index da804d0..cec0e55 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -1,28 +1,30 @@
+---
+outline: [2, 3]
+---
+
 # Web Map Tile Service (WMTS)
 
-A RESTFul implementation of the [WMTS OGC Standard](http://www.opengeospatial.org/standards/wmts).
+A RESTful implementation of the [WMTS OGC Standard](http://www.opengeospatial.org/standards/wmts).
 
 :::warning
-Only the RESTFul request encoding to `GetTile` is implemented, not the `GetLegend` and `GetFeatureInfo`. No KVP and SOAP request
-encoding is supported.
+We only support the `GetCapabilities` and `GetTile` operation through a RESTful API endpoint. KVP and SOAP encodings are not not available.
 :::
 
 WMTS requests can perform the following operations:
 
 ## GetCapabilities
 
-The GetCapabilites document provides informations about the service, along with layer description, both in german and french.
+The GetCapabilities document provides information about the service, along with layer description, both in German and French.
 
-<ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml?<Lang>" method="GET" />
+<ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml?lang=<Lang>" method="GET" />
 
-| **Parameter**       | **Description**                                               |
-| ------------------- | ------------------------------------------------------------- |
-| **Lang (optional)** | The language. Supported values: `de`, `fr` (Defaults to `de`) |
+| **Parameter**   | **Description**                                               |
+| --------------- | ------------------------------------------------------------- |
+| Lang (optional) | The language. Supported values: `de`, `fr` (Defaults to `de`) |
 
-### Supported projections
+### Supported Projections
 
-Four projections are supported. The same tiles are offered in four other
-_tilematrixsets/projection_.
+Tiles are available in four supported projections:
 
 - LV95/CH1903+ (EPSG:2056)  
   <https://wmts.geo.admin.ch/EPSG/2056/1.0.0/WMTSCapabilities.xml>
@@ -36,17 +38,15 @@ _tilematrixsets/projection_.
 - WGS84/Pseudo-Mercator (EPSG:3857, as used in OSM, Bing, Google Map)  
   <https://wmts.geo.admin.ch/EPSG/3857/1.0.0/WMTSCapabilities.xml>
 
-Note:
+Notes:
 
-- Partly due to a limitation of the WTMS 1.0.0 recommendations, each
-  _projection_ has its own _GetCapabilities_ document.
-- The same <span class="title-ref">timestamps</span> are available in
-  all projection. New <span class="title-ref">timestamp</span> are
-  added to the former ones.
+- Partly due to a limitation of the WMTS 1.0.0 recommendations, each
+  _projection_ has its own `GetCapabilities` document.
+- The same timestamps are available in all projection. New timestamps are added to the former ones.
 - The layer _ch.kantone.cadastralwebmap-farbe_ uses a WMS service as
   its source.
-- Note that all layers are available at all scales. You have to check
-  for which **tileMatrixSets** a particuliar layer is defined. Your
+- All layers are available at all scales. You have to check
+  for which **tileMatrixSets** a particular layer is defined. Your
   WMTS client may either stretch the tiles from the last available
   level or display nothing.
 
@@ -56,15 +56,17 @@ Note:
 
 Use the following parameters to define your request:
 
-| **Parameter**             | **Example**                | **Description**                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Version                   | 1.0.0                      | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                     |
-| Layername                 | ch.bfs.arealstatistik-1997 | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
-| StyleName                 | default                    | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
-| Time                      | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
-| TileMatrixSet             | 2056 (constant)            | EPSG code for LV03/CH1903                                                                                                                                                                                                                                                                                                                                                 |
-| TileSetId TileRow TileCol | 22 236 284                 | Zoom level (see below)                                                                                                                                                                                                                                                                                                                                                    |
-| FormatExtension           | png                        | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
+| **Parameter**   | **Example**                | **Description**                                                                                                                                                                                                                                                                                                                                                        |
+| --------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Version         | 1.0.0                      | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                  |
+| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the WMTS GetCapabilities document.document.                                                                                                                                                                                                                                                   |
+| StyleName       | default                    | Only `default` is supported.                                                                                                                                                                                                                                                                                                                                           |
+| Time            | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like `current`. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the `<Dimension` tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
+| TileMatrixSet   | 2056 (constant)            | EPSG code for LV03/CH1903                                                                                                                                                                                                                                                                                                                                              |
+| TileSetId       | 22                         | Zoom level (see table below)                                                                                                                                                                                                                                                                                                                                           |
+| TileRow         | 236                        |                                                                                                                                                                                                                                                                                                                                                                        |
+| TileCol         | 284                        |                                                                                                                                                                                                                                                                                                                                                                        |
+| FormatExtension | png                        | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                   |
 
 With the `tileOrigin` in the top left corner of the bounding box:
 
@@ -100,45 +102,38 @@ With the `tileOrigin` in the top left corner of the bounding box:
 | 0.25               | 27             | 12           | 64                 | 7500        | 5000        | 37’500’000  | 1 : 945                                    |
 | 0.1                | 28             | 13           | 25.6               | 18750       | 12500       | 234’375’000 | 1 : 378                                    |
 
-**Notes**
+Notes:
 
 1.  The projection for the tiles is **LV95** (EPSG:2056). Other
     projection are supported, see further down.
-2.  The tiles are generated on-the-fly and stored in a cache (hundreds
-    of requests per second)
-3.  The zoom level 24 (resolution 1.5m) has been generated, but is not
-    currently used in the API.
+2.  The tiles are generated on-the-fly and stored in a cache.
+3.  Zoom level 24, with a resolution of 1.5m, is available in the tile pyramid but it is not currently made available through the API.
 4.  The zoom levels 27 and 28 (resolution 0.25m and 0.1m) are only
     available for a few layers, e.g. swissimage or cadastral web map.
-    For the others layers it is only a client zoom (tiles are
+    For the other layers it is only a client zoom (tiles are
     stretched).
-5.  You **have** to use the <span
-    class="title-ref">\<ResourceURL\></span> to construct the <span
-    class="title-ref">GetTile</span> request.
+5.  You **have** to use the `ResourceURL` to construct the `GetTile` request.
 6.  **Axis order**: for historical reasons, EPSG:21781 WMTS tiles use
     the non-standard **row/col** order, while all other projections use
     the usual **col/row** order. However, most desktop GIS allow you to
-    either use the advertized order or to override it.
-7.  The tiles of a given layer might be updated **withtout** resulting
-    in a new \<Time\> dimension in the GetCapabilities dimension. In
-    case your application is caching tiles locally, you need to
-    invalidate your local cache for this layer. To check the latest
-    change of any layer, use the [Cache Update](#cache-update) service.
+    either use the advertised order or to override it.
+7.  The tiles of a given layer might be updated **without** resulting
+    in a new \<Time\> dimension in the GetCapabilities dimension.
+    If your application caches tiles locally, you need to invalidate your local cache for this layer.
+    To check the latest change of any layer, use the [Cache Update](#cache-update) service.
 
 ## Cache Update
 
-As noted in the introduction, the tiles of a given `<Time>` dimension might be updated for technical reasons.
+As noted in the `GetTile` section, the tiles of a given `<Time>` dimension might be updated for technical reasons.
 If you are caching tiles locally, this might result in your cache being outdated.
 Use the Cache Update service to query the date of the last update for a given layer.
 If your cache is older than the returned date, you have to clear your local cache.
 
-### URL
-
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/<LayerBodId>/cacheUpdate" method="GET" />
 
 ## Examples
 
-The latest cache update for SwissImage Product:
+The latest cache update for the product SWISSIMAGE:
 
 <ExampleCodeBlock
 request="curl https://api3.geo.admin.ch/rest/services/api/MapServer/ch.swisstopo.swissimage-product/cacheUpdate"
@@ -155,11 +150,11 @@ curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/d
 display demo.jpg
 ```
 
-The request will display the following image:
+The output image:
 
 <img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg" />
 
-## Examples: OpenLayers
+### OpenLayers
 
 An OpenLayers3 example showing the Cadastralwebmap as WMTS and Tiled WMS
 
diff --git a/docs/xyz.md b/docs/xyz.md
index b0fc611..c37e924 100644
--- a/docs/xyz.md
+++ b/docs/xyz.md
@@ -1,35 +1,41 @@
+---
+outline: [2, 3]
+---
+
 # XYZ
 
-The XYZ tile service provides tiles based on a URL template with values substituted in for zoom level and X and Y counts of the tile.
-Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context and is therefore a de facto standard.
+The XYZ service provides map tiles based on specified (X, Y) coordinates and a chosen zoom level (Z).
 
 <ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/{LayerName}/{StyleName}/{Time}/3857/{z}/{x}/{y}.{FormatExtension}" method="GET" />
 
 :::tip
-We encourage users to use WMTS layer service which provides predefined tiles (like an XYZ service) with an option to use a RESTful templated URL or a KVP request and with a variety of projections and grids.
+Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context and is therefore a de facto standard.
+We encourage users to use WMTS layer service which provides predefined tiles (like an XYZ service) with an option to use a RESTful templated URL with a variety of projections and grids.
 Moreover, using WMTS GetCapabilities provides an up to date Metadata Service for the available layers.
 :::
 
 ### Supported projections
 
-Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context (OSM, Bing, Google Map) and therefore only the WGS84/Pseudo-Mercator (EPSG:3857) is supported.
+The XYZ service only offers the WGS84/Pseudo-Mercator projection (EPSG:3857). This is the most commonly used projection in web mapping applications like OSM, Bing or Google Maps.
 
 ## Request details
 
-with the following parameters:
+Use the following parameters to define your request:
 
-| Parameter                 | Example                     | Explanation                                                                                                                                                                                                                                                                                                                                                               |
-| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Layername                 | ch.bfs.arealstatistik-1997  | See the WMTS [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document.                                                                                                                                                                                                                                                                                  |
-| StyleName                 | default                     | Only **default** is supported.                                                                                                                                                                                                                                                                                                                                            |
-| Time                      | 2010, 2010-01               | Date of tile generation in (ISO-8601) or logical value like **current**. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
-| TileMatrixSet {z} {x} {y} | 3857 (constant) {z} {x} {y} | EPSG code for Webmercator                                                                                                                                                                                                                                                                                                                                                 |
-| FormatExtension           | png                         | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                      |
+| Parameter       | Example                    | Explanation                                                                                                                                                                                                                                                                                                                                                             |
+| --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the WMTS GetCapabilities document.document.                                                                                                                                                                                                                                                    |
+| StyleName       | default                    | Only `default` is supported.                                                                                                                                                                                                                                                                                                                                            |
+| Time            | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like `current`. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
+| z               | 10                         | Zoom level                                                                                                                                                                                                                                                                                                                                                              |
+| x               | 266                        | Tile column (X coordinate in the tile grid)                                                                                                                                                                                                                                                                                                                             |
+| y               | 180                        | Tile row (Y coordinate in the tile grid)                                                                                                                                                                                                                                                                                                                                |
+| FormatExtension | png                        | The image format of the returned tiles. Most layers are provided as "png", only a few exceptions like the raster layers `ch.swisstopo.pixelkarte-*` and `ch.swisstopo.swissimage*` use FormatExtension "jpeg". See the `<Format>` tag in the [GetCapabilites document of the WMTS](https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml).                               |
 
 ::: warning
 
 The tiles of a given layer might be updated **without** resulting in a new `<Time\>` dimension.
-In case your application is caching tiles locally, you need to invalidate your local cache for this layer.
+If your application caches tiles locally, you need to invalidate your local cache for this layer.
 To check the latest change of any layer, use the [Cache Update](/docs/wmts#cache-update) service.
 
 :::
@@ -43,13 +49,13 @@ curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/d
 display demo.jpg
 ```
 
-The request will display the following image:
+The output image:
 
 <img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg" />
 
-## Examples: OpenLayers
+### OpenLayers
 
-An OpenLayers3 application using the pseudo-Mercator projection:
+An OpenLayers 3 example demonstrating the CadastralWebMap using the WMTS and the Tiled WMS:
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="WMTS layer (EPSG:3857)" src="https://codepen.io/geoadmin/embed/pyzwwL?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href="https://codepen.io/geoadmin/pen/pyzwwL">
@@ -59,7 +65,7 @@ An OpenLayers3 application using the pseudo-Mercator projection:
 
 <br/>
 
-An OpenLayers example showing the Swissimage as XYZ:
+An OpenLayers example showing the SWISSIMAGE as XYZ:
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="xyz example" src="https://codepen.io/geoadmin/embed/xxYEwjQ?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
   See the Pen <a href="https://codepen.io/geoadmin/pen/xxYEwjQ">

From 55a9a9963e9bddd969aadac49cd5fcd181c92731 Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Wed, 13 Aug 2025 16:26:12 +0200
Subject: [PATCH 3/6] remove display command from curl examples

---
 docs/wms.md  | 2 --
 docs/wmts.md | 1 -
 docs/xyz.md  | 1 -
 3 files changed, 4 deletions(-)

diff --git a/docs/wms.md b/docs/wms.md
index e7d7a4f..aa04855 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -118,7 +118,6 @@ curl -o demo.jpg "https://wms.geo.admin.ch/?\
   WIDTH=800&\
   HEIGHT=582&\
   FORMAT=image/png"
-display demo.jpg
 ```
 
 The output image:
@@ -145,7 +144,6 @@ Example of a GetLegendGraphic request:
 
 ```bash
 curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
-display demo.jpg
 ```
 
 The output image:
diff --git a/docs/wmts.md b/docs/wmts.md
index cec0e55..a388af6 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -147,7 +147,6 @@ Fetch a single tile:
 
 ```bash
 curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg
-display demo.jpg
 ```
 
 The output image:
diff --git a/docs/xyz.md b/docs/xyz.md
index c37e924..b8a344f 100644
--- a/docs/xyz.md
+++ b/docs/xyz.md
@@ -46,7 +46,6 @@ Fetch a single tile:
 
 ```bash
 curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg
-display demo.jpg
 ```
 
 The output image:

From fe22ea0e335498c0a6148ce7379087437b1cb37f Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Thu, 14 Aug 2025 15:07:33 +0200
Subject: [PATCH 4/6] fix second round of review

---
 docs/3d-tiles.md            |  8 ++++----
 docs/mapbox-vector-tiles.md |  2 +-
 docs/terrain-service.md     |  8 ++++----
 docs/wms.md                 | 24 +++++++++++-------------
 docs/wmts.md                |  9 +++------
 docs/xyz.md                 |  8 +++-----
 6 files changed, 26 insertions(+), 33 deletions(-)

diff --git a/docs/3d-tiles.md b/docs/3d-tiles.md
index 723f176..d53453c 100644
--- a/docs/3d-tiles.md
+++ b/docs/3d-tiles.md
@@ -28,10 +28,10 @@ It can be used directly by [CesiumJS](https://github.com/CesiumGS/cesium).
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/tileset.json" method="GET" />
 
-| Parameter       | Example                          | Description                                    |
-| --------------- | -------------------------------- | ---------------------------------------------- |
-| Time (optional) | 20201203                         | Date of tile generation in (ISO-8601).         |
-| LayerName       | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer (see below) |
+| Parameter       | Example                          | Description                                                                                                                                                                             |
+| --------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Time (optional) | 20201203                         | Date of tile generation in (ISO-8601).                                                                                                                                                  |
+| layerName       | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer. Possible values are: `ch.swisstopo.swissbuildings3d.3d`, `ch.swisstopo.swisstlm3d.3d`, `ch.swisstopo.swissnames3d.3d`, `ch.swisstopo.vegetation.3d` |
 
 A metadata request for the Vegetation dataset:
 
diff --git a/docs/mapbox-vector-tiles.md b/docs/mapbox-vector-tiles.md
index b923147..36c2b6f 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/mapbox-vector-tiles.md
@@ -78,7 +78,7 @@ A MBtileSet request is in the following form:
 | layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
 | version       | v1.0.0               | Version of the tileset                      |
 
-A GetTileSet request for `.mbtiles` file in the Base Map dataset:
+A GetTileSet request for a `.mbtiles` file in the Base Map dataset:
 
 ```http
 curl -o demo.mbtiles https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
diff --git a/docs/terrain-service.md b/docs/terrain-service.md
index 48e39df..c9e6a93 100644
--- a/docs/terrain-service.md
+++ b/docs/terrain-service.md
@@ -28,14 +28,14 @@ The `layer.json` file provides metadata that describes the availability and stru
 
 <ApiCodeBlock url="https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/<Time>/layer.json" method="GET" />
 
-| Parameter       | Example  | Description                            |
-| --------------- | -------- | -------------------------------------- |
-| Time (optional) | 20201203 | Date of tile generation in (ISO-8601). |
+| Parameter       | Example  | Description                                                                                                               |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Time (optional) | 20201203 | Date of tile generation in (ISO-8601). If no date is provided, it returns the metadata for the most recent terrain tiles. |
 
 Example of a metadata request for the date `20201203`:
 
 <ExampleCodeBlock
-request="curl https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/layer.json"
+request="curl --compressed https://3d.geo.admin.ch/ch.swisstopo.terrain.3d/v1/20201203/layer.json"
 example='{
   "attribution": "Put something there",
   "available": [...],
diff --git a/docs/wms.md b/docs/wms.md
index aa04855..4a37969 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -7,8 +7,6 @@ outline: [2, 3]
 Federal offices make part of their data available via the WMS - Federal Spatial Data Infrastructure (FSDI) service.
 The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are presented in map.geo.admin.ch.
 
-WMS requests can perform the following operations:
-
 ## GetCapabilities
 
 The GetCapabilities document provides information about the service, along with layer description, both in German and French.
@@ -108,16 +106,16 @@ Use the following parameters to define your request:
 Example of a GetMap request:
 
 ```bash
-curl -o demo.jpg "https://wms.geo.admin.ch/?\
-  SERVICE=WMS&REQUEST=GetMap&\
-  VERSION=1.3.0&\
-  LAYERS=ch.bafu.bundesinventare-bln&\
-  STYLES=default&\
-  CRS=EPSG:2056&\
-  BBOX=2550000,1060000,2660000,1140000&\
-  WIDTH=800&\
-  HEIGHT=582&\
-  FORMAT=image/png"
+curl -o demo.png "https://wms.geo.admin.ch/?\
+SERVICE=WMS&REQUEST=GetMap&\
+VERSION=1.3.0&\
+LAYERS=ch.bafu.bundesinventare-bln&\
+STYLES=default&\
+CRS=EPSG:2056&\
+BBOX=2550000,1060000,2660000,1140000&\
+WIDTH=800&\
+HEIGHT=582&\
+FORMAT=image/png"
 ```
 
 The output image:
@@ -143,7 +141,7 @@ Layer 'ch.bafu.bundesinventare-bln'
 Example of a GetLegendGraphic request:
 
 ```bash
-curl -o demo.jpg https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+curl -o demo.png https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
 ```
 
 The output image:
diff --git a/docs/wmts.md b/docs/wmts.md
index a388af6..4a76470 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -10,8 +10,6 @@ A RESTful implementation of the [WMTS OGC Standard](http://www.opengeospatial.or
 We only support the `GetCapabilities` and `GetTile` operation through a RESTful API endpoint. KVP and SOAP encodings are not not available.
 :::
 
-WMTS requests can perform the following operations:
-
 ## GetCapabilities
 
 The GetCapabilities document provides information about the service, along with layer description, both in German and French.
@@ -40,9 +38,8 @@ Tiles are available in four supported projections:
 
 Notes:
 
-- Partly due to a limitation of the WMTS 1.0.0 recommendations, each
-  _projection_ has its own `GetCapabilities` document.
-- The same timestamps are available in all projection. New timestamps are added to the former ones.
+- Partly due to a limitation of the WMTS 1.0.0 recommendations, each _projection_ has its own `GetCapabilities` document.
+- The same timestamps are available in all projections. New timestamps are added to the former ones.
 - The layer _ch.kantone.cadastralwebmap-farbe_ uses a WMS service as
   its source.
 - All layers are available at all scales. You have to check
@@ -59,7 +56,7 @@ Use the following parameters to define your request:
 | **Parameter**   | **Example**                | **Description**                                                                                                                                                                                                                                                                                                                                                        |
 | --------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Version         | 1.0.0                      | WMTS protocol version                                                                                                                                                                                                                                                                                                                                                  |
-| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the WMTS GetCapabilities document.document.                                                                                                                                                                                                                                                   |
+| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the [WMTS GetCapabilities document](#getcapabilities).                                                                                                                                                                                                                                        |
 | StyleName       | default                    | Only `default` is supported.                                                                                                                                                                                                                                                                                                                                           |
 | Time            | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like `current`. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the `<Dimension` tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
 | TileMatrixSet   | 2056 (constant)            | EPSG code for LV03/CH1903                                                                                                                                                                                                                                                                                                                                              |
diff --git a/docs/xyz.md b/docs/xyz.md
index b8a344f..d96cc7c 100644
--- a/docs/xyz.md
+++ b/docs/xyz.md
@@ -9,9 +9,7 @@ The XYZ service provides map tiles based on specified (X, Y) coordinates and a c
 <ApiCodeBlock url="https://wmts.geo.admin.ch/1.0.0/{LayerName}/{StyleName}/{Time}/3857/{z}/{x}/{y}.{FormatExtension}" method="GET" />
 
 :::tip
-Unlike WMTS that follow the OGC standard, the XYZ tile service is often used in Web Mapping Context and is therefore a de facto standard.
-We encourage users to use WMTS layer service which provides predefined tiles (like an XYZ service) with an option to use a RESTful templated URL with a variety of projections and grids.
-Moreover, using WMTS GetCapabilities provides an up to date Metadata Service for the available layers.
+We recommend using the WMTS over the XYZ service. A WMTS provides predefined tiles like an XYZ service but a WMTS offers more functionality, like additional projections. While XYZ services are supported by most web mapping applications, WMTS is an official OGC standard.
 :::
 
 ### Supported projections
@@ -24,13 +22,13 @@ Use the following parameters to define your request:
 
 | Parameter       | Example                    | Explanation                                                                                                                                                                                                                                                                                                                                                             |
 | --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the WMTS GetCapabilities document.document.                                                                                                                                                                                                                                                    |
+| Layername       | ch.bfs.arealstatistik-1997 | The technical layer name. See the `<ows:Identifier>` tag of the layer in the [WMTS GetCapabilities document](/docs/wmts.md#getcapabilities).                                                                                                                                                                                                                            |
 | StyleName       | default                    | Only `default` is supported.                                                                                                                                                                                                                                                                                                                                            |
 | Time            | 2010, 2010-01              | Date of tile generation in (ISO-8601) or logical value like `current`. A list of available values is provided in the [GetCapabilities](//wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml) document under the \<Dimension\> tag. We recommend to use the value under the \<Default\> tag. Note that these values might change frequently - **check for updates regularly**. |
 | z               | 10                         | Zoom level                                                                                                                                                                                                                                                                                                                                                              |
 | x               | 266                        | Tile column (X coordinate in the tile grid)                                                                                                                                                                                                                                                                                                                             |
 | y               | 180                        | Tile row (Y coordinate in the tile grid)                                                                                                                                                                                                                                                                                                                                |
-| FormatExtension | png                        | The image format of the returned tiles. Most layers are provided as "png", only a few exceptions like the raster layers `ch.swisstopo.pixelkarte-*` and `ch.swisstopo.swissimage*` use FormatExtension "jpeg". See the `<Format>` tag in the [GetCapabilites document of the WMTS](https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml).                               |
+| FormatExtension | png                        | The image format of the returned tiles. Most layers are provided as "png", only a few exceptions like the raster layers `ch.swisstopo.pixelkarte-*` and `ch.swisstopo.swissimage*` use FormatExtension "jpeg". See the `<Format>` tag in the [GetCapabilities document of the WMTS](https://wmts.geo.admin.ch/1.0.0/WMTSCapabilities.xml).                              |
 
 ::: warning
 

From 10e799bed8fb91260cc5eb9cbddc0438a0d605d7 Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Thu, 14 Aug 2025 15:54:41 +0200
Subject: [PATCH 5/6] fix iframe error about a tag

---
 docs/3d-tiles.md            | 3 ---
 docs/mapbox-vector-tiles.md | 5 +----
 docs/terrain-service.md     | 3 ---
 docs/wmts.md                | 6 ------
 docs/xyz.md                 | 6 ------
 5 files changed, 1 insertion(+), 22 deletions(-)

diff --git a/docs/3d-tiles.md b/docs/3d-tiles.md
index d53453c..2baadce 100644
--- a/docs/3d-tiles.md
+++ b/docs/3d-tiles.md
@@ -67,7 +67,4 @@ example='{
 An example Cesium application using terrain tiles, 3D buildings and WMTS.
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
-  Geoadmin Terrain, Buildings and WMTS CesiumJS integration</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>
diff --git a/docs/mapbox-vector-tiles.md b/docs/mapbox-vector-tiles.md
index 36c2b6f..737ddc1 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/mapbox-vector-tiles.md
@@ -132,8 +132,5 @@ example='{
 
 An example using MapLibre to display the Light Base Map:
 
-<iframe height="300" style="width: 100%;" scrolling="no" title="Maplibre Vector Tiles" src="https://codepen.io/geoadmin/embed/GvgLvj?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/GvgLvj">
-  Maplibre Vector Tiles</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
+<iframe height="600" style="width: 100%;" scrolling="no" title="Maplibre Vector Tiles" src="https://codepen.io/geoadmin/embed/GvgLvj?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
 </iframe>
diff --git a/docs/terrain-service.md b/docs/terrain-service.md
index c9e6a93..a16455e 100644
--- a/docs/terrain-service.md
+++ b/docs/terrain-service.md
@@ -56,7 +56,4 @@ example='{
 An example Cesium application using terrain tiles, 3D buildings and WMTS.
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/zBEYGE">
-  Geoadmin Terrain, Buildings and WMTS CesiumJS integration</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>
diff --git a/docs/wmts.md b/docs/wmts.md
index 4a76470..6f0a4af 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -155,9 +155,6 @@ The output image:
 An OpenLayers3 example showing the Cadastralwebmap as WMTS and Tiled WMS
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="WMTS in (EPSG:21781) and WMS (EPSG:21781)" src="https://codepen.io/geoadmin/embed/xVKLdV?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/xVKLdV">
-  WMTS in (EPSG:21781) and WMS (EPSG:21781)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>
 
 <br/>
@@ -165,7 +162,4 @@ An OpenLayers3 example showing the Cadastralwebmap as WMTS and Tiled WMS
 Using geo.admin.ch WMTS tiles in the new LV95 frame (EPSG:2056).
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="WMTS layer (EPSG:2056)" src="https://codepen.io/geoadmin/embed/GZKEam?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/GZKEam">
-  WMTS layer (EPSG:2056)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>
diff --git a/docs/xyz.md b/docs/xyz.md
index d96cc7c..da9a2a7 100644
--- a/docs/xyz.md
+++ b/docs/xyz.md
@@ -55,9 +55,6 @@ The output image:
 An OpenLayers 3 example demonstrating the CadastralWebMap using the WMTS and the Tiled WMS:
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="WMTS layer (EPSG:3857)" src="https://codepen.io/geoadmin/embed/pyzwwL?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/pyzwwL">
-  WMTS layer (EPSG:3857)</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>
 
 <br/>
@@ -65,7 +62,4 @@ An OpenLayers 3 example demonstrating the CadastralWebMap using the WMTS and the
 An OpenLayers example showing the SWISSIMAGE as XYZ:
 
 <iframe height="600" style="width: 100%;" scrolling="no" title="xyz example" src="https://codepen.io/geoadmin/embed/xxYEwjQ?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
-  See the Pen <a href="https://codepen.io/geoadmin/pen/xxYEwjQ">
-  xyz example</a> by geoadmin (<a href="https://codepen.io/geoadmin">@geoadmin</a>)
-  on <a href="https://codepen.io">CodePen</a>.
 </iframe>

From 43b49156f7f84923eabc2f9e5cdec26aff29b9d6 Mon Sep 17 00:00:00 2001
From: Pedro Soares <pedro.soares@camptocamp.com>
Date: Thu, 21 Aug 2025 11:45:08 +0200
Subject: [PATCH 6/6] remaining pr review fixes

---
 .vitepress/config.mts                         |  4 +-
 ...mapbox-vector-tiles.md => vector-tiles.md} |  2 +-
 docs/wms.md                                   | 94 +++++++++----------
 docs/wmts.md                                  | 36 +++----
 docs/xyz.md                                   |  2 +-
 5 files changed, 68 insertions(+), 70 deletions(-)
 rename docs/{mapbox-vector-tiles.md => vector-tiles.md} (99%)

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 6e9184d..41e3a6f 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -149,8 +149,8 @@ function visualizeDataItems(): DefaultTheme.SidebarItem[] {
     { text: "WMTS", link: "/docs/wmts" },
     { text: "XYZ", link: "/docs/xyz" },
     {
-      text: "Mapbox Vector Tiles",
-      link: "/docs/mapbox-vector-tiles",
+      text: "Vector Tiles",
+      link: "/docs/vector-tiles",
     },
     {
       text: "Terrain Service",
diff --git a/docs/mapbox-vector-tiles.md b/docs/vector-tiles.md
similarity index 99%
rename from docs/mapbox-vector-tiles.md
rename to docs/vector-tiles.md
index 737ddc1..1c9c1d7 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/vector-tiles.md
@@ -1,4 +1,4 @@
-# Mapbox Vector Tiles
+# Vector Tiles
 
 This service delivers vector map tiles and styles through a RESTful API, implementing the [Mapbox Vector Tiles specification](https://www.mapbox.com/vector-tiles).
 
diff --git a/docs/wms.md b/docs/wms.md
index 4a37969..1a2b24a 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -5,7 +5,7 @@ outline: [2, 3]
 # Web Map Service (WMS)
 
 Federal offices make part of their data available via the WMS - Federal Spatial Data Infrastructure (FSDI) service.
-The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are presented in map.geo.admin.ch.
+The data layers currently available in the WMS-FSDI correspond, with a few exceptions, to the geodata that are presented in [map.geo.admin.ch](map.geo.admin.ch).
 
 ## GetCapabilities
 
@@ -50,6 +50,25 @@ Use the following parameters to define your request:
 | Height        | 582                             | Height of the output image in pixels.                                                               |
 | Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                                              |
 
+Example of a GetMap request:
+
+```bash
+curl -o demo.png "https://wms.geo.admin.ch/?\
+SERVICE=WMS&REQUEST=GetMap&\
+VERSION=1.3.0&\
+LAYERS=ch.bafu.bundesinventare-bln&\
+STYLES=default&\
+CRS=EPSG:2056&\
+BBOX=2550000,1060000,2660000,1140000&\
+WIDTH=800&\
+HEIGHT=582&\
+FORMAT=image/png"
+```
+
+The output image:
+
+<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
+
 ## GetFeatureInfo
 
 <ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&LAYERS=<Layers>&QUERY_LAYERS=<QueryLayers>&STYLES=<Styles>&CRS=<CRS>&BBOX=<BBOX>&WIDTH=<Width>&HEIGHT=<Height>&I=<I>&J=<J>&INFO_FORMAT=<InfoFormat>&FEATURE_COUNT=<FeatureCount>&LANG=<Lang>&FORMAT=<Format>&TRANSPARENT=<Transparent>" method="GET" />
@@ -73,6 +92,22 @@ Use the following parameters to define your request:
 | Format        | image/png                       | Output image format (should match the map request).                                                 |
 | Transparent   | true                            | Whether the background should be transparent (`true` or `false`).                                   |
 
+Example of a GetFeatureInfo request:
+
+<ExampleCodeBlock
+request="curl https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&FORMAT=image%2Fpng&TRANSPARENT=true&QUERY_LAYERS=ch.bafu.bundesinventare-bln&LAYERS=ch.bafu.bundesinventare-bln&FEATURE_COUNT=10&INFO_FORMAT=text%2Fplain&LANG=en&I=50&J=50&CRS=EPSG%3A2056&STYLES=&WIDTH=101&HEIGHT=101&BBOX=2609000%2C1123050%2C2614050%2C1128100"
+exampleLang="txt"
+example="GetFeatureInfo results:
+Layer 'ch.bafu.bundesinventare-bln'
+  Feature 1362: 
+    No. = '1716'
+    Name = 'Pfynwald – Illgraben'
+    Area_ha = '5064.29'
+    Objectsheet = 'https://data.geo.admin.ch/ch.bafu.bundesinventare-bln/objectsheets/2017revision/nr1716.pdf'
+    Subarea-No. = '0'
+    Subarea = ''"
+/>
+
 ## GetLegendGraphic
 
 <ApiCodeBlock url="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS={Layers}&STYLES={Styles}&LANG={Lang}&CRS={CRS}&BBOX={BBOX}&WIDTH={Width}&HEIGHT={Height}&FORMAT={Format}" method="GET" />
@@ -90,6 +125,16 @@ Use the following parameters to define your request:
 | Height        | 582                             | Height of the output image in pixels.                                                              |
 | Format        | image/png                       | Output image format (e.g., `image/png`, `image/jpeg`).                                             |
 
+Example of a GetLegendGraphic request:
+
+```bash
+curl -o demo.png https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
+```
+
+The output image:
+
+<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
+
 #### Further information
 
 - [General Terms of Use and Operating Conditions of the Federal Spatial Data Infrastructure FSDI](https://www.geo.admin.ch/en/geo-services/geo-services/terms-of-use.html)
@@ -100,50 +145,3 @@ Use the following parameters to define your request:
 - [MapInfo](http://www.twiav.nl/files/TWIAV_TIP_MI002.pdf)
 - [Quantum GIS](http://www.qgis.org/en/docs/index.html)
 - [Exemple 1 - Mappetizer](http://www.mappetizer.de/de/beispiele/wms_bafu_suisse/index.html)
-
-## Examples
-
-Example of a GetMap request:
-
-```bash
-curl -o demo.png "https://wms.geo.admin.ch/?\
-SERVICE=WMS&REQUEST=GetMap&\
-VERSION=1.3.0&\
-LAYERS=ch.bafu.bundesinventare-bln&\
-STYLES=default&\
-CRS=EPSG:2056&\
-BBOX=2550000,1060000,2660000,1140000&\
-WIDTH=800&\
-HEIGHT=582&\
-FORMAT=image/png"
-```
-
-The output image:
-
-<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
-
-Example of a GetFeatureInfo request:
-
-<ExampleCodeBlock
-request="curl https://wms.geo.admin.ch/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&FORMAT=image%2Fpng&TRANSPARENT=true&QUERY_LAYERS=ch.bafu.bundesinventare-bln&LAYERS=ch.bafu.bundesinventare-bln&FEATURE_COUNT=10&INFO_FORMAT=text%2Fplain&LANG=en&I=50&J=50&CRS=EPSG%3A2056&STYLES=&WIDTH=101&HEIGHT=101&BBOX=2609000%2C1123050%2C2614050%2C1128100"
-exampleLang="txt"
-example="GetFeatureInfo results:
-Layer 'ch.bafu.bundesinventare-bln'
-  Feature 1362: 
-    No. = '1716'
-    Name = 'Pfynwald – Illgraben'
-    Area_ha = '5064.29'
-    Objectsheet = 'https://data.geo.admin.ch/ch.bafu.bundesinventare-bln/objectsheets/2017revision/nr1716.pdf'
-    Subarea-No. = '0'
-    Subarea = ''"
-/>
-
-Example of a GetLegendGraphic request:
-
-```bash
-curl -o demo.png https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png
-```
-
-The output image:
-
-<img src="https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetLegendGraphic&VERSION=1.3.0&LAYERS=ch.bafu.bundesinventare-bln&STYLES=default&LANG=en&CRS=EPSG:2056&BBOX=2550000,1060000,2660000,1140000&WIDTH=800&HEIGHT=582&FORMAT=image/png" />
diff --git a/docs/wmts.md b/docs/wmts.md
index 6f0a4af..755e1df 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -63,7 +63,7 @@ Use the following parameters to define your request:
 | TileSetId       | 22                         | Zoom level (see table below)                                                                                                                                                                                                                                                                                                                                           |
 | TileRow         | 236                        |                                                                                                                                                                                                                                                                                                                                                                        |
 | TileCol         | 284                        |                                                                                                                                                                                                                                                                                                                                                                        |
-| FormatExtension | png                        | Mostly png, except for some raster layer (pixelkarte and swissimage)                                                                                                                                                                                                                                                                                                   |
+| FormatExtension | png                        | Mostly png, except for some raster layer (pixelkarte and SWISSIMAGE)                                                                                                                                                                                                                                                                                                   |
 
 With the `tileOrigin` in the top left corner of the bounding box:
 
@@ -99,14 +99,14 @@ With the `tileOrigin` in the top left corner of the bounding box:
 | 0.25               | 27             | 12           | 64                 | 7500        | 5000        | 37’500’000  | 1 : 945                                    |
 | 0.1                | 28             | 13           | 25.6               | 18750       | 12500       | 234’375’000 | 1 : 378                                    |
 
+<small>
 Notes:
 
-1.  The projection for the tiles is **LV95** (EPSG:2056). Other
-    projection are supported, see further down.
+1.  The projection for the tiles is **LV95** (EPSG:2056). Other projection are available, see [Supported Projections](/docs/wmts.html#supported-projections).
 2.  The tiles are generated on-the-fly and stored in a cache.
 3.  Zoom level 24, with a resolution of 1.5m, is available in the tile pyramid but it is not currently made available through the API.
 4.  The zoom levels 27 and 28 (resolution 0.25m and 0.1m) are only
-    available for a few layers, e.g. swissimage or cadastral web map.
+    available for a few layers, e.g. SWISSIMAGE or cadastral web map.
     For the other layers it is only a client zoom (tiles are
     stretched).
 5.  You **have** to use the `ResourceURL` to construct the `GetTile` request.
@@ -115,10 +115,22 @@ Notes:
     the usual **col/row** order. However, most desktop GIS allow you to
     either use the advertised order or to override it.
 7.  The tiles of a given layer might be updated **without** resulting
-    in a new \<Time\> dimension in the GetCapabilities dimension.
+    in a new `<Time>` dimension in the GetCapabilities dimension.
     If your application caches tiles locally, you need to invalidate your local cache for this layer.
     To check the latest change of any layer, use the [Cache Update](#cache-update) service.
 
+</small>
+
+Example of a GetTile request:
+
+```bash
+curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg
+```
+
+The output image:
+
+<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg" />
+
 ## Cache Update
 
 As noted in the `GetTile` section, the tiles of a given `<Time>` dimension might be updated for technical reasons.
@@ -128,8 +140,6 @@ If your cache is older than the returned date, you have to clear your local cach
 
 <ApiCodeBlock url="https://api3.geo.admin.ch/rest/services/api/MapServer/<LayerBodId>/cacheUpdate" method="GET" />
 
-## Examples
-
 The latest cache update for the product SWISSIMAGE:
 
 <ExampleCodeBlock
@@ -140,17 +150,7 @@ example='{
 }'
 />
 
-Fetch a single tile:
-
-```bash
-curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg
-```
-
-The output image:
-
-<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg" />
-
-### OpenLayers
+## Examples: OpenLayers
 
 An OpenLayers3 example showing the Cadastralwebmap as WMTS and Tiled WMS
 
diff --git a/docs/xyz.md b/docs/xyz.md
index da9a2a7..b2e4f4f 100644
--- a/docs/xyz.md
+++ b/docs/xyz.md
@@ -32,7 +32,7 @@ Use the following parameters to define your request:
 
 ::: warning
 
-The tiles of a given layer might be updated **without** resulting in a new `<Time\>` dimension.
+The tiles of a given layer might be updated **without** resulting in a new `<Time>` dimension.
 If your application caches tiles locally, you need to invalidate your local cache for this layer.
 To check the latest change of any layer, use the [Cache Update](/docs/wmts#cache-update) service.