remote/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2026-06-24 17:54:35 +02:00
Code Issues Projects Releases Packages Wiki Activity

Improve docs structure for static(), refs #2804, #2800

Browse source
This commit is contained in:
Simon Willison 2026-06-23 13:59:01 -07:00
commit 39f1df5997
1 changed files with 48 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

91
docs/custom_templates.rst
View file

@ -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
~~~~~~~~~~~~~~~~~~~~~~~~