Document asset URL functionality in Snowboard.js URL plugin

snowboard/utilities.md

@@ -256,22 +256,44 @@ When the URL plugin is loaded, it will automatically detect the base URL for the
 
 You can retrieve the base URL by calling `Snowboard.url().baseUrl()` anywhere in your JavaScript.
 
+### Asset URL detection
+
+When the URL plugin is loaded, it will automatically detect the asset URL for the current project, based on three sources in order:
+
+- If Snowboard is loaded via the `{% snowboard %}` Twig tag, which is the recommended way of loading Snowboard, then a `data-asset-url` attribute is added to the script tag, and will be passed through to Snowboard as the asset URL.
+- If Snowboard is manually loaded, it will attempt to find a `<link rel="asset_url">` tag in the HTML. If one is found, the `href` of this tag will be used as the asset URL.
+- If neither option above work, then the asset URL will be determined to be the hostname of the site per the current URL. This will *not work* if you host Winter in a subdirectory, so please use either of the options above in this situation.
+
+You can retrieve the base URL by calling `Snowboard.url().assetUrl()` anywhere in your JavaScript.
+
 ### URL generation
 
-You can generate a URL that is correctly based through the `to` method in the URL plugin. This will ensure that any URLs you use in your JavaScript are pointing to the correct URL.
+You can generate a URL that is correctly based through the `to` and `asset()` methods in the URL plugin. This will ensure that any URLs you use in your JavaScript are pointing to the correct URL.
 
 If an absolute URL is provided to this helper, it will be returned unchanged:
 
 ```js
 Snowboard.url().baseUrl();
-// returns "https://mysite.com/"
+// returns "https://example.com/"
 
 Snowboard.url().to('/');
-// returns "https://mysite.com/"
+// returns "https://example.com/"
 
 Snowboard.url().to('my-page/my-sub-page');
-// returns "https://mysite.com/my-page/my-sub-page"
+// returns "https://example.com/my-page/my-sub-page"
 
 Snowboard.url().to('https://google.com');
 // returns "https://google.com"
+
+Snowboard.url().assetUrl();
+// returns "https://cdn.example.com/"
+
+Snowboard.url().asset('/');
+// returns "https://cdn.example.com/"
+
+Snowboard.url().asset('assets/images');
+// returns "https://cdn.example.com/assets/images"
+
+Snowboard.url().asset('https://cdn.example.com/external/lib/leftpad.js?v1.2');
+// returns "https://cdn.example.com/external/lib/leftpad.js?v1.2"
 ```