Document theme assets manifest

docs/creating-theme.md

@@ -140,11 +140,17 @@ To extend a template and change some details, just extend the base template and
 ```html+jinja
 {% extends "raw.html" %}
 
+{% block theme_css %}
+{{ super() }}
+<link href="{{ theme_static('theme.css') }}" rel="stylesheet">
+{% endblock %}
+
 {% block raw_head %}
 {{ super() }}
 <link rel="shortcut icon" href="{{ theme_static('img/favicon.png') }}">
 {% endblock %}
 ```
+
 You can reference static assets from your theme with the `theme_static` global function.
 
 !!! note
@@ -154,6 +160,46 @@ You can reference static assets from your theme with the `theme_static` global f
 You can also rewrite entirely the template, but don't forget you need to have the proper blocks
 for template inheritance and use the proper context variables.
 
+## Assets manifest
+
+Theme can optionnaly provide an asset manifest for long-term caching.
+The manifest is simply a JSON file mapping human-readable names (ie. `theme.css`) to their real path (ie. `/_theme/my-theme/theme.83c45954dd3da90126b5f13d10b547b5.css`).
+
+The theme assets manifest need to be named `manifest.json` at the theme root directory (sibling `info.json`).
+If present, `udata` will automatically detect it and allows you to use the `manifest` jinja global helper and the `in_manifest` jinja test.
+
+```html+jinja
+{% extends "raw.html" %}
+
+{% block theme_css %}
+{{ super() }}
+<link href="{{ manifest('theme', 'theme.css') }}" rel="stylesheet">
+{# Only render tag if asset is present in the manifest #}
+{% if 'my.css' is in_manifest('theme') %}
+<link href="{{ manifest('theme', 'my.css') }}" rel="stylesheet">
+{% endif %}
+{% endblock %}
+```
+
+!!! note
+    The theme manifest is registered with the `theme` key.<br/>
+    You need to use `manfest('theme', <filename>)` and `in_manifest('theme')`
+
+Here a sample theme manifest:
+
+```json
+{
+  "admin.css": "/_themes/gouvfr/admin.10cd3b26d19962df0e6b78cbdcadfe88.css",
+  "admin.js": "/_themes/gouvfr/admin.97515dac30750ec5d315.js",
+  "img/favicon.png": "/_themes/gouvfr/img/favicon.png",
+  "...": "",
+  "oembed.css": "/_themes/gouvfr/oembed.66142920652697e6e1717060154fe3a2.css",
+  "oembed.js": "/_themes/gouvfr/oembed.97515dac30750ec5d315.js",
+  "theme.css": "/_themes/gouvfr/theme.d9adbf77694f2b00063ddc34b61bf8fe.css",
+  "theme.js": "/_themes/gouvfr/theme.97515dac30750ec5d315.js"
+}
+```
+
 ## Hooks
 
 Your theme can also customize some behavior by using hooks in your ``__init__.py``.