Add docs for headless user bar setup

Author: laymonage

headless-userbar.md

@@ -0,0 +1,19 @@
+# Exposing the Wagtail user bar to the headless frontend
+
+This document explains how the Wagtail userbar is made available to frontend applications in a headless setup, including the use of the custom `UserbarView`, URL configuration, and customization of the accessibility item for cross-origin support.
+
+## 1. UserbarView and URL Configuration
+
+A custom Django view, `UserbarView`, is implemented in `bakerydemo/headless.py` to expose the Wagtail userbar as an API endpoint. The example in this repo does not handle authentication; it only renders the userbar and sets the necessary CORS header. This may need to be adjusted depending on how the API is accessed by the frontend.
+
+To make the userbar accessible to the frontend, a URL pattern for the `UserbarView` is added in the main `urls.py`. This exposes the userbar at `/userbar/`, which the frontend can call to retrieve the userbar markup or data.
+
+## 2. Customizing the AccessibilityItem for Cross-Origin Support
+
+The `allowedOrigins` property in Axe's spec must be set to the headless frontend's host. This allows Axe in the page editor to securely communicate with the frontend for accessibility checks. This can be done by overriding `get_axe_spec` in an `AccessibilityItem` subclass. The subclass is then used via the `construct_wagtail_userbar` hook.
+
+## References
+
+- [`bakerydemo/headless.py`](./bakerydemo/headless.py): Contains the `UserbarView` implementation.
+- [`bakerydemo/urls.py`](./bakerydemo/urls.py): Main URL configuration including the userbar endpoint.
+- [`bakerydemo/base/wagtail_hooks.py`](./bakerydemo/base/wagtail_hooks.py): Customizes the accessibility item for cross-origin support.