rustprooflabs · rustprooflabs · Feb 24, 2023 · Feb 24, 2023
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -18,9 +18,8 @@
 
 # Production usages
 
-
-- [Using External Postgres Connection](./postgres-external.md)
 - [Postgres Permissions](./postgres-permissions.md)
+- [Using External Postgres Connection](./postgres-external.md)
 - [Stay Updated with Replication](./replication.md)
 - [Using Update Mode](./update-mode.md)
 - [QGIS Styles](./qgis-styles.md)

diff --git a/docs/src/common-customization.md b/docs/src/common-customization.md
@@ -107,7 +107,7 @@ Calculating nested place polygons for Colorado adds less than 30 seconds on an 8
 taking about 5% longer.
 A larger region, such as North America, can take 33% longer adding more than
 an hour and a half to the total processing time.
-See [docs/PERFORMANCE.md](PERFORMANCE.md) for more details.
+See the [performance section](performance.md) for more details.
 
 
 Use `--skip-nested` to bypass the calculation of nested admin polygons.
@@ -135,7 +135,7 @@ psql -d myosm \
     -f ~/pgosm-data/pgosm-flex-north-america-us-district-of-columbia-default-2023-01-21.sql
 ```
 
-> The above assumes a database user with `superuser` permissions is used. See [docs/POSTGRES-PERMISSIONS.md](POSTGRES-PERMISSIONS.md) for a more granular approach to permissions.
+> The above assumes a database user with `superuser` permissions is used. See the [Postgres Permissions](postgres-permissions.md) section for a more granular approach to permissions.
 
 
 

diff --git a/docs/src/customizations.md b/docs/src/customizations.md
@@ -1,6 +1,6 @@
 # Customize PgOSM Flex
 
 
-- [Common Customizations](./COMMON-CUSTOMIZATION.md)
-- [Layersets](./LAYERSETS.md)
-- [Configure Postgres](./CONFIGURE-POSTGRES.md)
+- [Common Customizations](./common-customization.md)
+- [Layersets](./layersets.md)
+- [Configure Postgres](./configure-postgres.md)
diff --git a/docs/src/postgres-external.md b/docs/src/postgres-external.md
@@ -1,11 +1,9 @@
 # Using External Postgres Connection
 
 
-The PgOSM Flex Docker image can be used with Postgres instance outside the
-Docker container.
 
 Prepare the database and permissions as described in
-[Postgres Permissions](POSTGRES-PERMISSIONS.md).
+[Postgres Permissions](postgres-permissions.md).
 
 
 Set environment variables to define the connection.  Create a file with the

diff --git a/docs/src/postgres-permissions.md b/docs/src/postgres-permissions.md
@@ -1,8 +1,18 @@
 # Postgres permissions for PgOSM Flex
 
-These instructions show an example of setting up a Postgres database
-for use with PgOSM Flex as an external database connection
-described in [DOCKER-RUN.md](DOCKER-RUN.md).
+The [quick start](quick-start.md) section showed how to get up and
+running using the Postgres instance within the PgOSM Flex docker image.
+Many production usage cases of PgOSM Flex prefer to connect the
+PgOSM Flex processing within Docker directly to an already running
+Postgres instances.
+
+
+The first step to using PgOSM Flex with your own Postgres instance
+is to have a database already created, and a login role with
+proper permissions.
+The steps in this page prepare for the steps outlined
+in the [Using External Postgres Connection](postgres-external.md)
+section.
 
 ## Create database and PostGIS
 
@@ -17,14 +27,17 @@ In the target Postgres instance, create your database.
 CREATE DATABASE your_db_name;
 ```
 
-In `your_db_name` create the PostGIS extension.
+Connect to `your_db_name` and create the PostGIS extension.
+This is done along with the `CREATE DATABASE` since both steps
+require the superuser role. 
 
 
 ```sql
 CREATE EXTENSION postgis;
 ```
 
 
+
 ## Runtime permissions
 
 Your target database needs to have an `osm` schema and the database user

diff --git a/docs/src/query.md b/docs/src/query.md
@@ -111,7 +111,8 @@ The topic of POIs is subject and likely is not inclusive of everything that prob
 a POI. If there are POIs missing
 from this table please submit a [new issue](https://github.com/rustprooflabs/pgosm-flex/issues/new)
 with sufficient details about what is missing.
-Pull requests also welcome! [See CONTRIBUTING.md](CONTRIBUTING.md).
+Pull requests also welcome! See [the contributing section](contributing.md)
+for more information.
 
 
 Counts of POIs by `osm_type`.

diff --git a/docs/src/quick-start.md b/docs/src/quick-start.md
@@ -47,7 +47,6 @@ logic, an post-processing steps required.  Features include:
 ## Docker usage
 
 This section outlines a typical import using Docker to run PgOSM Flex.
-See the full Docker instructions in [docs/DOCKER-RUN.md](docs/DOCKER-RUN.md).
 
 Create directory for the `.osm.pbf` file, output `.sql` file, log output, and
 the osm2pgsql command ran.

diff --git a/docs/src/readme.md b/docs/src/readme.md
@@ -10,9 +10,9 @@ Running PgOSM Flex is easy via the PgOSM Docker image
 [hosted on Docker Hub](https://hub.docker.com/repository/docker/rustprooflabs/pgosm-flex).
 
 
-1. The [quick start](QUICK-START.md) shows how easy it is to get started
-1. Change how PgOSM Flex runs with [common customizations](COMMON-CUSTOMIZATION.md)
-1. [Customize layersets](LAYERSETS.md) to change what data you load
+1. The [quick start](quick-start.md) shows how easy it is to get started
+1. Change how PgOSM Flex runs with [common customizations](common-customization.md)
+1. [Customize layersets](layersets.md) to change what data you load
 
 
 ## Project goals

diff --git a/docs/src/routing.md b/docs/src/routing.md
@@ -3,9 +3,6 @@
 This page provides a simple example of using OpenStreetMap roads
 loaded with PgOSM Flex for routing.
 The example uses the D.C. PBF included under `tests/data/`.
-See [MANUAL-STEPS-RUN.md](MANUAL-STEPS-RUN.md) for more details
-on running PgOSM Flex w/out Docker.
-
 
 ```bash
 cd ~/pgosm-data