--- a/docker/README.md	Thu Feb 07 12:23:05 2019 +0100
+++ b/docker/README.md	Thu Feb 07 13:45:43 2019 +0100
@@ -1,5 +1,13 @@
 # Setup dev environment using Docker
 
+- [Setup dev environment using Docker](#setup-dev-environment-using-docker)
+  - [Network setup](#network-setup)
+  - [Database setup](#database-setup)
+  - [Create ER diagrams](#create-er-diagrams)
+  - [GeoServer setup](#geoserver-setup)
+  - [Gemma backend setup](#gemma-backend-setup)
+  - [SPA setup](#spa-setup)
+
 Run the `build` commands from the root of your checkout, because it is
 assumed as the context!
 
@@ -8,87 +16,104 @@
 
 ## Network setup
 
-- Create a network to connect containers:
-  ```
-  docker network create gemma
-  ```
+Create a network to connect containers:
+
+```shell
+docker network create gemma
+```
 
 ## Database setup
 
-- Build Dockerfile with e.g.:
-  ```
-  docker build -t gemma_db -f docker/Dockerfile.db .
-  ```
+Build `gemma_db` docker image with e.g.:
+
+```shell
+docker build -t gemma_db -f docker/Dockerfile.db .
+```
+
+Get a running instance with e.g.:
 
-- Get a running instance with e.g.:
-  ```
-  docker run --name gemma_db -d -p 54321:5432 -v $PWD/schema:/opt/gemma \
-          --network gemma gemma_db
-  ```
-  Use `--network-alias gemma_db` if your container has a different name
+```shell
+docker run --name gemma_db -d -p 54321:5432 -v $PWD/schema:/opt/gemma \
+           --network gemma gemma_db
+```
+
+Use `--network-alias gemma_db` if your container has a different name
 
-- Run tests for RLS policies:
-  ```
-  docker exec gemma_db ./run_tests.sh
-  ```
+Run tests for [Row-Level Security](https://www.postgresql.org/docs/11/ddl-rowsecurity.html) (RLS)
+policies:
+
+```shell
+docker exec gemma_db ./run_tests.sh
+```
 
 ## Create ER diagrams
 
-Assuming you have installed `postgresql_autodoc` and `graphviz` on a machine
-from wich you can reach your docker host, you can use the following:
+Assuming you have installed `postgresql-autodoc` and
+[graphviz](http://graphviz.org/) on a machine from which you can reach your
+docker host, you can use the following:
+
+ER diagram with waterway related tables:
 
-- ER diagram with waterway related tables:
-  ```
-  postgresql_autodoc -p 54321 -h $dockerhost \
-      -d gemma -U sophie --password=so2Phie4 -t dot -l . -s 'waterway'
-  dot -Tpdf gemma.dot > gemma_waterway.pdf
-  ```
+```shell
+postgresql_autodoc -p 54321 -h $dockerhost \
+                   -d gemma -U sophie --password=so2Phie4 \
+                   -t dot -l . -s 'waterway'
+dot -Tpdf gemma.dot > gemma_waterway.pdf
+```
 
 Omit the `-s` option to get a diagram with all tables or use any other
 schema name to see other parts of the whole picture.
 
 ## GeoServer setup
 
-- Build Dockerfile with e.g.:
-  ```
-  docker build -t gemma_geoserver -f docker/Dockerfile.geoserv .
-  ```
+Build `gemma_geoserver` docker image with e.g.:
+
+```shell
+docker build -t gemma_geoserver -f docker/Dockerfile.geoserv .
+```
+
+Get a running instance with e.g.:
 
-- Get a running instance with e.g.:
-  ```
-  docker run --name gemma_geoserver -d -p 8280:8080 --network gemma \
-         gemma_geoserver
-  ```
-  Use `--network-alias gemma_geoserver` if you give your container
-  a different name.
+```shell
+docker run --name gemma_geoserver -d -p 8280:8080 --network gemma \
+           gemma_geoserver
+```
+
+Use `--network-alias gemma_geoserver` if you give your container
+a different name.
 
 ## Gemma backend setup
 
-- Build Dockerfile with e.g.:
-  ```
-  docker build -t gemma_backend -f docker/Dockerfile.backend .
-  ```
+Build `gemma_backend` docker image with e.g.:
+
+```shell
+docker build -t gemma_backend -f docker/Dockerfile.backend .
+```
+
+Get a running instance with e.g.:
 
-- Get a running instance with e.g.:
-  ```
-  docker run --name gemma_backend -v $PWD:/opt/gemma -d -p 8200:8000 \
-             --network gemma gemma_backend
-  ```
-  Use `--network-alias gemma_backend` if you give your container
-  a different name.
+```shell
+docker run --name gemma_backend -v $PWD:/opt/gemma -d -p 8200:8000 \
+           --network gemma gemma_backend
+```
+
+Use `--network-alias gemma_backend` if you give your container
+a different name.
 
 ## SPA setup
 
-- Build Dockerfile with e.g.:
-  ```
-  docker build -t gemma_spa -f docker/Dockerfile.spa .
-  ```
+Build `gemma_spa` docker image with e.g.:
+
+```shell
+docker build -t gemma_spa -f docker/Dockerfile.spa .
+```
 
-- Get a running instance with e.g.:
-  ```
-  docker run --name gemma_spa -v $PWD/client:/opt/gemma/client -d -p 8290:8080 \
-             --network gemma gemma_spa
-  ```
+Get a running instance with e.g.:
+
+```shell
+docker run --name gemma_spa -v $PWD/client:/opt/gemma/client -d -p 8290:8080 \
+           --network gemma gemma_spa
+```
 
 Now you should be able to use the application in your browser by going to
-`http://HOST:8290`, with HOST being the hostname of your docker host.
+`http://HOSTNAME:8290`, with `HOSTNAME` being the hostname of your docker host.