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..2baadce
--- /dev/null
+++ b/docs/3d-tiles.md
@@ -0,0 +1,70 @@
+# 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" />
+
+Use the following parameters to define your request:
+
+| 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                                                                                                                                                                          |
+
+A 3D tile request for swissBUILDINGS3D dataset:
+
+```http
+curl -o demo.b3dm https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm
+```
+
+## Metadata
+
+The `tileset.json` file describes the available set of tiles.
+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. 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:
+
+<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": [...]
+  }
+}'
+/>
+
+## Example: 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">
+</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..737ddc1 100644
--- a/docs/mapbox-vector-tiles.md
+++ b/docs/mapbox-vector-tiles.md
@@ -1,65 +1,136 @@
 # 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)
-
-The service provides both _tiles_ and _styles_ that the customer can
-use.
-
-### GetStyle
-
-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
+This service delivers vector map tiles and styles through a RESTful API, implementing the [Mapbox Vector Tiles specification](https://www.mapbox.com/vector-tiles).
+
+::: 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
+
+To get the style of certain layer:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/styles/{layerName}/style.json" method="GET" />
+
+| **Parameter** | **Description**              |
+| ------------- | ---------------------------- |
+| layerName     | Layer to perform the request |
+
+A GetStyle request for the Light Base Map dataset:
+
+<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
 
 A tile request is in the following form:
 
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>/<zoomlevel>/<x>/<y>.pbf
-
-example of one pbf tile:
-
-- <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>
-
-### 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)
-
-### Metadata Service
-
-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 :
-
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json
-
-example of tileset:
-
-- <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)    |
+
+A GetTile request for one `.pbf` tile in the Relief dataset:
+
+```http
+curl -o demo.pbf https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf
+```
+
+## 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                      |
+
+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
+```
+
+## 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                      |
+
+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"
+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"
+  ]
+}
+'
+/>
+
+## Example: MapLibre
+
+An example using MapLibre to display the Light Base Map:
+
+<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
new file mode 100644
index 0000000..a16455e
--- /dev/null
+++ b/docs/terrain-service.md
@@ -0,0 +1,59 @@
+# Terrain Service
+
+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" />
+
+Use the following parameters to define your request:
+
+| 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 longitude index                                |
+| Y          | 3111            | The latitude index                                 |
+
+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 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" />
+
+| 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 --compressed 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"
+}'
+/>
+
+## Example: 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">
+</iframe>
diff --git a/docs/wms.md b/docs/wms.md
index 96489a0..4a37969 100644
--- a/docs/wms.md
+++ b/docs/wms.md
@@ -1,27 +1,23 @@
-# Web Mapping Services WMS: Available services an data
+---
+outline: [2, 3]
+---
 
-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.
+# Web Map Service (WMS)
 
-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).
+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 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 GetCapabilities document provides information 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:
+### Supported Projections
 
 - EPSG:2056 CH1903+ / LV95 -- Swiss CH1903+ / LV95
 - EPSG:21781 CH1903 / LV03 -- Swiss CH1903 / LV03
@@ -38,11 +34,63 @@ 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](#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
+
+<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](#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
+
+<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](#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)
@@ -52,3 +100,50 @@ 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 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 c5c3c44..6f0a4af 100644
--- a/docs/wmts.md
+++ b/docs/wmts.md
@@ -1,529 +1,28 @@
-# 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)
-
-<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
-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**
+---
+outline: [2, 3]
+---
 
-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.
+# Web Map Tile Service (WMTS)
 
-<http://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg>
+A RESTful implementation of the [WMTS OGC Standard](http://www.opengeospatial.org/standards/wmts).
 
-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.
+:::warning
+We only support the `GetCapabilities` and `GetTile` operation through a RESTful API endpoint. KVP and SOAP encodings are not not available.
+:::
 
-### URL
+## GetCapabilities
 
-    GET https://api3.geo.admin.ch/rest/services/api/MapServer/{layerBodId}/cacheUpdate
+The GetCapabilities document provides information 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=<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_.
+Tiles are available in four supported projections:
 
 - LV95/CH1903+ (EPSG:2056)  
   <https://wmts.geo.admin.ch/EPSG/2056/1.0.0/WMTSCapabilities.xml>
@@ -537,103 +36,130 @@ _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 projections. 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.
 
-## 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).
-
-> [!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.
-
-:::
+## 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 | 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                                                                                                                                                                                                                                                                                                                                              |
+| 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:
+
+| **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                                    |
+
+Notes:
 
-### Result
+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.
+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 other layers it is only a client zoom (tiles are
+    stretched).
+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 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.
 
-Access to ch.swisstopo.swissimage.
+## Cache Update
 
-<https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.swissimage/default/current/3857/%7Bz%7D/%7Bx%7D/%7By%7D.jpeg>
+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.
 
-### 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 the product SWISSIMAGE:
 
-## 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
-display demo.jpg
+curl -o demo.jpg https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/21781/20/58/70.jpeg
 ```
 
-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" />
+
+### 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">
+</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">
+</iframe>
diff --git a/docs/xyz.md b/docs/xyz.md
new file mode 100644
index 0000000..da9a2a7
--- /dev/null
+++ b/docs/xyz.md
@@ -0,0 +1,65 @@
+---
+outline: [2, 3]
+---
+
+# XYZ
+
+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 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
+
+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
+
+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](/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 [GetCapabilities 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.
+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.
+
+:::
+
+## 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
+```
+
+The output image:
+
+<img src="https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/3857/9/266/180.jpeg" />
+
+### OpenLayers
+
+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">
+</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">
+</iframe>