Document how to override templates

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Running locally
+Start local site with:
+
+```shell
+wp-env start
+```
+
+Change permalink structure:
+
+```shell
+wp-env run cli "wp rewrite structure '/%postname%'"
+```
+
+The site is now available at http://localhost:8888.

README.md

@@ -65,17 +65,47 @@ function oidc_clients() {
 }
 ```
 
-## Development
-Start local site with:
+## Overriding templates
+The pages provided by this plugin are rendered using templates. If you so wish, you can use your own templates instead of this plugins's [default templates](templates).
+
+To do so, you should create an `openid-connect/` directory under your theme, containing only the templates you wish to override. For example, if you wanted to override `authenticate/main.php` and `authenticate/forbidden.php` you would create them under an `openid-connect/` directory in your theme:
 
 ```shell
-wp-env start
+wp-content/themes/my-theme/
+ │── openid-connect/
+ │──── main.php
+ └──── forbidden.php
 ```
 
-Change permalink structure:
+If your theme is a child theme, this plugin will first look for templates under the child theme, and then in the parent theme. If it doesn't find a template, it will fall back to using the default template.
 
-```shell
-wp-env run cli "wp rewrite structure '/%postname%'"
+### Data
+Templates are passed a single `$data` variable containing the values necessary to render said template. For example, you can access the name of the OIDC client as follows:
+
+```php
+// wp-content/themes/my-theme/main.php
+
+/** @var stdClass $data **/
+
+/** @var string $client_name The OIDC client name */
+$client_name = $data->client_name;
+```
+
+You can of course also call any other WordPress function, like you would in any other file in your theme.
+
+### Partials
+In your templates, you can include partial templates (aka partials) by calling `$data->templates->partial()`:
+
+```php
+// wp-content/themes/my-theme/main.php
+
+/** @var stdClass $data **/
+
+/** @var \OpenIDConnectServer\Templating\Templating $templates */
+$templates = $data->templates;
+
+// Renders the <form> in the 'authenticate/form.php' partial.
+$templates->partial( 'authenticate/form' )
 ```
 
-The site is now available at http://localhost:8888.
+Partials are also passed the `$data` variable.