From 45b3af713e2a6b739a233a4dd3e6e795c28bf6ac Mon Sep 17 00:00:00 2001
From: Smit Barmase <heysmitbarmase@gmail.com>
Date: Mon, 28 Jul 2025 14:31:27 +0530
Subject: [PATCH] doc: Add docs for Forcing X11 scale factor (#35181)

Associated PR: https://github.com/zed-industries/zed/pull/34265
Recent Discussion:
https://github.com/zed-industries/zed/issues/33987#issuecomment-3125936302

Release Notes:

- N/A
---
 docs/src/linux.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/docs/src/linux.md b/docs/src/linux.md
index ca65da2969..309354de6d 100644
--- a/docs/src/linux.md
+++ b/docs/src/linux.md
@@ -294,3 +294,78 @@ If your system uses PipeWire:
    ```
 
 3. **Restart your system**
+
+### Forcing X11 scale factor
+
+On X11 systems, Zed automatically detects the appropriate scale factor for high-DPI displays. The scale factor is determined using the following priority order:
+
+1. `GPUI_X11_SCALE_FACTOR` environment variable (if set)
+2. `Xft.dpi` from X resources database (xrdb)
+3. Automatic detection via RandR based on monitor resolution and physical size
+
+If you want to customize the scale factor beyond what Zed detects automatically, you have several options:
+
+#### Check your current scale factor
+
+You can verify if you have `Xft.dpi` set:
+
+```sh
+xrdb -query | grep Xft.dpi
+```
+
+If this command returns no output, Zed is using RandR (X11's monitor management extension) to automatically calculate the scale factor based on your monitor's reported resolution and physical dimensions.
+
+#### Option 1: Set Xft.dpi (X Resources Database)
+
+`Xft.dpi` is a standard X11 setting that many applications use for consistent font and UI scaling. Setting this ensures Zed scales the same way as other X11 applications that respect this setting.
+
+Edit or create the `~/.Xresources` file:
+
+```sh
+vim ~/.Xresources
+```
+
+Add this line with your desired DPI:
+
+```sh
+Xft.dpi: 96
+```
+
+Common DPI values:
+
+- `96` for standard 1x scaling
+- `144` for 1.5x scaling
+- `192` for 2x scaling
+- `288` for 3x scaling
+
+Load the configuration:
+
+```sh
+xrdb -merge ~/.Xresources
+```
+
+Restart Zed for the changes to take effect.
+
+#### Option 2: Use the GPUI_X11_SCALE_FACTOR environment variable
+
+This Zed-specific environment variable directly sets the scale factor, bypassing all automatic detection.
+
+```sh
+GPUI_X11_SCALE_FACTOR=1.5 zed
+```
+
+You can use decimal values (e.g., `1.25`, `1.5`, `2.0`) or set `GPUI_X11_SCALE_FACTOR=randr` to force RandR-based detection even when `Xft.dpi` is set.
+
+To make this permanent, add it to your shell profile or desktop entry.
+
+#### Option 3: Adjust system-wide RandR DPI
+
+This changes the reported DPI for your entire X11 session, affecting how RandR calculates scaling for all applications that use it.
+
+Add this to your `.xprofile` or `.xinitrc`:
+
+```sh
+xrandr --dpi 192
+```
+
+Replace `192` with your desired DPI value. This affects the system globally and will be used by Zed's automatic RandR detection when `Xft.dpi` is not set.