From 39f1df59975f57ba011f13a181c1ca801f3296a8 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Tue, 23 Jun 2026 13:59:01 -0700
Subject: [PATCH] Improve docs structure for static(), refs #2804, #2800

---
 docs/custom_templates.rst | 91 +++++++++++++++++++++------------------
 1 file changed, 48 insertions(+), 43 deletions(-)

diff --git a/docs/custom_templates.rst b/docs/custom_templates.rst
index bfbd1725..50c23b3e 100644
--- a/docs/custom_templates.rst
+++ b/docs/custom_templates.rst
@@ -94,11 +94,55 @@ The ``core`` class is particularly useful - you can apply this directly to a ``<
 
 .. _customization_static_files:
 
-Serving static files
-~~~~~~~~~~~~~~~~~~~~
+Linking to static assets
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Datasette can serve static files for you, using the ``--static`` option.
-Consider the following directory structure::
+Use the ``static()`` template function to create cache-busting URLs to static
+assets from your custom templates. It returns a URL with a ``?_hash=`` parameter
+based on the file contents and takes the ``base_url`` setting into account.
+
+When the hash in the URL matches the current file contents, Datasette will serve
+the static asset with a far-future immutable ``Cache-Control`` header.
+
+When Datasette is run using ``--reload``, the file contents are hashed every time
+the template is rendered, so edits to static files will update their URLs
+without restarting Datasette. Without ``--reload``, the hash is cached for the
+lifetime of the Datasette process.
+
+For Datasette's bundled static assets, pass the path to the asset:
+
+.. code-block:: html+jinja
+
+    <link rel="stylesheet" href="{{ static('app.css') }}">
+
+For plugin static assets, pass the plugin name using ``plugin=`` and a path
+relative to the plugin's ``static/`` directory:
+
+.. code-block:: html+jinja
+
+    <script src="{{ static('plugin.js', plugin='datasette_plugin_name') }}" defer></script>
+
+For files served from a directory mounted using ``--static assets:static-files/``,
+pass the mount point name using ``mount=`` and a path relative to that mounted
+directory:
+
+.. code-block:: html+jinja
+
+    <link rel="stylesheet" href="{{ static('styles.css', mount='assets') }}">
+    <script src="{{ static('app.js', mount='assets') }}" defer></script>
+
+You can also use ``urls.path()`` if you want to link to a mounted file without
+adding a content hash:
+
+.. code-block:: html+jinja
+
+    <link rel="stylesheet" href="{{ urls.path('/assets/styles.css') }}">
+
+Serving files from a directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Datasette can serve static files from a directory for you, using the ``--static``
+option. Consider the following directory structure::
 
     metadata.json
     static-files/styles.css
@@ -151,45 +195,6 @@ You can reference those files from ``datasette.yaml`` like this, see :ref:`custo
         }
 .. [[[end]]]
 
-If you reference those files from a custom template, use the ``static()``
-template function to create a cache-busting URL based on the file contents.
-Pass the mount point as the ``mount=`` argument, and pass a path relative to
-that mounted directory:
-
-.. code-block:: html+jinja
-
-    <link rel="stylesheet" href="{{ static('styles.css', mount='assets') }}">
-    <script src="{{ static('app.js', mount='assets') }}" defer></script>
-
-The returned URL will include a ``?_hash=`` parameter and will take the
-``base_url`` setting into account. When that hash matches the current file
-contents, Datasette will serve the static asset with a far-future immutable
-``Cache-Control`` header. You can also use ``urls.path()`` if you want to link
-to the mounted file without adding a content hash:
-
-.. code-block:: html+jinja
-
-    <link rel="stylesheet" href="{{ urls.path('/assets/styles.css') }}">
-
-When Datasette is run using ``--reload``, the file contents are hashed every time
-the template is rendered, so edits to static files will update their URLs
-without restarting Datasette. Without ``--reload``, the hash is cached for the
-lifetime of the Datasette process.
-
-You can use the same function for Datasette's bundled static assets, omitting
-``mount=``:
-
-.. code-block:: html+jinja
-
-    <link rel="stylesheet" href="{{ static('app.css') }}">
-
-For plugin static assets, pass the plugin name using ``plugin=`` and a path
-relative to the plugin's ``static/`` directory:
-
-.. code-block:: html+jinja
-
-    <script src="{{ static('plugin.js', plugin='datasette_plugin_name') }}" defer></script>
-
 Publishing static assets
 ~~~~~~~~~~~~~~~~~~~~~~~~