From e3ff63b0f93303a8dfe23d8d2d84bbc9551c3eea Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Tue, 23 Jun 2026 12:46:15 -0700
Subject: [PATCH] Warn plugin authors to avoid name conflicts with
 extra_template_vars

Closes #1988
---
 docs/plugin_hooks.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst
index d2f87e27..66419ec4 100644
--- a/docs/plugin_hooks.rst
+++ b/docs/plugin_hooks.rst
@@ -230,6 +230,10 @@ Function that returns an awaitable function that returns a dictionary
 
 Datasette runs Jinja2 in `async mode <https://jinja.palletsprojects.com/en/2.10.x/api/#async-support>`__, which means you can add awaitable functions to the template scope and they will be automatically awaited when they are rendered by the template.
 
+.. warning::
+
+   Be careful not to accidentally define a variable that conflicts with one that Datasette is already using for something else. Check :ref:`the template context documentation <template_context>` to see the variables defined by Datasette core.
+
 Here's an example plugin that adds a ``"user_agent"`` variable to the template context containing the current request's User-Agent header:
 
 .. code-block:: python