From 77770c35eff72b5ad405ac5bfb3c73d8b597491c Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 4 Dec 2024 05:44:07 -0800
Subject: [PATCH] Merge content from #1803

---
 docs/classic-ui/static-resources.md | 65 ++++++++++++++++++-----------
 1 file changed, 40 insertions(+), 25 deletions(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 002c307eb..ccfa9f24f 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -12,7 +12,11 @@ myst:
 # Static resources
 
 We often want to ship a website with a static resource, such as an image, icon, CSS, or JavaScript file.
-For this, we need to register static resources.
+For CSS and JavaScript files, we can use the resource registry to register, then deliver, them to the client browser.
+
+The resource registry provides a programmatic way, either in code or through the web, to extend and configure the dependencies between static resources.
+It also automatically manages caching of static resources.
+If you were to hard-code these resources in templates with `<link>` or `<script>` tags, you would not have these advantages.
 
 ```{seealso}
 For some additional implementation information, see {ref}`classic-ui-theming-from-scratch-theme-label`.
@@ -33,7 +37,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/jscript">
     <value key="enabled">True</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -41,7 +45,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
 ```
 
 You can register a CSS resource in the same way.
-  
+
 ```xml
     <registry>
     <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
@@ -54,13 +58,13 @@ You can register a CSS resource in the same way.
 
 You can also register a JavaScript file and a CSS file in the same bundle.
 
-```xml 
+```xml
 <registry>
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
     <value key="enabled">True</value>
     <value key="csscompilation">++plone++myproject.site/style.min.css</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -72,34 +76,53 @@ You can also register a JavaScript file and a CSS file in the same bundle.
 
 ## Available attributes
 
-The following attributes are available for registering a static resource:
+The following attributes are available for registering a static resource.
 
 `enabled`
-:   Whether the bundle is enabled or not.
+:   Boolean.
+    Whether the bundle is enabled or not.
     If it is disabled, the bundle will not be loaded.
 
 `jscompilation`
-:   The path to the compiled JavaScript file.
+:   String.
+    The path to the compiled JavaScript file.
 
 `csscompilation`
-:   The path to the compiled CSS file.
+:   String.
+    The path to the compiled CSS file.
 
 `depends`
-:   A list of bundles that this bundle depends on.
+:   String.
+    A comma-separated list of bundles that this bundle depends on.
+    For a single dependency, do not insert commas.
+
+    When a bundle depends on another one, its `<script>` or `<link>` tag is rendered after the bundle it depends on.
+
+    If the bundle's dependencies do not exist, then the bundle will not render.
+
+    The `depends` attribute may be assigned the value of `all`, making this bundle render last, after all other bundles.
+    The `all` value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.
+
+    ```{note}
+    Setting `depends` to `all` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
+    It only affects bundles, not control panel settings.
+    ```
+
+    ```{versionadded} Plone 6.0.14
+    `depends` value of `all`.
+    ```
 
 `load_async`
-:   Whether the bundle should be loaded asynchronously or not.
+:   Boolean.
+    Whether the bundle should be loaded asynchronously or not.
     *Only JavaScript*
 
 `load_defer`
-:   Whether the bundle should be loaded deferred or not.
+:   Boolean.
+    Whether the bundle should be loaded deferred or not.
+    If you use `load_async`, this attribute has no effect.
     *Only JavaScript*
 
-
-(classic-ui-static-resources-loading-order-label)=
-
-## Loading order of resources
-
 You can use the `depends` attribute to define the order in which resources load.
 
 You can specify a list of either the names of the bundles on which this bundle depends or a single list item of `["all"]`.
@@ -109,11 +132,3 @@ This includes the theme, such as Barceloneta's theme CSS.
 This feature lets you override a theme with custom CSS from a bundle.
 Previously you had to add the CSS customizations to the registry via the `custom_css` settings, then update the registry after every change.
 
-```{versionadded} Plone 6.0.14
-The `depends` attribute may be assigned the value of `["all"]`, making this bundle render last, after all other bundles.
-```
-
-```{note}
-Setting `depends=["all"]` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
-It only affects bundles, not control panel settings.
-```