docs: add table description explaining the filters

Author: nstapelbroek

README.md

@@ -1,11 +1,29 @@
-[![Docker Pulls](https://img.shields.io/docker/pulls/nstapelbroek/static-webserver.svg?style=flat-square)](https://hub.docker.com/r/nstapelbroek/static-webserver/tags/)
-
 # Docker static webserver
 
+<!-- MANPAGE: BEGIN EXCLUDED SECTION -->
+<div align="center">
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/nstapelbroek/static-webserver.svg?style=for-the-badge)](https://hub.docker.com/r/nstapelbroek/static-webserver/tags/)
+![Docker Image Size (tag)](https://img.shields.io/docker/image-size/nstapelbroek/static-webserver/latest?style=for-the-badge)
+![Docker Image Version](https://img.shields.io/docker/v/nstapelbroek/static-webserver.svg?style=for-the-badge)
+
+</div>
+
 A simple nginx docker image that has the ability to insert environment variables. Created so I could re-use an image between prod and staging environments for my frontend builds.
 It replaces environment variables on container startup, so you don´t have to rebuild your Docker image or use a server-side language to change some settings.
 
-## Getting Started
+<!-- MANPAGE: BEGIN EXCLUDED SECTION -->
+* [Usage](#usage)
+    * [Dockerfile example](#dockerfile-example)
+    * [Using environment variables](#using-environment-variables)
+    * [Envsubst filters](#envsubst-filters)
+    * [Mounting volumes](#mounting-volumes)
+    * [Versioning](#versioning)
+* [License](#license)
+* [Acknowledgments](#acknowledgments)
+
+<!-- MANPAGE: END EXCLUDED SECTION -->
+## Dockerfile example
 
 This repository generates the images available on the [Docker hub](https://hub.docker.com/r/nstapelbroek/static-webserver/tags).
 Using this image for your own project is as simple as creating a Dockerfile with the two lines below:
@@ -31,9 +49,9 @@ FROM nstapelbroek/static-webserver:4
 COPY --from=build --chown=nginx:nginx /opt/project/dist /var/www
 ```
 
-### Using environment variables
+## Using environment variables
 
-When this container starts, a script will replace all occurrences of ${%variableName%} in `/var/www` with
+When this container starts, a script will replace all occurrences of ${VARIABLE_NAME} in `/var/www` with
 their matching environment variable. 
 
 For example, given this HTML in a file located at `/var/www/index.html`
@@ -47,25 +65,37 @@ And building & running this with an environment variable passed in docker run (`
 
 ![result](https://user-images.githubusercontent.com/3368018/27512102-48ae27aa-5936-11e7-824a-92ca12d5334f.png)
 
-### What tag should I use?
+Note: Please make sure your environment keys do not contain special characters. Only `a-z`, `A-Z`, `0-9` and `_` are recommended.
+
+## Envsubst filters
+By default, the script only changes files located in `/var/www`. You can change this by setting the `NGINX_ENVSUBST_WWW_DIR` environment variable.
+Using es6 template literals can cause issues. You can fine-tune the replacement by configuring a filter with the `NGINX_ENVSUBST_FILTER` environment variable. This should allow you to set a prefix like `CONFIG_`.
+Here's a table that should help you understand the behavior:
+
+text value in file | passed environment variable | passed nginx filter | result | why
+--- | --- | --- | --- | --- 
+`$MY_PROJECT_URL` | `MY_PROJECT_URL=123` | `PROJECT` | `123` | the passed filter matches we have an environment variable to replace
+`${MY_PROJECT_URL}` | `MY_PROJECT_URL=123` | `PROJECT` | `123` | the passed filter matches and we have an environment variable to replace
+\`${MY_PROJECT_URL}\` | `MY_PROJECT_URL=123` | `PROJECT` | \`123\` | the passed filter matches we have an environment variable to replace
+`MY_PROJECT_URL` | `MY_PROJECT_URL=123` | `PROJECT` | `MY_PROJECT_URL` | this is not a valid form [for envsubst ](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html)
+`$MY_PROJECT_URL` | `YOUR_PROJECT_URL=123` | `PROJECT` | `MY_PROJECT_URL` | the filter matches, but we have no environment variable to replace
+`$MY_PROJECT_URL` | `MY_PROJECT_URL=123` | `PUBLIC_` | `MY_PROJECT_URL` | the variable does match the allowed filter
+
+
+## Mounting volumes
+The project is not meant as a development environment. Don´t mount your code in here as it will only change environment variables on the first container startup.
+
+## Versioning
 
 To prevent sudden BC-breaks you should avoid using the `latest` tag when building upon this image (or any image for that reason).
-I'm using [Semver](https://semver.org/) as a base for versioning schematics. Due to the small functionality of this container I'm considering the following changes as "incompatible API changes": 
+I'm using [Semver](https://semver.org/) as a base for versioning schematics. Due to the small functionality of this container I'm considering the following changes as "incompatible API changes":
 
 - Altered behavior at clients, for example due to changes in cache-headers
 - Altered behavior in the find & replace script
 - Altered behavior in the file locations
 
 You should use the latest available tag in [at in the registry](https://hub.docker.com/r/nstapelbroek/static-webserver/tags/).
 
-## Known limitations
-
-Due to the simple approach of finding & replacing the keywords there are some limitations:
-- Please make sure your environment keys do not contain special characters. Only `a-z`, `A-Z`, `0-9` and `_` are recommended.
-- By default, the script only changes files located in `/var/www`. You can change this by setting the `NGINX_ENVSUBST_WWW_DIR` environment variable.
-- Using es6 template literals can cause issues. You can fine-tune the replacement by configuring a filter with the `NGINX_ENVSUBST_FILTER` environment variable. This should allow you to set a prefix like `CONFIG_`.
-- The project is not meant as a development environment. Don´t mount your code in here as it will only change environment variables on the first startup.
-
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details