From 4d5932327823d5db4a67724824a7892e00cfbd3b Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Mon, 27 Oct 2025 17:50:16 -0700 Subject: [PATCH] add branding guide --- docs.json | 3 +- manage/branding.mdx | 312 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 314 insertions(+), 1 deletion(-) create mode 100644 manage/branding.mdx diff --git a/docs.json b/docs.json index 335ef74..6250c70 100644 --- a/docs.json +++ b/docs.json @@ -84,7 +84,8 @@ ] }, "manage/domains", - "manage/integration-api" + "manage/integration-api", + "manage/branding" ] }, { diff --git a/manage/branding.mdx b/manage/branding.mdx new file mode 100644 index 0000000..bc5736c --- /dev/null +++ b/manage/branding.mdx @@ -0,0 +1,312 @@ +--- +title: "Branding" +description: "Learn how to customize the look your Pangolin dashboard and login pages with custom branding" +--- + + +Branding is only available in Enterprise Edition. + + +Pangolin allows you to customize the appearance of your dashboard with your own branding, including colors, logos, and custom text for authentication pages. Branding is configured through the `privateConfig.yml` file. + + +Branding is currently available for the entire application only. Organization-specific branding will be available in a future release. Let us know if this is a priority for you. + + +## Setting up Branding + +To get started, create a `privateConfig.yml` file next to your existing `config.yml` file: + +```yaml title="privateConfig.yml" +branding: + app_name: "MyApp" + + logo: + light_path: "/branding/logo-light.svg" + dark_path: "/branding/logo-dark.svg" + + favicon_path: "/branding/favicon.ico" + + colors: + light: + primary: "hsl(212, 65%, 35%)" + ring: "hsl(212, 65%, 35%)" + primary-foreground: "hsl(0 0% 98%)" + dark: + primary: "hsl(212, 65%, 45%)" + ring: "hsl(212, 65%, 35%)" + primary-foreground: "hsl(0 0% 98%)" +``` + +## Mounting Branding Assets + +For image assets like logos and backgrounds, you need to mount a volume to the Pangolin container to make them accessible to the application: + +```yaml title="docker-compose.yml" +volumes: + - ./config:/app/config + - ./branding:/app/public/branding +``` + +Your folder structure should look like this: + +``` +. +├── config/ +│ ├── config.yml +│ └── privateConfig.yml +└── branding/ + ├── logo-light.svg + ├── logo-dark.svg + └── favicon.ico +``` + +## Reference + +All branding configuration options are optional. Only specify the sections you want to customize. + +### Application Name + + + The name of your application that appears in various places throughout the UI. + + **Example**: `"MyApp"` + + +### Background Image + + + Path to a custom background image used on authentication pages. + + **Example**: `"/branding/backgrounds/bg.png"` + + + Requires mounting a volume to `/app/public`. + + + +### Colors + + + Custom color scheme that overrides the default Tailwind classes for shadcn components. + + Colors can be provided in OKLCH or HSL format for example and apply to both light and dark modes. + + **Color Reference**: Available color properties include `background`, `foreground`, `card`, `card-foreground`, `popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`, `radius`, and `chart-1` through `chart-5`. + + **Example**: + ```yaml + colors: + light: + primary: "hsl(212, 65%, 35%)" + background: "hsl(212, 65%, 35%)" + foreground: "hsl(0 0% 98%)" + dark: + primary: "hsl(212, 65%, 45%)" + background: "hsl(212, 65%, 35%)" + foreground: "hsl(0 0% 98%)" + ``` + + + For a complete list of Tailwind color classes used by shadcn components, refer to the [shadcn/ui documentation](https://ui.shadcn.com/docs/theming). + + + +### Logo + + + Logo configuration for different parts of the application. + + + + Path to the logo image used in light mode. + + **Example**: `"/branding/logo-light.svg"` + + + + Path to the logo image used in dark mode. + + **Example**: `"/branding/logo-dark.svg"` + + + + Logo dimensions for authentication pages. + + + + Logo width in pixels. + + **Example**: `200` + + + + Logo height in pixels. + + **Example**: `80` + + + + + + Logo dimensions for the navigation bar. + + + + Logo width in pixels. + + **Example**: `150` + + + + Logo height in pixels. + + **Example**: `60` + + + + + + +### Favicon + + + Path to a custom favicon. + + **Example**: `"/branding/favicon.ico"` + + + Requires mounting a volume to `/app/public`. + + + +### Footer + + + Custom footer links displayed at the bottom of the page. + + **Example**: + ```yaml + footer: + - text: "Privacy Policy" + href: "https://example.com/privacy" + - text: "Terms of Service" + href: "https://example.com/terms" + ``` + + + The display text for the footer link. + + + + The URL or path for the footer link. + + + +### Login Page + + + Custom text for the login page. + + + + The main title text displayed on the login page. + + **Example**: `"Welcome Back!"` + + + + The subtitle text displayed below the title. + + **Example**: `"Sign in to continue to your account"` + + + + +### Signup Page + + + Custom text for the signup page. + + + + The main title text displayed on the signup page. + + **Example**: `"Create Your Account"` + + + + The subtitle text displayed below the title. + + **Example**: `"Join us and get started today"` + + + + +### Resource Auth Page + + + Configuration for the resource authentication page shown to users when accessing protected resources. + + + + Whether to display the logo on the resource auth page. + + **Default**: `true` + + + + Whether to hide the "Powered by Pangolin" text on the resource auth page. + + **Default**: `false` + + + + The main title text displayed on the resource auth page. + + **Example**: `"Access Restricted"` + + + + The subtitle text displayed below the title. + + **Example**: `"Please sign in to view this resource"` + + + + +### Emails + + + Email customization settings. + + + + Custom signature appended to sent emails. + + **Example**: `"Best regards,\nThe MyApp Team"` + + + Use `\n` for line breaks in the signature. + + + + + Email color scheme. + + + + Primary color for email elements. + + **Example**: `"oklch(0.6717 0.1946 41.93)"` + + + + + + +## Applying Changes + + +After creating or modifying `privateConfig.yml`, you must restart the Pangolin container for changes to take effect. +