static (#97)

* static

* docs

Author: Frooodle

docs/Configuration/Other Customisations.md

@@ -5,17 +5,183 @@ sidebar_position: 13
 
 Stirling PDF offers various other customisation options, such as:
 
-### Defaulting Language
+## Static File Overrides
+
+You can override static files (logos, images, favicons, etc.) by placing custom versions in the `customFiles/static/` directory.
+
+### How It Works
+
+Stirling-PDF checks for files in this order:
+1. **First:** `customFiles/static/` (your custom files)
+2. **Fallback:** Built-in static files embedded in the application
+
+This means you can replace any static resource by placing a file with the matching path in `customFiles/static/`.
+
+### Finding File Paths to Override
+
+Static files in the application come from the `frontend/public/` folder in the source code. The mapping is direct:
+
+**Frontend source → Your override path:**
+- `frontend/public/favicon.svg` → `customFiles/static/favicon.svg`
+- `frontend/public/modern-logo/logo.svg` → `customFiles/static/modern-logo/logo.svg`
+- `frontend/public/classic-logo/logo.svg` → `customFiles/static/classic-logo/logo.svg`
+
+**To see what files you can override:**
+1. Browse the [frontend/public folder on GitHub](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/frontend/public)
+2. Match the directory structure in your `customFiles/static/` folder
+
+Common files you might want to override:
+
+**Favicons & Icons:**
+- `favicon.svg`, `favicon.ico` - Browser favicons
+- `apple-touch-icon.png` - iOS home screen icon
+- `android-chrome-192x192.png` - Android icon (192x192)
+- `android-chrome-512x512.png` - Android icon (512x512)
+
+**Logo Variants (Both classic-logo/ and modern-logo/):**
+
+Both logo directories contain the same file structure - just replace `classic-logo/` or `modern-logo/` with whichever style you're using:
+
+- `{style}/StirlingPDFLogoBlackText.svg` - Logo with black text (light mode)
+- `{style}/StirlingPDFLogoWhiteText.svg` - Logo with white text (dark mode)
+- `{style}/StirlingPDFLogoGreyText.svg` - Logo with grey text
+- `{style}/StirlingPDFLogoNoTextDark.svg` - Logo without text (dark variant)
+- `{style}/StirlingPDFLogoNoTextLight.svg` - Logo without text (light variant)
+- `{style}/logo-tooltip.svg` - Small logo for tooltips
+- `{style}/favicon.ico` - Style-specific favicon
+- `{style}/logo192.png`, `{style}/logo512.png` - PNG versions at different sizes
+- `{style}/Firstpage.png` - First page preview image
+
+Where `{style}` is either `classic-logo` or `modern-logo` depending on your logo style setting:
+
+**Settings file (configs/settings.yml):**
+```yaml
+ui:
+  logoStyle: classic  # Options: 'classic' or 'modern'
+```
+
+**Environment variable (Docker):**
+```bash
+UI_LOGOSTYLE=classic
+```
+
+**In-app configuration:**
+Settings → UI → Logo Style (requires login enabled)
+
+**Other Assets:**
+- `moon.svg` - Dark mode toggle icon
+- `robots.txt` - Search engine directives
+- `manifest.json`, `manifest-classic.json` - Web app manifests
+- Images, fonts, and locales
+
+### Example: Custom Favicon
+
+```bash
+# Your directory structure
+customFiles/
+  └── static/
+      ├── favicon.svg
+      └── favicon.ico
+```
+
+Docker compose:
+```yaml
+volumes:
+  - ./customFiles:/customFiles:rw
+```
+
+Restart the container - your custom favicons will be used!
+
+### Example: Custom Logo (Simple)
+
+```bash
+customFiles/
+  └── static/
+      └── classic-logo/
+          └── StirlingPDFLogoBlackText.svg
+```
+
+This overrides the classic logo with black text (used in light mode).
+
+**Important:** Make sure your logo style is set to `classic` in your configuration:
+```yaml
+ui:
+  logoStyle: classic  # Must match the directory you're overriding!
+```
+
+Or via environment variable:
+```bash
+UI_LOGOSTYLE=classic
+```
+
+If you have `logoStyle: modern` set, override files in `modern-logo/` instead!
+
+### Example: Complete Branding Customization
+
+To fully rebrand Stirling-PDF with your company logo, override multiple variants:
+
+```bash
+customFiles/
+  └── static/
+      ├── favicon.svg                                    # Main favicon
+      ├── favicon.ico                                    # Legacy favicon
+      └── classic-logo/                                  # Or modern-logo/ if using modern style
+          ├── StirlingPDFLogoBlackText.svg              # Light mode with text
+          ├── StirlingPDFLogoWhiteText.svg              # Dark mode with text
+          ├── StirlingPDFLogoNoTextLight.svg            # Light mode icon only
+          ├── StirlingPDFLogoNoTextDark.svg             # Dark mode icon only
+          ├── logo-tooltip.svg                          # Small icon
+          ├── favicon.ico                               # Style-specific favicon
+          └── Firstpage.png                             # Homepage preview
+```
+
+**Important:** Set your logo style to match the directory:
+```yaml
+ui:
+  logoStyle: classic  # Use 'classic' if overriding classic-logo/, 'modern' if overriding modern-logo/
+```
+
+Or via environment variable: `UI_LOGOSTYLE=classic`
+
+**Tips:**
+- For consistent branding across light/dark modes, provide both:
+  - `StirlingPDFLogoBlackText.svg` (shows on light backgrounds)
+  - `StirlingPDFLogoWhiteText.svg` (shows on dark backgrounds)
+- You can also configure this in-app: Settings → UI → Logo Style (if you have login enabled)
+
+### Advanced: Overriding Built Files (HTML, JS, CSS)
+
+**⚠️ For developers only!**
+
+Files like `index.html`, JavaScript bundles, and CSS are **generated** by the build process from `frontend/src/`. To override these:
+
+1. Clone the Stirling-PDF repository
+2. Make your changes to the React source code in `frontend/src/`
+3. Build the frontend: `npm run build` (from the `frontend/` directory)
+4. The built files appear in `frontend/dist/`
+5. Copy the specific files you want to override to `customFiles/static/` matching the path structure
+
+**Example:** To override `index.html`:
+```bash
+# After building the frontend
+cp frontend/dist/index.html customFiles/static/index.html
+```
+
+**Warning:** Built files may include hashed filenames (e.g., `assets/index-abc123.js`) that change with each build. Overriding these requires matching the exact filename from your build and is not recommended for most users.
+
+---
+
+## Defaulting Language
 Default language selection via the `SYSTEM_DEFAULTLOCALE` environment variable. Accepted values include `de-DE`, `fr-FR`, `ar-AR` and all other languages codes that are within Stirling-PDFs current list.
 
-### Google Search Visibility (robots.txt)
+## Google Search Visibility (robots.txt)
 Enable or disable search engine visibility with the `ALLOW_GOOGLE_VISIBILITY` variable.
 
-### Custom Root path
+## Custom Root path
 Redirect the root path of the application using `APP_ROOT_PATH`.
 This is for changing websites like stirlingtools.com to instead host the interface at stirlingtools.com/`APP_ROOT_PATH` like stirlingtools.com/demo
 
-### Enable/Disable Analytics
+## Enable/Disable Analytics
 Analytics can be enabled/disabled with ``SYSTEM_ENABLEANALYTICS`` or
 ```yaml
 system:

docs/Configuration/UI Customisation.md

@@ -20,11 +20,11 @@ These settings (in Settings.yml) control system behavior and customization capab
 - `showUpdate` - Controls whether update notifications are displayed
 - `showUpdateOnlyAdmin` - When true, restricts update notifications to admin users only (requires `showUpdate: true`)
 
-## V2.0 UI Customization Notes
+## UI Customization Options
 
-### In-App Settings Management (V2.0+)
+### In-App Settings Management (Recommended)
 
-**New in V2.0**: If you have login enabled and are logged in as an admin, you can now configure all settings directly in the application through the **Settings** menu. No need to edit `settings.yml` manually!
+If you have login enabled and are logged in as an admin, you can configure all settings directly in the application through the **Settings** menu. No need to edit `settings.yml` manually!
 
 **How to access:**
 1. Enable login: `SECURITY_ENABLELOGIN=true`
@@ -33,36 +33,44 @@ These settings (in Settings.yml) control system behavior and customization capab
 4. Configure all options through the UI
 5. Changes apply immediately
 
-This is the recommended way to manage settings in V2.0 for production deployments.
+**Available customizations:**
+- Application name and branding
+- Update notification settings
+- Language settings
+- Theme preferences
+- Logo style (classic/modern)
+- Custom logo upload
 
-### Template Customization Changes
+### Static File Overrides (Advanced)
 
-**Important**: The V1 `customFiles/` folder system for overriding templates has been replaced with a new customization approach due to the UI framework change in V2.0.
+For customization beyond the built-in settings, you can override static files like logos, favicons, and images:
 
-For advanced UI customization in V2.0:
-1. Clone or download the repository
-2. Modify the React components in the `frontend/src` directory
-3. Build the frontend: `cd frontend && npm install && npm run build`
-4. Volume mount the `frontend/dist` folder into your Docker container to replace the built-in frontend files
-
-Example docker-compose with custom frontend:
 ```yaml
 services:
   stirling-pdf:
     image: stirlingtools/stirling-pdf:latest
     ports:
       - '8080:8080'
     volumes:
-      - ./frontend/dist:/app/frontend/dist  # Mount your custom frontend
-    environment:
-      - MODE=BOTH
+      - ./customFiles:/customFiles:rw
 ```
 
-The following customizations work without rebuilding:
-- Application name and branding (via environment variables or in-app settings)
-- Update notification settings (via in-app settings if admin)
-- Language settings (via in-app settings)
-- Theme preferences (via in-app settings)
+Then place your custom files in `customFiles/static/` matching the path structure. Common examples:
+- `customFiles/static/favicon.svg` - Custom favicon
+- `customFiles/static/classic-logo/logo.svg` - Custom logo
+- `customFiles/static/modern-logo/logo.svg` - Custom modern logo
+
+**Learn more:** [Other Customisations - Static File Overrides](./Other%20Customisations.md#static-file-overrides)
+
+### Fork the Frontend (Developers)
+
+For complete UI customization:
+1. Clone the Stirling-PDF repository
+2. Modify the React components in `frontend/src/`
+3. Build the frontend: `cd frontend && npm install && npm run build`
+4. Use static file overrides or build your own Docker image
+
+This approach requires maintaining your fork and manually merging updates.
 
 ## Configuration Examples
 

docs/Installation/Path Structure.md

@@ -32,7 +32,7 @@ All paths below are relative to the BASE_PATH. The File.separator ensures cross-
 - `pipeline/finishedFolders/` - Completed processing output location
 
 ## Custom Files Structure
-- `customFiles/static/` - Static assets
-- `customFiles/templates/` - Template files
+- `customFiles/static/` - Static asset overrides (logos, images, favicons, etc.)
+- `customFiles/templates/` - Legacy template files (deprecated, not used)
 - `customFiles/signatures/` - Digital signature files
 

docs/Migration/Breaking-Changes.md

@@ -22,29 +22,34 @@ Most V1 deployments will upgrade smoothly to V2, but there are some important ch
 
 ---
 
-## 🎨 Template Customization System Removed
+## 🎨 UI Customization Architecture Changed
 
 **Impact:** HIGH for users who customized UI using `customFiles/templates/`
 
 ### What Changed
 
-**V1 Approach:**
+**V1 Architecture:**
 ```bash
 customFiles/
   └── templates/
       ├── fragments/
-      │   └── navbar.html       # Custom navbar
-      └── home.html             # Custom homepage
+      │   └── navbar.html       # Custom Thymeleaf template
+      └── home.html             # Custom Thymeleaf template
 ```
 
-V1 used server-side template injection with Thymeleaf templates.
+V1 used **server-side rendering** with Thymeleaf templates. HTML was generated dynamically on the server for each request.
 
-**V2 Approach:**
-V2 uses React frontend - server-side template injection no longer possible.
+**V2 Architecture:**
+V2 uses a **React frontend** with client-side rendering. The UI is built into **static files** (HTML, CSS, JavaScript) that are served to the browser.
+
+**What this means:**
+- ❌ Thymeleaf templates (`.html` with `th:*` attributes) no longer work because there's no server-side rendering
+- ✅ Static file overrides **still work** via `customFiles/static/` - same concept, different paths
+- The file paths are different because they're now built React files instead of Thymeleaf templates
 
 ### Migration Path
 
-If you customized templates in V1, you have two options:
+Your V1 Thymeleaf templates cannot be directly reused in V2, but you have three options:
 
 #### Option 1: Use Built-In Customization (Recommended)
 
@@ -65,26 +70,35 @@ V2 provides in-app settings for most common customizations:
 
 **Learn more:** [UI Customisation](../Configuration/UI%20Customisation.md)
 
-#### Option 2: Edit Static Files in Docker
+#### Option 2: Static File Overrides (Same Concept as V1, Different Paths)
 
-For customizations beyond built-in settings, you can mount and edit static files:
+**✅ Still supported in V2!** The static file override system works the same way conceptually - place files in `customFiles/static/` to override defaults.
 
-**Steps:**
-1. Mount the `/customFiles/static/` directory in Docker
-2. Add your custom static files (images, favicons, etc.)
-3. Reference them in your HTML/settings
-4. Restart container to apply changes
+**How it works:**
+1. V2 checks `customFiles/static/` **first** for any requested file
+2. If not found, falls back to the bundled static files
+3. This lets you override logos, CSS, HTML, JavaScript, or any other static asset
 
 **Example Docker compose:**
 ```yaml
 volumes:
   - ./customFiles:/customFiles:rw
 ```
 
+**Key difference from V1:**
+- V1 paths: `customFiles/templates/fragments/navbar.html` (Thymeleaf)
+- V2 paths: `customFiles/static/index.html` (React build output)
+
+The file paths are different because V2 serves the **compiled React app** instead of Thymeleaf templates. See [Other Customisations - Static File Overrides](../Configuration/Other%20Customisations.md#static-file-overrides) for:
+- How to determine the correct file paths in V2
+- Examples of common customizations
+- Understanding the build output structure
+
 **Use cases:**
-- Custom favicon
-- Custom images/logos
-- Static assets
+- Custom favicon or logo
+- Modified `index.html` for advanced branding
+- Custom CSS to override styles
+- Additional static assets
 
 #### Option 3: Fork the Frontend (Advanced)
 
@@ -103,21 +117,25 @@ For complete UI customization:
 
 ### What No Longer Works
 
-These V1 customization patterns are **no longer supported:**
+These V1 **Thymeleaf template features** no longer work because V2 uses React (client-side) instead of Thymeleaf (server-side):
 
 ```html
-<!-- V1: Inject custom navbar (NO LONGER WORKS) -->
+<!-- V1: Thymeleaf fragment injection (NO LONGER WORKS) -->
 <div th:replace="fragments/navbar :: navbar"></div>
 
-<!-- V1: Conditional content (NO LONGER WORKS) -->
+<!-- V1: Thymeleaf conditionals (NO LONGER WORKS) -->
 <div th:if="${@propertyService.get('ui.showAdvanced')}">
   Custom content
 </div>
 
-<!-- V1: Server-side variables (NO LONGER WORKS) -->
+<!-- V1: Thymeleaf variables (NO LONGER WORKS) -->
 <span th:text="${appName}"></span>
 ```
 
+**Why they don't work:** These are Thymeleaf-specific features that require server-side HTML generation. V2 uses React which compiles to static JavaScript that runs in the browser.
+
+**Alternative:** You can still customize the **output** by overriding the built static files in `customFiles/static/`, but you'll be editing the compiled HTML/CSS/JS instead of Thymeleaf templates.
+
 ---
 
 ## ⚙️ UI Settings Moved to In-App Configuration