From 125cc7a8843af522019126f82bc71bfba2b07ee0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Sch=C3=B6ldstr=C3=B6m?= <public@oxy.fi>
Date: Sat, 22 Apr 2017 17:10:05 -0500
Subject: [PATCH] Add template inheritance docs [ci skip]

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/README.md b/README.md
index d76df5b..6d46b94 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,58 @@ Configures Nginx's [`log_format`](http://nginx.org/en/docs/http/ngx_http_log_mod
 
 (For RedHat/CentOS only) Set this to `false` to disable the installation of the `nginx` yum repository. This could be necessary if you want the default OS stable packages, or if you use Satellite.
 
+## Overriding configuration templates
+
+If you can't customize via variables because an option isn't exposed, you can override the template used to generate the virtualhost configuration files or the `nginx.conf` file.
+
+```yaml
+nginx_conf_template: "nginx.conf.j2"
+nginx_vhost_template: "vhost.j2"
+```
+
+You can either copy and modify the provided template, or extend it with [Jinja2 template inheritance](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance) and override the specific template block you need to change.
+
+### Example: Configure gzip in nginx configuration
+
+Set the `nginx_conf_template` to point to a template file in your playbook directory.
+
+```yaml
+nginx_conf_template: "{{ playbook_dir }}/templates/nginx.conf.j2"
+```
+
+Create the child template in the path you configured above and extend `geerlingguy.nginx` template file relative to your `playbook.yml`.
+
+```
+{% extends 'roles/geerlingguy.nginx/templates/nginx.conf.j2' %}
+
+{% block http_gzip %}
+    gzip on;
+    gzip_proxied any;
+    gzip_static on;
+    gzip_http_version 1.0;
+    gzip_disable "MSIE [1-6]\.";
+    gzip_vary on;
+    gzip_comp_level 6;
+    gzip_types
+        text/plain
+        text/css
+        text/xml
+        text/javascript
+        application/javascript
+        application/x-javascript
+        application/json
+        application/xml
+        application/xml+rss
+        application/xhtml+xml
+        application/x-font-ttf
+        application/x-font-opentype
+        image/svg+xml
+        image/x-icon;
+    gzip_buffers 16 8k;
+    gzip_min_length 512;
+{% endblock %}
+```
+
 ## Dependencies
 
 None.