diff --git a/README.md b/README.md
index c129297..e6ea522 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,29 @@ You can however exempt directories that have been added through the `config.asse
 
 These assets can be referenced through their logical path using the normal helpers like `asset_path`, `image_tag`, `javascript_include_tag`, and all the other asset helper tags. These logical references are automatically converted into digest-aware paths in production when `assets:precompile` has been run (through a JSON mapping file found in `public/assets/.manifest.json`).
 
+## Referencing digested assets in CSS and JavaScript
+
+Propshaft will automatically convert asset references in CSS to use the digested file names. So `background: url("/bg/pattern.svg")` is converted to `background: url("/assets/bg/pattern-2169cbef.svg")` before the stylesheet is served.
+
+For JavaScript, you'll have to manually trigger this transformation by using the `RAILS_ASSET_URL` pseudo-method. It's used like this:
+
+```javascript
+export default class extends Controller {
+  init() {
+    this.img = RAILS_ASSET_URL("/icons/trash.svg")
+  }
+}
+```
+
+That'll turn into:
+
+```javascript
+export default class extends Controller {
+  init() {
+    this.img = "/assets/icons/trash-54g9cbef.svg"
+  }
+}
+```
 
 ## Bypassing the digest step