Skip to main content

UI Customisation

Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own.

Application Name Settings​

These settings control the visible application name:

  • appName - Defines the visible application name shown in the window name and navbar if navbar is not defined separately
  • homeDescription - The description displayed on the homepage under the navbar that first greets the user
  • appNameNavbar - The app name shown within the navbar for all pages

Show update notifications​

These settings (in Settings.yml) control system behavior and customization capabilities:

  • showUpdate - Controls whether update notifications are displayed
  • showUpdateOnlyAdmin - When true, restricts update notifications to admin users only (requires showUpdate: true)

System Configuration​

customHTMLFiles In Settings.yml Enables custom HTML file overrides (called fragments) when set to true

Custom Files​

When customHTMLFiles is enabled, you can override the default templatesby placing your custom files in specific directories. The system uses a resource override mechanism where files in these custom directories take precedence over the default files.

Directory Structure​

customFiles/
├── static/          # Static assets (CSS, JS, images, etc.)
└── templates/       # HTML template files

File Locations​

The root path for custom files varies by installation type:

  • Default/Docker Installation: ./customFiles/
  • Windows Desktop: %APPDATA%\Stirling-PDF\customFiles\
  • MacOS Desktop: ~/Library/Application Support/Stirling-PDF/customFiles/
  • Linux Desktop: ~/.config/Stirling-PDF/customFiles/

Override Examples​

To override existing files, maintain the same directory structure as the original. Here are some examples with links to the original files you would be overriding:

To override a file:

  1. Navigate to the original file in the GitHub repository
  2. Copy its contents
  3. Create the same file path under your customFiles directory following the same directory structure
  4. Paste and modify the contents as needed

Note: When overriding templates, first copy the existing template from the source repository to maintain the base structure.

  1. To replace the favicon:

    customFiles/static/favicon.svg

    Original file: src/main/resources/static/favicon.svg

  2. To override a Bootstrap icon font:

    customFiles/static/css/fonts/bootstrap-icons.woff

    Original file: src/main/resources/static/css/fonts/bootstrap-icons.woff

  3. To modify a template:

    customFiles/templates/fragments/common.html

    Original file: src/main/resources/templates/fragments/common.html

The original files can be found in the GitHub repository under:

Configuration Examples​

ui:
  appName: exampleAppName # Application's visible name
  homeDescription: I am a description # Short description or tagline shown on homepage
  appNameNavbar: navbarName # Name displayed on the navigation bar

system:
  showUpdate: false # Control update notification visibility
  showUpdateOnlyAdmin: false # Restrict update notifications to admins
  customHTMLFiles: false # Enable custom HTML/CSS overrides