rommapp · gantoine · May 4, 2026 · May 4, 2026 · May 4, 2026 · May 4, 2026
diff --git a/docs/Navigation.md b/docs/Navigation.md
@@ -9,6 +9,7 @@ search:
 - Getting Started
     - [Quick Start](getting-started/quick-start.md)
     - [Folder Structure](getting-started/folder-structure.md)
+    - [Metadata Providers](getting-started/metadata-providers.md)
     - [Your First Scan](getting-started/first-scan.md)
 - Install & Deploy
     - [Overview](install/index.md)
@@ -33,7 +34,6 @@ search:
         - [Keycloak](administration/oidc/keycloak.md)
         - [PocketID](administration/oidc/pocketid.md)
         - [Zitadel](administration/oidc/zitadel.md)
-    - [Metadata Providers](administration/metadata-providers.md)
     - [Scanning & Watcher](administration/scanning-and-watcher.md)
     - [Scheduled Tasks](administration/scheduled-tasks.md)
     - [Server Stats](administration/server-stats.md)

diff --git a/docs/administration/index.md b/docs/administration/index.md
@@ -20,7 +20,7 @@ The end-user equivalent (how to actually play the games, build collections, uplo
 
 ### Content & library
 
-- **[Metadata Providers](metadata-providers.md)**: all providers, credentials, priority ordering
+- **[Metadata Providers](../getting-started/metadata-providers.md)**: all providers, credentials, priority ordering
 - **[Scanning & Watcher](scanning-and-watcher.md)**: how scans work, scan modes, filesystem watcher
 - **[Firmware Management](firmware-management.md)**: BIOS/firmware uploads for emulation
 

diff --git a/docs/administration/scanning-and-watcher.md b/docs/administration/scanning-and-watcher.md
@@ -117,7 +117,7 @@ When a metadata provider returns multiple regional variants (Japanese cover, US
 
 ## Metadata source priority
 
-Who wins when two providers disagree is covered in [Metadata Providers](metadata-providers.md#priority-and-conflict-resolution), though the short version is `scan.priority.metadata` and `scan.priority.artwork` in `config.yml`.
+Who wins when two providers disagree is covered in [Metadata Providers](../getting-started/metadata-providers.md#priority-and-conflict-resolution), though the short version is `scan.priority.metadata` and `scan.priority.artwork` in `config.yml`.
 
 ## Troubleshooting
 

diff --git a/docs/getting-started/first-scan.md b/docs/getting-started/first-scan.md
@@ -5,7 +5,7 @@ description: Populate a fresh install by scanning the library for the first time
 
 # Your First Scan
 
-You're up and running ([Quick Start](quick-start.md)), your ROMs are laid out correctly ([Folder Structure](folder-structure.md)), and metadata credentials are configured ([Metadata Providers](../administration/metadata-providers.md)). Time to catalogue everything!
+You're up and running ([Quick Start](quick-start.md)), your ROMs are laid out correctly ([Folder Structure](folder-structure.md)), and metadata credentials are configured ([Metadata Providers](metadata-providers.md)). Time to catalogue everything!
 
 ## Before you hit scan
 

diff --git a/docs/getting-started/folder-structure.md b/docs/getting-started/folder-structure.md
@@ -162,7 +162,7 @@ Filenames are parsed for region, language, revision, and arbitrary tags, with bo
 - **Revision**: prefix with `rev`/`rev-` (e.g. `rev v1`, `rev-1`)
 - **Arbitrary tags**: anything else in brackets is imported verbatim (e.g. `tetris [1.0001](HACK)[!].gba`)
 
-Inline tags like `(igdb-1234)` in filenames can be used to force a match to a specific provider entry, covered in [Metadata Providers → Filename tags](../administration/metadata-providers.md#metadata-tags-in-filenames).
+Inline tags like `(igdb-1234)` in filenames can be used to force a match to a specific provider entry, covered in [Metadata Providers → Filename tags](metadata-providers.md#metadata-tags-in-filenames).
 
 <div class="grid cards" markdown>
 

diff --git a/docs/administration/metadata-providers.md → docs/getting-started/metadata-providers.md b/docs/administration/metadata-providers.md → docs/getting-started/metadata-providers.md
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -13,7 +13,7 @@ You'll need:
 
 - [Docker](https://docs.docker.com/get-docker/) and Docker Compose installed on the host
 - Your ROM files organised in the expected [folder structure](folder-structure.md)
-- API credentials for at least one [metadata provider](../administration/metadata-providers.md)
+- API credentials for at least one [metadata provider](metadata-providers.md)
 
 <!-- prettier-ignore -->
 !!! warning "Metadata providers are recommended"
@@ -31,16 +31,16 @@ Start from the reference file shipped in the repo. A known-good, minimally-edite
 
 You'll want to edit the following values before launching:
 
-| Where     | Variable                  | What to put                                                                                                            |
-| --------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `romm-db` | `MARIADB_ROOT_PASSWORD`   | A long, randomly generated password.                                                                                   |
-| `romm-db` | `MARIADB_PASSWORD`        | A separate long, randomly generated password.                                                                          |
-| `romm`    | `DB_PASSWD`               | Must match `MARIADB_PASSWORD` above.                                                                                   |
-| `romm`    | `ROMM_AUTH_SECRET_KEY`    | Generate with `openssl rand -hex 32` and keep it secret.                                                               |
-| `romm`    | Metadata provider creds   | Fill in only the providers you've registered with (see [Metadata Providers](../administration/metadata-providers.md)). |
-| `romm`    | `/path/to/library` volume | Host path to the directory containing your `roms/` folder.                                                             |
-| `romm`    | `/path/to/assets` volume  | Host storage paths for saves, states and screenshots.                                                                  |
-| `romm`    | `/path/to/config` volume  | Host path to a directory that will hold `config.yml`.                                                                  |
+| Where     | Variable                  | What to put                                                                                          |
+| --------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `romm-db` | `MARIADB_ROOT_PASSWORD`   | A long, randomly generated password.                                                                 |
+| `romm-db` | `MARIADB_PASSWORD`        | A separate long, randomly generated password.                                                        |
+| `romm`    | `DB_PASSWD`               | Must match `MARIADB_PASSWORD` above.                                                                 |
+| `romm`    | `ROMM_AUTH_SECRET_KEY`    | Generate with `openssl rand -hex 32` and keep it secret.                                             |
+| `romm`    | Metadata provider creds   | Fill in only the providers you've registered with (see [Metadata Providers](metadata-providers.md)). |
+| `romm`    | `/path/to/library` volume | Host path to the directory containing your `roms/` folder.                                           |
+| `romm`    | `/path/to/assets` volume  | Host storage paths for saves, states and screenshots.                                                |
+| `romm`    | `/path/to/config` volume  | Host path to a directory that will hold `config.yml`.                                                |
 
 Generate the auth secret now so you don't forget:
 

diff --git a/docs/install/index.md b/docs/install/index.md
@@ -30,6 +30,6 @@ Regardless of host platform, you'll make the same handful of decisions:
 
 ## After you're up and running
 
-- **Configure metadata providers**: [Metadata Providers](../administration/metadata-providers.md)
+- **Configure metadata providers**: [Metadata Providers](../getting-started/metadata-providers.md)
 - **Populate the library**: [Your First Scan](../getting-started/first-scan.md)
 - **Add users**: [Invitations & Registration](../administration/invitations-and-registration.md)
diff --git a/docs/install/synology.md b/docs/install/synology.md
@@ -64,7 +64,7 @@ Keep the output. It becomes `ROMM_AUTH_SECRET_KEY` in your compose file. Don't l
 
 ## 4. Set up metadata provider credentials
 
-Recommended before the first scan. Full walkthrough in [Metadata Providers](../administration/metadata-providers.md).
+Recommended before the first scan. Full walkthrough in [Metadata Providers](../getting-started/metadata-providers.md).
 
 ## 5. Docker Compose
 

diff --git a/docs/install/truenas.md b/docs/install/truenas.md
@@ -27,7 +27,7 @@ You'll be asked for the same set of env vars as [Quick Start](../getting-started
 
 - **Database credentials**: TrueNAS will offer to provision MariaDB for you, just pick a strong password.
 - **`ROMM_AUTH_SECRET_KEY`**: generate via `openssl rand -hex 32` on any Linux box and paste the output.
-- **Metadata provider credentials**: fill in whatever you've registered for (see [Metadata Providers](../administration/metadata-providers.md)).
+- **Metadata provider credentials**: fill in whatever you've registered for (see [Metadata Providers](../getting-started/metadata-providers.md)).
 - **Storage configurations**: point the **Library** and **Assets** volumes at datasets you control.
     - Make sure the UID/GID defined in the app config (default: `568`, the `apps` user) has ACL access to those datasets.
 

diff --git a/docs/platforms/index.md b/docs/platforms/index.md
@@ -11,5 +11,5 @@ description: Everything about the supported platforms
 ## Related sections
 
 - **[In-Browser Play](../using/in-browser-play/emulatorjs.md)**: the end-user side of EmulatorJS + Ruffle
-- **[Metadata Providers](../administration/metadata-providers.md)**
+- **[Metadata Providers](../getting-started/metadata-providers.md)**
 - **[Folder Structure](../getting-started/folder-structure.md)**
diff --git a/docs/platforms/supported-platforms.md b/docs/platforms/supported-platforms.md
@@ -21,7 +21,7 @@ Your folder name has to match the **platform slug** in the table. If yours diffe
 
 - **Slug**: the folder name RomM expects. Matches the IGDB platform slug where possible.
 - **Name**: the human-readable platform name
-- **Providers**: which metadata providers have at least partial coverage (see [Metadata Providers](../administration/metadata-providers.md)).
+- **Providers**: which metadata providers have at least partial coverage (see [Metadata Providers](../getting-started/metadata-providers.md)).
 - **EmulatorJS**: a playable in-browser core exists (see [Configuration File → `emulatorjs`](../reference/configuration-file.md#emulatorjs) for operator-level tuning).
 - **Firmware**: platform needs BIOS files for emulation (see [Firmware Management](../administration/firmware-management.md)).
 
@@ -46,6 +46,6 @@ uv run python -m scripts.gen_platforms
 
 - [Folder Structure](../getting-started/folder-structure.md): how platform slugs map to on-disk folders
 - [Custom Platforms](custom-platforms.md): adding platforms outside the built-in list
-- [Metadata Providers](../administration/metadata-providers.md): provider coverage deep-dive
+- [Metadata Providers](../getting-started/metadata-providers.md): provider coverage deep-dive
 - [In-Browser Play → EmulatorJS](../using/in-browser-play/emulatorjs.md): EmulatorJS core catalogue
 - [Firmware Management](../administration/firmware-management.md): how RomM stores and serves BIOS files
diff --git a/docs/reference/configuration-file.md b/docs/reference/configuration-file.md
@@ -194,7 +194,7 @@ Values are the provider slugs. Full list:
 | `tgdb`       | TheGamesDB            |
 | `libretro`   | Libretro metadata     |
 
-See [Metadata Providers](../administration/metadata-providers.md) for context on each.
+See [Metadata Providers](../getting-started/metadata-providers.md) for context on each.
 
 ### `scan.priority.artwork`
 
@@ -428,4 +428,4 @@ Most settings under `emulatorjs.settings` and `emulatorjs.controls` can be overr
 ## Related
 
 - [Folder Structure](../getting-started/folder-structure.md): how the filesystem shape interacts with `config.yml`
-- [Metadata Providers](../administration/metadata-providers.md): per-provider detail for the `scan.priority.*` slugs
+- [Metadata Providers](../getting-started/metadata-providers.md): per-provider detail for the `scan.priority.*` slugs
diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
@@ -51,7 +51,7 @@ You'll always set these:
 | `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASSWD` | Database connection                                                                             |
 | `ROMM_DB_DRIVER`                             | One of `mariadb` (default), `mysql`, or `postgresql` (see [Databases](../install/databases.md)) |
 
-For metadata providers (IGDB, ScreenScraper, etc.) see [Metadata Providers](../administration/metadata-providers.md), and for OIDC, see [OIDC Setup](../administration/oidc/index.md).
+For metadata providers (IGDB, ScreenScraper, etc.) see [Metadata Providers](../getting-started/metadata-providers.md), and for OIDC, see [OIDC Setup](../administration/oidc/index.md).
 
 ## Full reference
 

diff --git a/docs/reference/exports.md b/docs/reference/exports.md
@@ -71,7 +71,7 @@ Once `gamelist.xml` has been generated and populated `covers/` + `screenshots/`,
 - `MediaDirectory`: point it at the ROM folder (same path ES-DE uses for `ROMDirectory`), so ES-DE looks for media in-place rather than in its own library.
 - `LegacyGamelistFileLocation`: makes ES-DE write updates back to the same `gamelist.xml` read on import, rather than its separate config dir.
 
-See also [Metadata Providers → gamelist.xml](../administration/metadata-providers.md) for the _import_ direction (reading gamelist.xml back in).
+See also [Metadata Providers → gamelist.xml](../getting-started/metadata-providers.md) for the _import_ direction (reading gamelist.xml back in).
 
 ## Pegasus
 

diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -51,7 +51,7 @@ Every term the docs, UI, and API use consistently, with foundational concepts ge
 
 **Library**: your ROM files on disk. Mounted (usually read-only) at `/romm/library` inside the container, with platforms as subdirectories. The catalogue is built from what's found there (see [Folder Structure](../getting-started/folder-structure.md)).
 
-**Metadata provider**: external source of game data, queried during a scan, with results merged. Configured via env vars + priority in `config.yml` (see [Metadata Providers](../administration/metadata-providers.md)).
+**Metadata provider**: external source of game data, queried during a scan, with results merged. Configured via env vars + priority in `config.yml` (see [Metadata Providers](../getting-started/metadata-providers.md)).
 
 **Netplay**: EmulatorJS's multiplayer mode. Two or more players share a session across the internet. Open rooms are tracked and brokered via WebSocket. Needs STUN/TURN (ICE servers) configured in `config.yml` for reliable NAT traversal (see [Netplay](../using/netplay.md)).
 

diff --git a/docs/resources/snippets/quick-start.docker-compose.yml b/docs/resources/snippets/quick-start.docker-compose.yml
@@ -17,10 +17,10 @@ services:
             - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb
             - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`
             - SCREENSCRAPER_USER= # These are the recommended metadata providers
-            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#screenscraper
-            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#retroachievements
-            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#steamgriddb
-            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#hasheous
+            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/getting-started/metadata-providers/#screenscraper
+            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#retroachievements
+            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#steamgriddb
+            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/getting-started/metadata-providers/#hasheous
         volumes:
             - romm_resources:/romm/resources # Resources fetched from IGDB (covers, screenshots, etc.)
             - romm_redis_data:/redis-data # Cached data for background tasks

diff --git a/docs/resources/snippets/synology.docker-compose.yml b/docs/resources/snippets/synology.docker-compose.yml
@@ -15,10 +15,10 @@ services:
             - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb
             - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`
             - SCREENSCRAPER_USER= # These are the recommended metadata providers
-            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#screenscraper
-            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#retroachievements
-            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#steamgriddb
-            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#hasheous
+            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/getting-started/metadata-providers/#screenscraper
+            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#retroachievements
+            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#steamgriddb
+            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/getting-started/metadata-providers/#hasheous
         volumes:
             - /volume1/docker/romm/resources:/romm/resources
             - /volume1/docker/romm/redis-data:/redis-data

diff --git a/docs/resources/snippets/truenas.docker-compose.yml b/docs/resources/snippets/truenas.docker-compose.yml
@@ -17,10 +17,10 @@ services:
             - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb
             - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`
             - SCREENSCRAPER_USER= # These are the recommended metadata providers
-            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#screenscraper
-            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#retroachievements
-            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#steamgriddb
-            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/Getting-Started/Metadata-Providers/#hasheous
+            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/getting-started/metadata-providers/#screenscraper
+            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#retroachievements
+            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#steamgriddb
+            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/getting-started/metadata-providers/#hasheous
         volumes: # Any /mnt paths may optionally be replaced with a docker volume
             - /mnt/tank/truenas/resources:/romm/resources # Replace /mnt...: file path with your own data structure
             - romm_redis_data:/redis-data # Docker will manage this volume

diff --git a/docs/troubleshooting/kubernetes.md b/docs/troubleshooting/kubernetes.md
@@ -118,7 +118,7 @@ resources:
         memory: "4Gi"
 ```
 
-Or disable hashing on the Scan page to cut memory use by ~80% (you lose RetroAchievements + Hasheous matching, see [Metadata Providers](../administration/metadata-providers.md)).
+Or disable hashing on the Scan page to cut memory use by ~80% (you lose RetroAchievements + Hasheous matching, see [Metadata Providers](../getting-started/metadata-providers.md)).
 
 ## Still stuck?
 

diff --git a/docs/troubleshooting/scanning.md b/docs/troubleshooting/scanning.md
@@ -77,7 +77,7 @@ ERROR:    [RomM][scan_handler][2025-04-12 11:48:55]   Failed to process /romm/li
 Options, in order of effort:
 
 1. **Add more providers**: a ROM IGDB doesn't know about might be in ScreenScraper, Hasheous, or LaunchBox, so enable one or more, then run an **Unmatched** scan.
-2. **Use filename tags**: if you already know the provider ID, rename the file to include `(igdb-1234)` or similar (see [Metadata Providers → Filename tags](../administration/metadata-providers.md#metadata-tags-in-filenames)).
+2. **Use filename tags**: if you already know the provider ID, rename the file to include `(igdb-1234)` or similar (see [Metadata Providers → Filename tags](../getting-started/metadata-providers.md#metadata-tags-in-filenames)).
 3. **Manually match**: open the ROM detail page, click the **Match** button, and search for the right title.
 
 ## Hash calculations are slow

diff --git a/docs/using/in-browser-play/ruffle.md b/docs/using/in-browser-play/ruffle.md
@@ -19,6 +19,6 @@ Most 2D Flash games work, but 3D Shockwave and some advanced ActionScript titles
 
 ## Metadata
 
-If you enable the [Flashpoint](../../administration/metadata-providers.md#flashpoint) provider, Ruffle games pick up descriptions, cover art, and tags from the Flashpoint database.
+If you enable the [Flashpoint](../../getting-started/metadata-providers.md#flashpoint) provider, Ruffle games pick up descriptions, cover art, and tags from the Flashpoint database.
 
 More troubleshooting in [In-Browser Play Troubleshooting](../../troubleshooting/in-browser-play.md).