diff --git a/docs/simplesamlphp-theming.md b/docs/simplesamlphp-theming.md
index fd7b0fa8a851c9cd1a59398f5577829cab737270..7d0ea7310c5f47e2c31f9009dfa96a15c79f9b89 100644
--- a/docs/simplesamlphp-theming.md
+++ b/docs/simplesamlphp-theming.md
@@ -114,3 +114,22 @@ Example for a custom CSS stylesheet file:
 ```html
 <link rel="stylesheet" type="text/css" href="<?php echo SimpleSAML\Module::getModuleURL('mymodule/style.css'); ?>" />
 ```
+
+Migrating to Twig templates
+---------------------------
+
+In version 1.15, a new templating system based on [Twig](https://twig.symfony.com/) was introduced. As modules migrate, it will become necessary for themes to include both the old templating style described above and new Twig-based templates.
+
+Twig works by extending a base template, which can itself include other partial templates. Some of the content of the old `includes/header.php` template is now located in a separate `_header.twig` file. This can be customized by copying it from the base template:
+
+	cp templates/_header.twig modules/mymodule/themes/fancytheme/default/
+
+If you need to make more extensive customizations to the base template, you should copy it from the base theme:
+
+	cp templates/base.twig modules/mymodule/themes/fancytheme/default/
+
+Any references to `$this->data['baseurlpath']` in old-style templates can be replaced with `{{baseurlpath}}` in Twig templates. Likewise, references to `SimpleSAML_Module::getModuleURL()` can be replaced with `{{baseurlpath}}module.php/mymodule/...`
+
+See the [Twig documentation](https://twig.symfony.com/doc/1.x/templates.html) for more information on using variables and expressions in Twig templates, and the SimpleSAMLphp wiki for [our conventions](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig-conventions).
+
+The wiki also includes some information on [migrating translations](https://github.com/simplesamlphp/simplesamlphp/wiki/Migrating-translation-in-Twig) and [migrating templates](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig:-Migrating-templates).
diff --git a/docs/simplesamlphp-upgrade-notes-1.15.md b/docs/simplesamlphp-upgrade-notes-1.15.md
index 19523af595a2397051f980bc29990f2fdcecba0d..a4ffd2483d3c320b80ac1e00607b8c154b033cda 100644
--- a/docs/simplesamlphp-upgrade-notes-1.15.md
+++ b/docs/simplesamlphp-upgrade-notes-1.15.md
@@ -5,7 +5,9 @@ The minimum required PHP version is now 5.4. The dependency on mcrypt has been
 dropped.
 
 A new templating system based on Twig has been introduced. The old templating
-system is still available but should be considered deprecated.
+system is still available but should be considered deprecated. Custom themes
+may need to be updated to include Twig-style templates as well. See the
+[theming documentation](simplesamlphp-theming).
 
 A new internationalization system based on Gettext has been introduced. While
 old templates can use either the old or the new system (refer to the