From 84863bdfa9ae2ac139a7ab5ffcc9dd3f7386e04e Mon Sep 17 00:00:00 2001
From: maliming <malimings@gmail.com>
Date: Tue, 25 Aug 2026 16:15:55 +0800
Subject: [PATCH] Document the branding logo urls and the logo icon provider

---
 .../framework/ui/mvc-razor-pages/branding.md  | 37 +++++++++++++++++++
 docs/en/ui-themes/lepton-x/mvc.md             |  2 +
 2 files changed, 39 insertions(+)

diff --git a/docs/en/framework/ui/mvc-razor-pages/branding.md b/docs/en/framework/ui/mvc-razor-pages/branding.md
index e8e9309ff8..9c9f5c6a37 100644
--- a/docs/en/framework/ui/mvc-razor-pages/branding.md
+++ b/docs/en/framework/ui/mvc-razor-pages/branding.md
@@ -43,8 +43,45 @@ The result will be like shown below:
 * `LogoUrl`: A URL to show the application logo.
 * `LogoReverseUrl`: A URL to show the application logo on a reverse color theme (dark, for example).
 
+ABP's built-in MVC themes resolve the branding URLs for the current request. `/logo.png`, `logo.png` and `~/logo.png` are treated as application relative URLs and include the `PathBase` of the request, so they keep working when the application is deployed to a non-root path, like an IIS virtual directory. Absolute HTTP(S) URLs, like `https://cdn.example.com/logo.png`, and protocol relative URLs, like `//cdn.example.com/logo.png`, are returned unchanged. `null` and white space values are treated as not set.
+
+If you render a branding URL in a custom MVC theme or view, resolve it with `Url.ResolveBrandingUrl(...)`.
+
 > **Tip**: `IBrandingProvider` is used in every page refresh. For a multi-tenant application, you can return a tenant specific application name to customize it per tenant.
 
+## IBrandingLogoProvider
+
+Some theme areas need a compact logo, like a collapsed menu. To provide one, make the same branding provider implement both `IBrandingProvider` and `IBrandingLogoProvider`. `DefaultBrandingProvider` implements both, so a derived provider only overrides the icon properties:
+
+````csharp
+using Volo.Abp.Ui.Branding;
+using Volo.Abp.DependencyInjection;
+
+namespace MyProject.Web
+{
+    [Dependency(ReplaceServices = true)]
+    public class MyProjectBrandingProvider : DefaultBrandingProvider
+    {
+        public override string AppName => "Book Store";
+
+        public override string LogoUrl => "/logo.png";
+
+        public override string LogoIconUrl => "/logo-icon.png";
+    }
+}
+````
+
+`IBrandingLogoProvider` has the following properties:
+
+* `LogoIconUrl`: A URL to show the compact application logo.
+* `LogoIconReverseUrl`: A URL to show the compact application logo on a reverse color theme.
+
+Both properties return `null` by default and follow the same URL rules as `LogoUrl`.
+
+The active theme decides whether and where to use the compact logo. The LeptonX MVC theme enables its compact branding when `LogoIconUrl` is not empty: it uses the compact logo instead of the full logo in its branding areas and shows `AppName` next to it where there is room for both. Dark and dim styles use `LogoIconReverseUrl` and fall back to `LogoIconUrl` when it is not set. Themes that don't support `IBrandingLogoProvider` ignore these properties.
+
+> This URL resolution and the compact logo apply to the ASP.NET Core MVC / Razor Pages themes. The Blazor themes handle branding on their own.
+
 ## Overriding the Branding Area
 
 You can see the [UI Customization Guide](customization-user-interface.md) to learn how you can replace the branding area with a custom view component.
diff --git a/docs/en/ui-themes/lepton-x/mvc.md b/docs/en/ui-themes/lepton-x/mvc.md
index 392af280fe..e52e1a91c8 100644
--- a/docs/en/ui-themes/lepton-x/mvc.md
+++ b/docs/en/ui-themes/lepton-x/mvc.md
@@ -261,6 +261,8 @@ General Settings can be replaced with following files.
 
 Application name and logo can be customized by using the `IBrandingProvider` service. See [Razor Pages: Branding](../../framework/ui/mvc-razor-pages/branding.md) for more information.
 
+When the branding provider also provides a `LogoIconUrl`, LeptonX switches to its compact branding: the branding areas show the logo icon instead of the full logo and render the application name next to it. Dark and dim styles use `LogoIconReverseUrl` and fall back to `LogoIconUrl`.
+
 If you need to replace the component, you can follow the steps below.
 
 * The **main header branding component page (.cshtml file)** is defined in the `Themes/LeptonX/Components/Common/MainHeaderBranding/Default.cshtml` file and you can **override it** by creating a file with the **same name** and **under** the **same folder**.