diff --git a/src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx b/src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx
index dc96ec135..efd33503e 100644
--- a/src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx
+++ b/src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx
@@ -74,6 +74,24 @@ When the resource is started, the URL is available in the dashboard.
 
 Alternatively, you could use the overload that accepts a `Func<EndpointReference, ResourceUrlAnnotation>` as a callback. This allows you to specify deep-links on target `EndpointReference` instances.
 
+### Control URL display order
+
+When a resource exposes multiple custom URLs, use the `DisplayOrder` property on `ResourceUrlAnnotation` to control the order they appear in the dashboard. Higher values sort higher (first) in the list. `DisplayOrder` is a nullable `int`, so URLs without an explicit value fall back to the default ordering.
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddProject<Projects.AspireApp_Api>("api")
+    .WithUrlForEndpoint("https", url =>
+    {
+        url.DisplayText = "Scalar (HTTPS)";
+        url.Url = "/scalar";
+        url.DisplayOrder = 1000;
+    });
+
+builder.Build().Run();
+```
+
 ### Customize multiple resource URLs
 
 To customize multiple URLs for a resource, use the `WithUrls` method. This method allows you to specify multiple URLs for a resource, each with its own display text. The following example demonstrates how to set multiple URLs for a project resource: