diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst index 3b7364aeaa..4cd8317c17 100644 --- a/docs/plugin_hooks.rst +++ b/docs/plugin_hooks.rst @@ -1136,13 +1136,36 @@ jinja2_environment_from_request(datasette, request, env) ``datasette`` - :ref:`internals_datasette` A Datasette instance. -``request`` - :ref:`internals_request` - The current HTTP request. +``request`` - :ref:`internals_request` or ``None`` + The current HTTP request, if one is available. -``env`` - `Environment` +``env`` - ``Environment`` The Jinja2 environment that will be used to render the current page. -... use overlays here +This hook can be used to return a customized `Jinja environment `__ based on the incoming request. + +If you want to run a single Datasette instance that serves different content for different domains, you can do so like this: + +.. code-block:: python + + from datasette import hookimpl + from jinja2 import ChoiceLoader, FileSystemLoader + + @hookimpl + def jinja2_environment_from_request(request, env): + if request and request.host == "www.niche-museums.com": + return env.overlay( + loader=ChoiceLoader( + [ + FileSystemLoader("/mnt/niche-museums/templates"), + env.loader, + ] + ), + enable_async=True, + ) + return env + +This uses the Jinja `overlay() method `__ to create a new environment identical to the default environment except for having a different template loader, which first looks in the ``/mnt/niche-museums/templates`` directory before falling back on the default loader. .. _plugin_hook_filters_from_request: