Repository: maplibre/martin
Pull request #1796: docs: restructure docs sidebar
Author: login: CommanderStorm
Created: 2025-04-16T18:28:39Z | Merged: 2025-04-24T11:01:57Z

This PR might be controversial, depending how you two like the current docs layout.

So I noticed that the current docs are likely a bit overwhealmign for users and could be more tidy.


<details><summary>This PR tries to clean up things into new drawers where appropriate (click to expand)</summary>
<p>

![image](https://github.com/user-attachments/assets/1e6e50a1-62af-4ebb-be46-ea3a40b197ac)
![image](https://github.com/user-attachments/assets/486a324a-4d1e-4f89-ad79-5377f8235ac8)


</p>
</details> 

Because this adds more categories, this also adds a bit of extra fluff.
Example:
- one section where I discuss the pros/cons of mbtiles/pmtiles/postgres => https://github.com/CommanderStorm/martin/blob/1742d0899f54ab373e16f8353abdb99c7966f416/docs/src/config/tiles/tiles.md
- one section where I discuss why one would use a reverse-proxy => https://github.com/CommanderStorm/martin/blob/1742d0899f54ab373e16f8353abdb99c7966f416/docs/src/run/reverse-proxy/reverse-proxy.md


Diff:
diff --git a/.github/files/config.markdownlint-cli2.jsonc b/.github/files/config.markdownlint-cli2.jsonc
index f1f24a814..49442efcd 100644
--- a/.github/files/config.markdownlint-cli2.jsonc
+++ b/.github/files/config.markdownlint-cli2.jsonc
@@ -2,12 +2,12 @@
   "config": {
     "default": true,
     "relative-links": true,
+    "MD001": false,
     // Line length Check. See https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md013.md
     "MD013": false,
-    "MD041": false,
     "MD033": false,
+    "MD041": false,
     "MD045": false,
-    "MD001": false
   },
   // globs expression. See https://github.com/DavidAnson/markdownlint-cli2#command-line
   "globs": [
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 3fbe0b10a..23fac3cb1 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -8,36 +8,45 @@
 - [Installation](installation.md)
 - [Running](run.md)
   - [Command Line Interface](run-with-cli.md)
-    - [Environment Variables](env-vars.md)
-  - [Running with Docker](run-with-docker.md)
-  - [Running with Docker Compose](run-with-docker-compose.md)
-  - [Running with NGINX](run-with-nginx.md)
-  - [Running with Apache](run-with-apache.md)
-  - [Running in AWS Lambda](run-with-lambda.md)
+  - [Environment Variables](env-vars.md)
+  - [Hosting Environment–specific Guides](run-hosting-environment.md)
+    - [Docker](run-with-docker.md)
+    - [Docker Compose](run-with-docker-compose.md)
+    - [AWS Lambda](run-with-lambda.md)
+  - [Reverse Proxies](run-with-reverse-proxy.md)
+    - [NGINX](run-with-nginx.md)
+    - [Apache](run-with-apache.md)
   - [Troubleshooting](troubleshooting.md)
 - [Configuration File](config-file.md)
-  - [PostgreSQL Connections](pg-connections.md)
-  - [PostgreSQL Table Sources](sources-pg-tables.md)
-  - [PostgreSQL Function Sources](sources-pg-functions.md)
-  - [MBTiles and PMTiles File Sources](sources-files.md)
-  - [Composite Sources](sources-composite.md)
-  - [Sprite Sources](sources-sprites.md)
-  - [Style Sources](sources-styles.md)
-  - [Font Sources](sources-fonts.md)
-- [Usage and Endpoint API](using.md)
-  - [Using with MapLibre](using-with-maplibre.md)
-  - [Using with Leaflet](using-with-leaflet.md)
-  - [Using with deck.gl](using-with-deck-gl.md)
-  - [Using with Mapbox](using-with-mapbox.md)
-  - [Using with OpenLayers](using-with-openlayers.md)
-  - [Recipes](recipes.md)
-- [Tools](tools.md)
-  - [martin-cp bulk tile generation](martin-cp.md)
-  - [MBTiles Metadata](mbtiles-meta.md)
-  - [MBTiles Schemas](mbtiles-schema.md)
-  - [Copying MBTiles](mbtiles-copy.md)
-  - [Diffing/Patching MBTiles](mbtiles-diff.md)
-  - [Validating MBTiles](mbtiles-validation.md)
+  - [Tile sources](sources-tiles.md)
+    - [MBTiles and PMTiles File Sources](sources-files.md)
+    - [PostgreSQL Connections](pg-connections.md)
+      - [PostgreSQL Table Sources](sources-pg-tables.md)
+      - [PostgreSQL Function Sources](sources-pg-functions.md)
+    - [Composite Sources](sources-composite.md)
+  - [Supporting Resources](sources-resources.md)
+    - [Sprites](sources-sprites.md)
+    - [Styles](sources-styles.md)
+    - [Fonts](sources-fonts.md)
+- [Avaliable API Endpoints](using.md)
+- [Guides](using-guides.md)
+  - [Map renderer specific](using-with-renderer.md)
+    - [MapLibre](using-with-maplibre.md)
+    - [Leaflet](using-with-leaflet.md)
+    - [deck.gl](using-with-deck-gl.md)
+    - [Mapbox](using-with-mapbox.md)
+    - [OpenLayers](using-with-openlayers.md)
+  - [Data source specific](using-with-data.md)
+    - [Using Hosted PostgreSQL](recipes.md)
+    - [Setting up a basemap and overlaying data]() <!-- markdownlint-disable-line MD042 -->
+  - [Bulk Tile Generation](martin-cp.md)
+  - [Working with MBTiles archives](mbtiles.md)
+    - [MBTiles Schemas](mbtiles-schema.md)
+    - [Accessing Metadata](mbtiles-meta.md)
+    - [Copying MBTiles](mbtiles-copy.md)
+    - [Diffing/Patching MBTiles](mbtiles-diff.md)
+    - [Validating MBTiles](mbtiles-validation.md)
 - [Development](development.md)
   - [Getting involved](getting-involved.md)
+  - [Provided Tools](tools.md)
   - [Martin as a library](martin-as-a-library.md)
diff --git a/docs/src/env-vars.md b/docs/src/env-vars.md
index 0bb98a9e9..49178cd8d 100644
--- a/docs/src/env-vars.md
+++ b/docs/src/env-vars.md
@@ -2,11 +2,11 @@
 
 You can also configure Martin using environment variables, but only if the configuration file is not used. See [configuration section](config-file.md) on how to use environment variables with config files. See also [SSL configuration](pg-connections.md#postgresql-ssl-connections) section below.
 
-| Environment var <br/> Config File key    | Example                              | Description                                                                                                                                                                                                |
-|------------------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `DATABASE_URL` <br/> `connection_string` | `postgresql://postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
-| `DEFAULT_SRID` <br/> `default_srid`      | `4326`                               | If a PostgreSQL table has a geometry column with SRID=0, use this value instead                                                                                                                            |
-| `PGSSLCERT` <br/> `ssl_cert`             | `./postgresql.crt`                   | A file with a client SSL certificate. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLCERT)                                                                             |
-| `PGSSLKEY` <br/> `ssl_key`               | `./postgresql.key`                   | A file with the key for the client SSL certificate. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLKEY)                                                                |
-| `PGSSLROOTCERT` <br/> `ssl_root_cert`    | `./root.crt`                         | A file with trusted root certificate(s). The file should contain a sequence of PEM-formatted CA certificates. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLROOTCERT) |
-| `AWS_LAMBDA_RUNTIME_API`                 |                                      | If defined, connect to AWS Lambda to handle requests. The regular HTTP server is not used. See [Running in AWS Lambda](run-with-lambda.md)                                                                 |
+| Environment var <br/> Config File key    | Example                                     | Description                                                                                                                                                                                                |
+|------------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `DATABASE_URL` <br/> `connection_string` | `postgresql://`<br/>`postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
+| `DEFAULT_SRID` <br/> `default_srid`      | `4326`                                      | If a PostgreSQL table has a geometry column with SRID=0, use this value instead                                                                                                                            |
+| `PGSSLCERT` <br/> `ssl_cert`             | `./postgresql.crt`                          | A file with a client SSL certificate. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLCERT)                                                                             |
+| `PGSSLKEY` <br/> `ssl_key`               | `./postgresql.key`                          | A file with the key for the client SSL certificate. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLKEY)                                                                |
+| `PGSSLROOTCERT` <br/> `ssl_root_cert`    | `./root.crt`                                | A file with trusted root certificate(s). The file should contain a sequence of PEM-formatted CA certificates. [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLROOTCERT) |
+| `AWS_LAMBDA_RUNTIME_API`                 |                                             | If defined, connect to AWS Lambda to handle requests. The regular HTTP server is not used. See [Running in AWS Lambda](run-with-lambda.md)                                                                 |
diff --git a/docs/src/getting-involved.md b/docs/src/getting-involved.md
index acd31d06a..8c4905ff3 100644
--- a/docs/src/getting-involved.md
+++ b/docs/src/getting-involved.md
@@ -84,7 +84,7 @@ Go to any part you're interested in of martin code and add a breakpoint.
 
 We add a breakpoint here in the [start of martin](https://github.com/maplibre/martin/blob/e628c3973f193a432d3d1282c5893e2339e806b6/martin/src/bin/martin.rs#L10).
 
-```rust
+```rust, ignore
 use clap::Parser;
 use log::{error, info, log_enabled};
 use martin::args::{Args, OsEnv};
diff --git a/docs/src/martin-cp.md b/docs/src/martin-cp.md
index 32844952d..e69976709 100644
--- a/docs/src/martin-cp.md
+++ b/docs/src/martin-cp.md
@@ -1,18 +1,17 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
-(bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. `martin-cp` supports the
-same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file.
+
+`martin-cp` can be used to generate tiles for a large area or multiple areas (bounding boxes).
+If multiple areas overlap, it will ensure each tile is generated only once
+`martin-cp` supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
 
 After copying, `martin-cp` will update the `agg_tiles_hash` metadata value unless `--skip-agg-tiles-hash` is specified.
-This allows the MBTiles file to be [validated](./mbtiles-validation.md#aggregate-content-validation)
-using `mbtiles validate` command.
+This allows the MBTiles file to be [validated](mbtiles-validation.md#aggregate-content-validation) using `mbtiles validate` command.
 
 ## Usage
 
-This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles`
-using [normalized](mbtiles-schema.md) schema, with zoom levels from 0 to 10, and bounds of the whole world.
+This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles` using [normalized](mbtiles-schema.md#normalized) schema, with zoom levels from 0 to 10, and bounds of the whole world.
 
 ```bash
 martin-cp  --output-file tileset.mbtiles \
diff --git a/docs/src/mbtiles.md b/docs/src/mbtiles.md
new file mode 100644
index 000000000..06ff96d41
--- /dev/null
+++ b/docs/src/mbtiles.md
@@ -0,0 +1,8 @@
+# Working with MBTiles archives
+
+Martin includes `mbtiles` utility to interact with the [`*.mbtiles` files](mbtiles-schema.md) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
+
+Use `mbtiles --help` to see a list of available commands, and `mbtiles <command> --help` to see help for a specific command.
+
+This tool can be installed by compiling the latest released version with `cargo install mbtiles --locked`, or by downloading a pre-built binary from the [releases page](https://github.com/maplibre/martin/releases/latest).
diff --git a/docs/src/recipes.md b/docs/src/recipes.md
index 423c64b08..8c2e49f84 100644
--- a/docs/src/recipes.md
+++ b/docs/src/recipes.md
@@ -1,30 +1,29 @@
-## Recipes
+# Hosted PostgreSQL
 
-### Using with DigitalOcean PostgreSQL
+Some providers of PostgreSQL databases require additional configuration to work with Martin.
+We try to provide a guide for each provider, but we may not cover all of them.
 
-You can use Martin
-with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with
-PostGIS extension
+## Using with DigitalOcean PostgreSQL
 
-First, you need to download the CA certificate and get your cluster connection string from
-the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA
-certificate to connect to the database
+You can use Martin with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with PostGIS extension
+
+First, you need to download the CA certificate and get your cluster connection string from the [dashboard](https://cloud.digitalocean.com/databases).
+After that, you can use the connection string and the CA certificate to connect to the database
 
 ```bash
 martin --ca-root-file ./ca-certificate.crt \
        postgresql://user:password@host:port/db?sslmode=require
 ```
 
-### Using with Heroku PostgreSQL
+## Using with Heroku PostgreSQL
 
-You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with PostGIS extension
+You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with the PostGIS extension
 
 ```bash
 heroku pg:psql -a APP_NAME -c 'create extension postgis'
 ```
 
-Use the same environment variables as
-Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables).
+Use the same environment variables as Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables).
 
 ```bash
 export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME)
diff --git a/docs/src/run-hosting-environment.md b/docs/src/run-hosting-environment.md
new file mode 100644
index 000000000..a47a51e40
--- /dev/null
+++ b/docs/src/run-hosting-environment.md
@@ -0,0 +1,7 @@
+# Hosting Environment–specific Guides
+
+To help with common runtimes, we have written the following guides:
+
+- [Docker](run-with-docker.md)
+- [Docker-compose](run-with-docker-compose.md)
+- [AWS Lambda](run-with-lambda.md)
diff --git a/docs/src/run-with-reverse-proxy.md b/docs/src/run-with-reverse-proxy.md
new file mode 100644
index 000000000..0925f3acf
--- /dev/null
+++ b/docs/src/run-with-reverse-proxy.md
@@ -0,0 +1,15 @@
+# Reverse Proxies
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides:
+
+- Martin does not support HTTPS connections (TLS termination).
+- We do not check `HOST`-headers - we just serve on a port.
+  This means anybody can point their dns record to your server and serve to all requests going to the port Martin is running on.
+  Using a reverse proxy makes this abuse obvious.
+- Martin only supports a simple in-memory caching.
+  If you need more advanced caching options, you can use a reverse proxy like [Nginx](https://nginx.org/), [Varnish](https://varnish-cache.org/), or [Apache](https://httpd.apache.org/) with custom rules.
+  For example, you may choose to only cache zoom 0..10.
+- You may need to host more than just tiles at a single domain name.
+- Martin has a fixed public API, but your site may require a different structure, e.g. serving tiles with from a sub-path like `/tiles/source/z/x/y`.
diff --git a/docs/src/sources-pg-tables.md b/docs/src/sources-pg-tables.md
index 51968d5cc..64ea84402 100644
--- a/docs/src/sources-pg-tables.md
+++ b/docs/src/sources-pg-tables.md
@@ -1,8 +1,8 @@
-## Table Sources
+# PostgreSQL Table Sources
 
 Table Source is a database table which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). If a [PostgreSQL connection string](pg-connections.md) is given, Martin will publish all tables as data sources if they have at least one geometry column. If geometry column SRID is 0, a default SRID must be set, or else that geo-column/table will be ignored. All non-geometry table columns will be published as vector tile feature tags (properties).
 
-### Modifying Tilejson
+## Modifying Tilejson
 
 Martin will automatically generate a `TileJSON` manifest for each table source. It will contain the `name`, `description`, `minzoom`, `maxzoom`, `bounds` and `vector_layer` information.
 For example, if there is a table `public.table_source`:
@@ -43,7 +43,7 @@ The TileJSON:
 
 By default the `description` and `name` is database identifies about this table, and the bounds is queried from database. You can fine tune these by adjusting `auto_publish` section in [configuration file](https://maplibre.org/martin/config-file.html#config-example).
 
-#### TileJSON in SQL Comments
+## TileJSON in SQL Comments
 
 Other than adjusting `auto_publish` section in configuration file, you can fine tune the `TileJSON` on the database side directly: Add a valid JSON as an SQL comment on the table.
 
diff --git a/docs/src/sources-resources.md b/docs/src/sources-resources.md
new file mode 100644
index 000000000..8c3d9939e
--- /dev/null
+++ b/docs/src/sources-resources.md
@@ -0,0 +1,4 @@
+# Supporting Resources
+
+Data alone is not enough to show an interactive map.
+A map requires data, but it also requires fonts, sprites (sometimes called glyphs) and (dependent on the rendering engine) a style.
diff --git a/docs/src/sources-tiles.md b/docs/src/sources-tiles.md
new file mode 100644
index 000000000..7d43e64ea
--- /dev/null
+++ b/docs/src/sources-tiles.md
@@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin supports multiple tile sources
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-generated vector or raster tiles.
+- [PMTiles Sources](sources-files.md) A local file or a web-accessible HTTP source with the pre-generated raster or vector tiles.
+- [PostgreSQL Connections](pg-connections.md) with
+  - [Table Sources](sources-pg-tables.md)
+  - [Function Sources](sources-pg-functions.md)
+
+The difference between tile archives (*[MBTiles/PMTiles](sources-files.md)*) and a database ([PG-Table](sources-pg-tables.md)/[PG-Function](sources-pg-functions.md)) is that
+
+- **database** are more flexible and may (depending on how you fill it) be updated in **real-time**.
+- **Tile archives** on the other hand may (depending on the data) be more **compact, memory efficient and exhibit better performance** for tile-serving.
+
+=> For most usecases, you may want a mix of both. We support this via [Composite Sources](sources-composite.md)
+=> For some usecases, you want the flexibility of a database, but you don't want to pay the runtime-price. We offer the [`martin-cp`](martin-cp.md) utility to render all tiles into a tile archive. This can also be used to provide offline maps via [diffing and syncing `mbtiles`](mbtiles-diff.md)
+
+The difference between MBTiles and PMTiles is that:
+
+- **MBTiles** require the entire archive to be on the same machine. **PMTiles** can utilise a remote HTTP-Range request supporting server or a local file.
+- Performance wise, **MBTiles** is slightly faster than **PMTiles**, but with caching this is negligible.
+- Disk size wise, **MBTiles** is slightly (10-15%) higher than **PMTiles**.
+- **PMTiles** requires less memory in extreme cases as sqlite has a small in-memory cache.
+
+The choice depends on your specific usecase and requirements.
diff --git a/docs/src/tools.md b/docs/src/tools.md
index df4ea78fb..b0b68946c 100644
--- a/docs/src/tools.md
+++ b/docs/src/tools.md
@@ -1,17 +1,27 @@
-# CLI Tools
+# Provided Tools
+
+In addition to the `martin` tile server, we provide a set of tools to help build and manage maps. These tools are designed to work seamlessly with the `martin` server and can be used to generate tiles, manage data, and perform various operations on maps.
+
+## CLI Tools
 
 Martin project contains additional tooling to help manage the data servable with Martin tile server.
 
-## `martin-cp`
+### `martin-cp`
+
+`martin-cp` is a tool for generating tiles in bulk, and save retrieved tiles into a new or an existing MBTiles file. It can be used to generate tiles for a large area or multiple areas.
+If multiple areas overlap, it will generate tiles only once.
+`martin-cp` supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
 
-`martin-cp` is a tool for generating tiles in bulk, and save retrieved tiles into a new or an existing MBTiles file. It can be used to generate tiles for a large area or multiple areas. If multiple areas overlap, it will generate tiles only once. `martin-cp` supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
+See [this article](martin-cp.md) for more information.
 
-## `mbtiles`
+### `mbtiles`
 
-`mbtiles` is a small utility to interact with the `*.mbtiles` files from the command line. It allows users to examine, copy, validate, compare, and apply diffs between them.
+`mbtiles` is a small utility to interact with the `*.mbtiles` files from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
 
-Use `mbtiles --help` to see a list of available commands, and `mbtiles <command> --help` to see help for a specific command.
+See [this article](mbtiles.md) for more information.
 
-This tool can be installed by compiling the latest released version with `cargo install mbtiles --locked`, or by downloading a pre-built binary from the [releases page](https://github.com/maplibre/martin/releases/latest).
+### Supporting crates
 
-The `mbtiles` utility builds on top of the [MBTiles specification](https://github.com/mapbox/mbtiles-spec). It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets.
+Next to these tools, we also have a set of supporting crates for supporting the `martin` server and its ecosystem.
+Example of this is `martin-tile-utils` which is used in `martin`, `mbtiles` and `martin-cp`.
diff --git a/docs/src/using-guides.md b/docs/src/using-guides.md
new file mode 100644
index 000000000..77d5e9ecb
--- /dev/null
+++ b/docs/src/using-guides.md
@@ -0,0 +1,6 @@
+# Guides
+
+This section of the docs' site is dedicated to some examples and tutorials.
+If you have something you would like to share with the community that is not straightforward and might be beneficial to others, this is the place!
+
+The process of adding examples or guides is pretty straightforward, see our `docs` folder in the [Martin repository](https://github.com/maplibre/martin) for more information.
diff --git a/docs/src/using-with-data.md b/docs/src/using-with-data.md
new file mode 100644
index 000000000..a972270c8
--- /dev/null
+++ b/docs/src/using-with-data.md
@@ -0,0 +1,6 @@
+# Data source specific
+
+Some datasources are harder to setup than others.
+Below, we provide setup instructions for some common data sources:
+
+- [Hosted PostgreSQL](recipes.md)
diff --git a/docs/src/using-with-renderer.md b/docs/src/using-with-renderer.md
new file mode 100644
index 000000000..1ac980c83
--- /dev/null
+++ b/docs/src/using-with-renderer.md
@@ -0,0 +1,4 @@
+# Map renderer specific
+
+Martin is mostly a general purpose tileserver.
+The exception is style serving, as it is specific to [maplibre](https://maplibre.org).


Reviews:
user: login: copilot-pull-request-reviewer[bot]
body: 

Copilot reviewed 62 out of 63 changed files in this pull request and generated 1 comment.

<details>
<summary>Files not reviewed (1)</summary>

* **docs/src/config/resources/resources.**: Language not supported
</details>

<details>
<summary>Comments suppressed due to low confidence (1)</summary>

**docs/src/SUMMARY.md:17**
* The link text 'NGINX ' contains a trailing space; please remove it to ensure consistency.
```
 +    - [NGINX ](run/reverse-proxy/nginx.md)
```
</details>


state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T18:29:08Z
user: login: nyurik
body: awesome work, thx!  I made a number of content suggestions - some text may need a bit more polishing. We may need to go over it again. 
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-22T06:05:35Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T07:31:32Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T07:36:09Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T07:44:07Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:17:47Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:19:32Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:27:14Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:33:16Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:40:38Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:42:07Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:48:28Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T08:59:32Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T09:30:51Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T09:38:23Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-22T10:18:47Z
user: login: nyurik
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-22T16:14:13Z
user: login: nyurik
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-22T16:15:47Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:21:29Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:25:16Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:27:41Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:35:08Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:36:51Z
user: login: CommanderStorm
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-24T01:42:05Z
user: login: copilot-pull-request-reviewer[bot]
body: ## Pull Request Overview

This PR reorganizes the documentation sidebar to present a clearer, tidier structure for users. Key changes include adding new pages for specific topics (e.g. map renderer, data sources, guides), reorganizing existing sections (e.g. tools, sources, hosting environments), and updating the SUMMARY.md to reflect the new layout.

### Reviewed Changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

<details>
<summary>Show a summary per file</summary>

| File                             | Description                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| docs/src/using-with-renderer.md  | Added a new page for map renderer specifics                                        |
| docs/src/using-with-data.md      | Introduced data source instructions                                                |
| docs/src/using-guides.md         | Created a guides page for tutorials and examples                                   |
| docs/src/tools.md                | Updated tools documentation and section headings                                   |
| docs/src/sources-tiles.md        | Enhanced tile source docs with clearer categorization                              |
| docs/src/sources-resources.md    | Added supporting resources for maps                                                |
| docs/src/sources-pg-tables.md    | Revised PostgreSQL table sources documentation                                     |
| docs/src/run-with-reverse-proxy.md| Added documentation for reverse proxy usage                                        |
| docs/src/run-hosting-environment.md| Introduced hosting environment–specific guides                                   |
| docs/src/recipes.md              | Updated PostgreSQL usage guides with provider-specific details                     |
| docs/src/mbtiles.md              | Added a section on working with MBTiles archives                                   |
| docs/src/martin-cp.md            | Refined the description and usage of martin-cp tool                                |
| docs/src/getting-involved.md     | Minor adjustments in code snippet annotations                                      |
| docs/src/env-vars.md             | Updated the environment variables table with revised formatting                    |
| docs/src/SUMMARY.md              | Restructured the sidebar navigation to align with the new documentation hierarchy    |
</details>


<details>
<summary>Files not reviewed (1)</summary>

* **.github/files/config.markdownlint-cli2.jsonc**: Language not supported
</details>



state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T01:57:50Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-24T02:09:27Z
user: login: sharkAndshark
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-24T02:34:00Z
user: login: nyurik
body: thx!
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-24T02:58:39Z
user: login: sharkAndshark
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-04-24T03:00:56Z

Review comments:
diff_hunk: @@ -0,0 +1,23 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
+- [PostgreSQL Connections](pg-connections.md) via 
+  - [Table Sources](pg-tables.md)
+  - [Function Sources](pg-functions.md)
+
+The difference between tile archives (*[MBTiles/PMTiles](sources-files.md)*) and a database ([PG-Table](pg-tables.md)/[PG-Function](pg-functions.md)) is that
+- **database** are more flexible and may (depending on how you fill it) be updated in **real-time**.
+- **Tile archives** on the other hand may (depending on the data) be more **compact, memory efficient and exhibit better performance** for tile-serving.
+
+=> For most usecases, you may want a mix of both. We support this via [Composite Sources](sources-composite.md)
+
+The difference between MBTiles and PMTiles is that 
+- **MBTiles** require the entire archive to be on the same machine. **PMTiles** can utilise a remote HTTP-Range request supporting server or a local file.
+- Performance wise, **MBTiles** is slightly higher than **PMTiles**, but with caching this is negligible.
+- Disk size wise, **MBTiles** is slightly (10-15%) higher than **PMTiles**.
+- **PMTiles** requires less memory in exterme cases as sqlite has a small in-memory cache.
path: docs/src/config/tiles/tiles.md
user: login: Copilot
body: The word 'exterme' appears to be a typo; please correct it to 'extreme'.
```suggestion
- **PMTiles** requires less memory in extreme cases as sqlite has a small in-memory cache.
```
created_at: 2025-04-16T18:29:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -7,7 +7,9 @@
     "MD041": false,
     "MD033": false,
     "MD045": false,
-    "MD001": false
+    "MD001": false,
+    // mdbook uses empty links as sections which are not yet written
+    "MD042": false
path: .github/files/config.markdownlint-cli2.jsonc
user: login: nyurik
body: if this file supports comments, I am pretty sure it will support trailing commas too - this way diffs will be smaller. Also, a minor nit - perhaps sort them?
created_at: 2025-04-22T05:33:24Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
path: docs/src/mbtiles.md
user: login: nyurik
body: ```suggestion
Martin includes `mbtiles` utility to interact with the [`*.mbtiles` files](mbtiles-schema.md) from the command line.
```
created_at: 2025-04-22T05:43:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: ```suggestion
Doing so has a few downsides:
```
created_at: 2025-04-22T05:46:15Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: ```suggestion
- Martin does not support HTTPS connections (TLS termination).
```
created_at: 2025-04-22T05:47:31Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: this is not very clear
created_at: 2025-04-22T05:48:07Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
+- Martin only has one-size-fit-all caching. If you need more advanced caching options, you can use a reverse proxy like Nginx or Apache and cache for example only tiles from z10 and up.
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: ```suggestion
- Martin only supports a simple in-memory caching. If you need more advanced caching options, you can use a reverse proxy like Nginx, Varnish, or Apache with custom rules. For example, you may choose to only cache zoom 0..10.
```
created_at: 2025-04-22T05:49:30Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
+- Martin only has one-size-fit-all caching. If you need more advanced caching options, you can use a reverse proxy like Nginx or Apache and cache for example only tiles from z10 and up.
+- You likely want more than one thing running on the same server, such as a web server.
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: ```suggestion
- You may need to host more than just tiles at a single domain name.
```
created_at: 2025-04-22T05:51:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
+- Martin only has one-size-fit-all caching. If you need more advanced caching options, you can use a reverse proxy like Nginx or Apache and cache for example only tiles from z10 and up.
+- You likely want more than one thing running on the same server, such as a web server.
+- We don't handle subpath routing. (e.g. serving at `/tiles`)
path: docs/src/run-with-reverse-proxy.md
user: login: nyurik
body: ```suggestion
- Martin has a fixed public API, but your site may require a different structure, e.g. serving tiles with from a sub-path like `/tiles/source/z/x/y`.
```
created_at: 2025-04-22T05:52:23Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,4 @@
+# Supporting Resources
+
+Data alone is not enough to create a map.
path: docs/src/sources-resources.md
user: login: nyurik
body: ```suggestion
Data alone is not enough to show an interactive map.
```
created_at: 2025-04-22T05:53:47Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
path: docs/src/sources-tiles.md
user: login: nyurik
body: ```suggestion
Martin supports multiple tile sources
```
created_at: 2025-04-22T05:54:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
path: docs/src/sources-tiles.md
user: login: nyurik
body: "pre-rendered" is confusing here - MBTiles may have raster or vector images

```suggestion
- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-generated vector or raster tiles.
```
created_at: 2025-04-22T05:55:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
path: docs/src/sources-tiles.md
user: login: nyurik
body: ```suggestion
- [PMTiles Sources](sources-files.md) A local file or a web-accessible HTTP source with the pre-generated raster or vector tiles.
```
created_at: 2025-04-22T05:57:22Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
+- [PostgreSQL Connections](pg-connections.md) via
path: docs/src/sources-tiles.md
user: login: nyurik
body: ```suggestion
- [PostgreSQL Connections](pg-connections.md) with
```
created_at: 2025-04-22T05:57:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
+- [PostgreSQL Connections](pg-connections.md) via
+  - [Table Sources](sources-pg-tables.md)
+  - [Function Sources](sources-pg-functions.md)
+
+The difference between tile archives (*[MBTiles/PMTiles](sources-files.md)*) and a database ([PG-Table](sources-pg-tables.md)/[PG-Function](sources-pg-functions.md)) is that
+
+- **database** are more flexible and may (depending on how you fill it) be updated in **real-time**.
+- **Tile archives** on the other hand may (depending on the data) be more **compact, memory efficient and exhibit better performance** for tile-serving.
+
+=> For most usecases, you may want a mix of both. We support this via [Composite Sources](sources-composite.md)
+=> For some usecases, you want the flexibility of a database, but you don't want to pay the runtime-price. We offer the [`martin-cp`](martin-cp.md) utility to render all tiles into a tile archive. This can also be used to provide offline maps via [diffing and syncing `mbtiles`](mbtiles-diff.md)
+
+The difference between MBTiles and PMTiles is that
+
+- **MBTiles** require the entire archive to be on the same machine. **PMTiles** can utilise a remote HTTP-Range request supporting server or a local file.
+- Performance wise, **MBTiles** is slightly higher than **PMTiles**, but with caching this is negligible.
path: docs/src/sources-tiles.md
user: login: nyurik
body: ```suggestion
- Performance wise, **MBTiles** is slightly faster than **PMTiles**, but with caching this is negligible.
```
created_at: 2025-04-22T05:58:48Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
+- [PostgreSQL Connections](pg-connections.md) via
+  - [Table Sources](sources-pg-tables.md)
+  - [Function Sources](sources-pg-functions.md)
+
+The difference between tile archives (*[MBTiles/PMTiles](sources-files.md)*) and a database ([PG-Table](sources-pg-tables.md)/[PG-Function](sources-pg-functions.md)) is that
+
+- **database** are more flexible and may (depending on how you fill it) be updated in **real-time**.
+- **Tile archives** on the other hand may (depending on the data) be more **compact, memory efficient and exhibit better performance** for tile-serving.
+
+=> For most usecases, you may want a mix of both. We support this via [Composite Sources](sources-composite.md)
+=> For some usecases, you want the flexibility of a database, but you don't want to pay the runtime-price. We offer the [`martin-cp`](martin-cp.md) utility to render all tiles into a tile archive. This can also be used to provide offline maps via [diffing and syncing `mbtiles`](mbtiles-diff.md)
+
+The difference between MBTiles and PMTiles is that
+
+- **MBTiles** require the entire archive to be on the same machine. **PMTiles** can utilise a remote HTTP-Range request supporting server or a local file.
+- Performance wise, **MBTiles** is slightly higher than **PMTiles**, but with caching this is negligible.
+- Disk size wise, **MBTiles** is slightly (10-15%) higher than **PMTiles**.
+- **PMTiles** requires less memory in extreme cases as sqlite has a small in-memory cache.
+
+Given that these are tradeoffs, there is no clear winner. The choice depends on your specific usecase and requirements.
path: docs/src/sources-tiles.md
user: login: nyurik
body: ```suggestion
The choice depends on your specific usecase and requirements.
```
created_at: 2025-04-22T05:59:53Z
author_association: MEMBER
diff_hunk: @@ -1,17 +1,27 @@
-# CLI Tools
+# Provided Tools
+
+Next to the `martin` server, we provide a set of tools to help build and manage maps. These tools are designed to work seamlessly with the `martin` server and can be used to generate tiles, manage data, and perform various operations on maps.
path: docs/src/tools.md
user: login: nyurik
body: ```suggestion
In addition to the `martin` tile server, we provide a set of tools to help build and manage maps. These tools are designed to work seamlessly with the `martin` server and can be used to generate tiles, manage data, and perform various operations on maps.
```
created_at: 2025-04-22T06:00:27Z
author_association: MEMBER
diff_hunk: @@ -7,7 +7,9 @@
     "MD041": false,
     "MD033": false,
     "MD045": false,
-    "MD001": false
+    "MD001": false,
+    // mdbook uses empty links as sections which are not yet written
+    "MD042": false
path: .github/files/config.markdownlint-cli2.jsonc
user: login: sharkAndshark
body: Could we ignore MD042 only for `summary.md`, keeping this rule would be better. See https://github.com/DavidAnson/markdownlint/?tab=readme-ov-file#configuration

```md
    - [Setting up a basemap and overlaying data]() <!-- markdownlint-disable-line MD042 -->
    - [Using PMTiles via S3]() <!-- markdownlint-disable-line MD042 -->
```
created_at: 2025-04-22T07:31:32Z
author_association: COLLABORATOR
diff_hunk: @@ -4,7 +4,7 @@ You can also configure Martin using environment variables, but only if the confi
 
 | Environment var <br/> Config File key    | Example                              | Description                                                                                                                                                                                                |
 |------------------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `DATABASE_URL` <br/> `connection_string` | `postgresql://postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
+| `DATABASE_URL` <br/> `connection_string` | `postgresql://`<br/>`postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
path: docs/src/env-vars.md
user: login: sharkAndshark
body: Let's not add new line here? As someone would want to copy and modify it.
created_at: 2025-04-22T07:36:09Z
author_association: COLLABORATOR
diff_hunk: @@ -84,7 +84,7 @@ Go to any part you're interested in of martin code and add a breakpoint.
 
 We add a breakpoint here in the [start of martin](https://github.com/maplibre/martin/blob/e628c3973f193a432d3d1282c5893e2339e806b6/martin/src/bin/martin.rs#L10).
 
-```rust
+```rust,norun
path: docs/src/getting-involved.md
user: login: sharkAndshark
body: Maybe we should use `ignore`. see https://rust-lang.github.io/mdBook/format/mdbook.html#rust-code-block-attributes.  Only for hidding play button, the `norun` is enough though.

```suggestion
```rust, ignore 
```
created_at: 2025-04-22T07:44:07Z
author_association: COLLABORATOR
diff_hunk: @@ -1,18 +1,20 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
+into a new or an existing MBTiles file.
path: docs/src/martin-cp.md
user: login: sharkAndshark
body: I'm wondering why breaks this to a new line? Is there some linting rule for this(like line length? But I see other sentence longer than this not follow this braking)? For readability? My `just fmt-md` say nothing about this.
created_at: 2025-04-22T08:17:47Z
author_association: COLLABORATOR
diff_hunk: @@ -1,18 +1,20 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
+into a new or an existing MBTiles file.
+
+`martin-cp` can be used to generate tiles for a large area or multiple areas
 (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. `martin-cp` supports the
 same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
path: docs/src/martin-cp.md
user: login: sharkAndshark
body: Wondering breaking to two lines either.
created_at: 2025-04-22T08:19:31Z
author_association: COLLABORATOR
diff_hunk: @@ -1,18 +1,20 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
+into a new or an existing MBTiles file.
+
+`martin-cp` can be used to generate tiles for a large area or multiple areas
 (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. `martin-cp` supports the
 same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
 
 After copying, `martin-cp` will update the `agg_tiles_hash` metadata value unless `--skip-agg-tiles-hash` is specified.
-This allows the MBTiles file to be [validated](./mbtiles-validation.md#aggregate-content-validation)
+This allows the MBTiles file to be [validated](mbtiles-validation.md#aggregate-content-validation)
 using `mbtiles validate` command.
path: docs/src/martin-cp.md
user: login: sharkAndshark
body: Line breaks either.
created_at: 2025-04-22T08:27:13Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
path: docs/src/mbtiles.md
user: login: sharkAndshark
body: ```suggestion

It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
```
created_at: 2025-04-22T08:33:15Z
author_association: COLLABORATOR
diff_hunk: @@ -1,6 +1,9 @@
-## Recipes
+# Hosted PostgreSQL
 
-### Using with DigitalOcean PostgreSQL
+Some providers of postgres databases require additional configuration to work with Martin.
+We try to provide a guide for each provider, but we may not cover all of them.
+
+## Using with DigitalOcean PostgreSQL
 
 You can use Martin
 with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with
path: docs/src/recipes.md
user: login: sharkAndshark
body: Line breaking either.
created_at: 2025-04-22T08:40:38Z
author_association: COLLABORATOR
diff_hunk: @@ -15,7 +18,7 @@ martin --ca-root-file ./ca-certificate.crt \
        postgresql://user:password@host:port/db?sslmode=require
 ```
 
-### Using with Heroku PostgreSQL
+## Using with Heroku PostgreSQL
 
 You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with PostGIS extension
path: docs/src/recipes.md
user: login: sharkAndshark
body: ```suggestion
You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with the PostGIS extension
```
created_at: 2025-04-22T08:42:06Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
+
+Use `mbtiles --help` to see a list of available commands, and `mbtiles <command> --help` to see help for a specific command.
+
+This tool can be installed by compiling the latest released version with `cargo install mbtiles --locked`, or by downloading a pre-built binary from the [releases page](https://github.com/maplibre/martin/releases/latest).
+
+The `mbtiles` utility builds on top of the [MBTiles specification](https://github.com/mapbox/mbtiles-spec). It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets.
path: docs/src/mbtiles.md
user: login: sharkAndshark
body: Maybe delete this paragraph? Seems a little bit duplicated with the first paragraph?

```suggestion
The `mbtiles` utility builds on top of the [MBTiles specification](https://github.com/mapbox/mbtiles-spec). It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets.
```
created_at: 2025-04-22T08:48:28Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,7 @@
+# Runtime-specific Guides
path: docs/src/run-with-runtime.md
user: login: sharkAndshark
body: Runtime is a little bit confusing? @nyurik 
```suggestion
# Deployment-specific Guides
```
created_at: 2025-04-22T08:59:32Z
author_association: COLLABORATOR
diff_hunk: @@ -1,6 +1,9 @@
-## Recipes
+# Hosted PostgreSQL
 
-### Using with DigitalOcean PostgreSQL
+Some providers of postgres databases require additional configuration to work with Martin.
path: docs/src/recipes.md
user: login: sharkAndshark
body: 
```suggestion
Some providers of PostgreSQL databases require additional configuration to work with Martin.
```
created_at: 2025-04-22T09:30:51Z
author_association: COLLABORATOR
diff_hunk: @@ -1,4 +1,4 @@
-## Table Sources
+# PostgreSQL Table Sources
path: docs/src/sources-pg-tables.md
user: login: sharkAndshark
body: A level jumping from `# PostgreSQL Table Sources`  to `### Modifying Tilejson `
created_at: 2025-04-22T09:38:23Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,26 @@
+# Tile Sources
+
+Martin does support these tile sources:
+
+- [MBTiles Sources](sources-files.md) Local Sqlite database containing pre-rendered tiles.
+- [PMTiles Sources](sources-files.md) Local or remote file with pre-rendered tiles in a pre-defined order.
+- [PostgreSQL Connections](pg-connections.md) via
+  - [Table Sources](sources-pg-tables.md)
+  - [Function Sources](sources-pg-functions.md)
+
+The difference between tile archives (*[MBTiles/PMTiles](sources-files.md)*) and a database ([PG-Table](sources-pg-tables.md)/[PG-Function](sources-pg-functions.md)) is that
+
+- **database** are more flexible and may (depending on how you fill it) be updated in **real-time**.
+- **Tile archives** on the other hand may (depending on the data) be more **compact, memory efficient and exhibit better performance** for tile-serving.
+
+=> For most usecases, you may want a mix of both. We support this via [Composite Sources](sources-composite.md)
+=> For some usecases, you want the flexibility of a database, but you don't want to pay the runtime-price. We offer the [`martin-cp`](martin-cp.md) utility to render all tiles into a tile archive. This can also be used to provide offline maps via [diffing and syncing `mbtiles`](mbtiles-diff.md)
+
+The difference between MBTiles and PMTiles is that
path: docs/src/sources-tiles.md
user: login: sharkAndshark
body: ```suggestion
The difference between MBTiles and PMTiles is that:
```
created_at: 2025-04-22T10:18:47Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,7 @@
+# Runtime-specific Guides
path: docs/src/run-with-runtime.md
user: login: nyurik
body: Or `hosting environment` ?
created_at: 2025-04-22T16:14:13Z
author_association: MEMBER
diff_hunk: @@ -4,7 +4,7 @@ You can also configure Martin using environment variables, but only if the confi
 
 | Environment var <br/> Config File key    | Example                              | Description                                                                                                                                                                                                |
 |------------------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `DATABASE_URL` <br/> `connection_string` | `postgresql://postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
+| `DATABASE_URL` <br/> `connection_string` | `postgresql://`<br/>`postgres@localhost/db` | Postgres database connection                                                                                                                                                                               |
path: docs/src/env-vars.md
user: login: nyurik
body: I tried - you can still copy it. The table does look a bit better this way.  We do want to reformat the markdown though
created_at: 2025-04-22T16:15:47Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
+
+Use `mbtiles --help` to see a list of available commands, and `mbtiles <command> --help` to see help for a specific command.
+
+This tool can be installed by compiling the latest released version with `cargo install mbtiles --locked`, or by downloading a pre-built binary from the [releases page](https://github.com/maplibre/martin/releases/latest).
+
+The `mbtiles` utility builds on top of the [MBTiles specification](https://github.com/mapbox/mbtiles-spec). It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets.
path: docs/src/mbtiles.md
user: login: CommanderStorm
body: https://github.com/maplibre/martin/pull/1796/files#r2053648354

```suggestion
```
created_at: 2025-04-24T01:21:28Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
+- Martin only has one-size-fit-all caching. If you need more advanced caching options, you can use a reverse proxy like Nginx or Apache and cache for example only tiles from z10 and up.
path: docs/src/run-with-reverse-proxy.md
user: login: CommanderStorm
body: ```suggestion
- Martin only supports a simple in-memory caching.
  If you need more advanced caching options, you can use a reverse proxy like [Nginx](https://nginx.org/), [Varnish](https://varnish-cache.org/), or [Apache](https://httpd.apache.org/) with custom rules.
  For example, you may choose to only cache zoom 0..10.
```
created_at: 2025-04-24T01:25:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,7 @@
+# Runtime-specific Guides
path: docs/src/run-with-runtime.md
user: login: CommanderStorm
body: ```suggestion
# Hosting Environment–specific Guides
```
created_at: 2025-04-24T01:27:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
path: docs/src/mbtiles.md
user: login: CommanderStorm
body: I prefer leaving them together.
I think both are part of the short "one sentence" (here two, as much content) summary, that a good paragrah should have.

If you have a strong oppinion on this, we can add a newline here.
created_at: 2025-04-24T01:35:07Z
author_association: MEMBER
diff_hunk: @@ -1,18 +1,20 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
+into a new or an existing MBTiles file.
path: docs/src/martin-cp.md
user: login: CommanderStorm
body: This is already in this file for quite some time. Likely some editor config back in the day or someone really liking 80 cols and not having their editor configured like I have:

![image](https://github.com/user-attachments/assets/5d79f214-5667-4e18-8463-b804677e8ea1)

created_at: 2025-04-24T01:36:51Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,11 @@
+# Reverse Proxys
+
+Martin can run without a reverse proxy.
+
+Doing so has a few downsides though:
+
+- Martin by itself does not handle certificates => you won't be able to use HTTPS.
+- We would serve to all requests going to the port Martin is running on
path: docs/src/run-with-reverse-proxy.md
user: login: CommanderStorm
body: True, how about

```suggestion
- We do not check `HOST`-headers - we just serve on a port.
  This means anybody can point their dns record to your server and serve to all requests going to the port Martin is running on.
  Using a reverse proxy makes this abuse obvious.
```
created_at: 2025-04-24T01:42:04Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,13 @@
+# Reverse Proxys
+
path: docs/src/run-with-reverse-proxy.md
user: login: Copilot
body: Consider changing 'Reverse Proxys' to 'Reverse Proxies' for correct pluralization.
```suggestion
# Reverse Proxies
```
created_at: 2025-04-24T01:57:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,6 @@
+# Guides
+
+This section of the docs' site is dedicated to some examples and tutorials.
+If you have something you would like to share with the community that is not straight forward and might be beneficial to others, this is the place!
+
+The process of adding examples or guides is pretty straight forward, see our `docs` folder in the [Martin repository](https://github.com/maplibre/martin) for more information.
path: docs/src/using-guides.md
user: login: Copilot
body: [nitpick] Consider replacing 'straight forward' with 'straightforward' for improved clarity.
```suggestion
If you have something you would like to share with the community that is not straightforward and might be beneficial to others, this is the place!

The process of adding examples or guides is pretty straightforward, see our `docs` folder in the [Martin repository](https://github.com/maplibre/martin) for more information.
```
created_at: 2025-04-24T01:57:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,36 +8,45 @@
 - [Installation](installation.md)
 - [Running](run.md)
   - [Command Line Interface](run-with-cli.md)
-    - [Environment Variables](env-vars.md)
-  - [Running with Docker](run-with-docker.md)
-  - [Running with Docker Compose](run-with-docker-compose.md)
-  - [Running with NGINX](run-with-nginx.md)
-  - [Running with Apache](run-with-apache.md)
-  - [Running in AWS Lambda](run-with-lambda.md)
+  - [Environment Variables](env-vars.md)
+  - [Hosting Environment–specific Guides](run-hosting-environment.md)
+    - [Docker](run-with-docker.md)
+    - [Docker Compose](run-with-docker-compose.md)
+    - [AWS Lambda](run-with-lambda.md)
+  - [Reverse Proxys](run-with-reverse-proxy.md)
+    - [NGINX](run-with-nginx.md)
+    - [Apache](run-with-apache.md)
   - [Troubleshooting](troubleshooting.md)
 - [Configuration File](config-file.md)
-  - [PostgreSQL Connections](pg-connections.md)
-  - [PostgreSQL Table Sources](sources-pg-tables.md)
-  - [PostgreSQL Function Sources](sources-pg-functions.md)
-  - [MBTiles and PMTiles File Sources](sources-files.md)
-  - [Composite Sources](sources-composite.md)
-  - [Sprite Sources](sources-sprites.md)
-  - [Style Sources](sources-styles.md)
-  - [Font Sources](sources-fonts.md)
-- [Usage and Endpoint API](using.md)
-  - [Using with MapLibre](using-with-maplibre.md)
-  - [Using with Leaflet](using-with-leaflet.md)
-  - [Using with deck.gl](using-with-deck-gl.md)
-  - [Using with Mapbox](using-with-mapbox.md)
-  - [Using with OpenLayers](using-with-openlayers.md)
-  - [Recipes](recipes.md)
-- [Tools](tools.md)
-  - [martin-cp bulk tile generation](martin-cp.md)
-  - [MBTiles Metadata](mbtiles-meta.md)
-  - [MBTiles Schemas](mbtiles-schema.md)
-  - [Copying MBTiles](mbtiles-copy.md)
-  - [Diffing/Patching MBTiles](mbtiles-diff.md)
-  - [Validating MBTiles](mbtiles-validation.md)
+  - [Tile sources](sources-tiles.md)
+    - [MBTiles and PMTiles File Sources](sources-files.md)
+    - [PostgreSQL Connections](pg-connections.md)
+      - [PostgreSQL Table Sources](sources-pg-tables.md)
+      - [PostgreSQL Function Sources](sources-pg-functions.md)
+    - [Composite Sources](sources-composite.md)
+  - [Supporting Resources](sources-resources.md)
+    - [Sprites](sources-sprites.md)
+    - [Styles](sources-styles.md)
+    - [Fonts](sources-fonts.md)
+- [Avaliable API Endpoints](using.md)
+- [Guides](using-guides.md)
+  - [Map renderer specific](using-with-renderer.md)
+    - [MapLibre](using-with-maplibre.md)
+    - [Leaflet](using-with-leaflet.md)
+    - [deck.gl](using-with-deck-gl.md)
+    - [Mapbox](using-with-mapbox.md)
+    - [OpenLayers](using-with-openlayers.md)
+  - [Data source specific](using-with-data.md)
+    - [Using Hosted PostgreSQL](recipes.md)
+    - [Setting up a basemap and overlaying data]() <!-- markdownlint-disable-line MD042 -->
path: docs/src/SUMMARY.md
user: login: Copilot
body: The link for 'Setting up a basemap and overlaying data' is empty. Please provide a valid URL or remove the link if not needed.
```suggestion
    <!-- Placeholder for "Setting up a basemap and overlaying data" removed -->
```
created_at: 2025-04-24T01:57:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,10 @@
+# Working with MBTiles archives
+
+We offer the `mbtiles` utility to interact with the `*.mbtiles` files (see [this page](mbtiles-schema.md) for more information) from the command line.
+It allows users to [examine](mbtiles-meta.md), [copy](mbtiles-copy.md), [validate](mbtiles-validation.md) or [compare and apply diffs between them](mbtiles-diff.md).
path: docs/src/mbtiles.md
user: login: sharkAndshark
body: My bad. I didn't noticed they are one single paragraph but with to two lines. 
created_at: 2025-04-24T02:09:27Z
author_association: COLLABORATOR
diff_hunk: @@ -1,18 +1,20 @@
 # Generating Tiles in Bulk
 
-`martin-cp` is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
-into a new or an existing MBTiles file. `martin-cp` can be used to generate tiles for a large area or multiple areas
+We offer the `martin-cp` tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles
+into a new or an existing MBTiles file.
path: docs/src/martin-cp.md
user: login: sharkAndshark
body: Guessing breaking to lines is good to git diff?  I'm ok with this. Just wondering.
created_at: 2025-04-24T02:34:00Z
author_association: COLLABORATOR

PR comments:
user: login: nyurik
created_at: 2025-04-16T19:08:40Z
body: I am all in favor of improving the docs, thanks!  One important note is that we cannot rename files - or at least we must have some sort of a redirection in place - because we don't want to break URLs for the users from various stackoverflow or forum sites.
author_association: MEMBER
user: login: CommanderStorm
created_at: 2025-04-16T19:48:41Z
body: Well that sucks. Did not think of that.
Will revert those changes
author_association: MEMBER
user: login: nyurik
created_at: 2025-04-16T20:31:29Z
body: you can still restructure the sidebar - its design is not dictated by the filenames. Just keep the original filenames for what's relevant - although it is ok to move some things to new files if needed

P.S. I meant that if you want to split a file into two, that should be ok - just keep the content closest to the overall meaning to the original file
author_association: MEMBER
user: login: CommanderStorm
created_at: 2025-04-16T22:33:14Z
body: > you can still restructure the sidebar - its design is not dictated by the filenames. Just keep the original filenames for what's relevant - although it is ok to move some things to new files if needed

That is exactly what I meant with "those changes" ^^
author_association: MEMBER
user: login: nyurik
created_at: 2025-04-16T22:36:02Z
body: `tools.md` is the only one deleted now
author_association: MEMBER
user: login: CommanderStorm
created_at: 2025-04-16T22:44:24Z
body: Yes, but I don't have a replacement for this..
I could add another section below this, but that would also be super akward..

Maybe moving this into the developemnt section would be possible, and then ading above these sections martin to give devs a bit more of "the lay of the land".

Would not be a context fit though. I think breaking this liink is a better call.
author_association: MEMBER
user: login: nyurik
created_at: 2025-04-16T22:55:11Z
body: breaking a link is never good. We do not have to list the file in the side bar, but that file should continue to exist if only as a (soft) redirect
author_association: MEMBER
user: login: nyurik
created_at: 2025-04-16T22:56:08Z
body: note that mdbook has a redirect configuration:  https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect
author_association: MEMBER
user: login: sharkAndshark
created_at: 2025-04-17T03:59:30Z
body: Agree with @nyurik we must be careful to break the links. Any maybe we could maintain various versions doc at same time then we can never break links. Like breaking links in new version. But is this a good idea…? I'm not very sure 
author_association: COLLABORATOR
user: login: sharkAndshark
created_at: 2025-04-17T04:00:57Z
body: Like add version number to doc and version switch button to it? Maybe a bad idea, let's just do small fix and append to it
author_association: COLLABORATOR
user: login: nyurik
created_at: 2025-04-17T04:07:44Z
body: I'm not a big fan of multi-versioned docs - those are usually messy, contain a lot of duplicate content, and don't actually that much extra value.  Instead, we can just add redirects if we ever need to remove pages, and try to be conservative with adding new pages?
author_association: MEMBER
user: login: sharkAndshark
created_at: 2025-04-17T04:47:42Z
body: Taste about doc is really personally. I'm satisfied with the current structure(it's plain and simple). This new structure is a little bit too nested? I might be wrong. Just personal view, let's talk. : )
author_association: COLLABORATOR
user: login: CommanderStorm
created_at: 2025-04-17T08:52:31Z
body: Regarding your concearns @nyurik
okay, I have moved the tools.md to the development section. That should solve the linking problem
author_association: MEMBER
user: login: CommanderStorm
created_at: 2025-04-17T08:52:34Z
body: Regarding your concearns @sharkAndshark
About the too much nesting concearn, what about removing the red parts, but keeping the green parts?
Some of the green parts give semi-important grouping like
- grouping all map renderers,
- making users read about how to connect to postgres before reading about publishing tables
- given a section why a user might use which data source

4.1 and 6.1 are sections I feel strongly about, the others are highly negotiable ^^

![image](https://github.com/user-attachments/assets/8d764322-e73d-4537-8fee-b3559e143b3b)
author_association: MEMBER
user: login: CommanderStorm
created_at: 2025-04-22T23:22:40Z
body: Thanks to you both for the extensive reviews.

I will only be able to go through them on the weekend, after my hell-week of the semester (I purposely oversubscribe on courses to take and only continue those which do good teaching), just that we are clear in communication ^^
author_association: MEMBER
user: login: sharkAndshark
created_at: 2025-04-24T03:01:29Z
body: Love better doc! Approved!
author_association: COLLABORATOR