From 2afd32fbb04e2c3f50de81d0b906ca7de47b2bd2 Mon Sep 17 00:00:00 2001
From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com>
Date: Fri, 21 Mar 2025 02:56:19 -0400
Subject: [PATCH] docs: update font-related troubleshooting (#1695)

---
 docs/content/troubleshooting.md | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/content/troubleshooting.md b/docs/content/troubleshooting.md
index 3a56fcec..192baed2 100644
--- a/docs/content/troubleshooting.md
+++ b/docs/content/troubleshooting.md
@@ -23,18 +23,24 @@ Another (better) alternative is to install a font that supports braille fonts, a
 For example, installing something like [UBraille](https://yudit.org/download/fonts/UBraille/) or [Iosevka](https://github.com/be5invis/Iosevka)
 and ensuring your terminal uses it should work.
 
-### Braille font issues on Linux/macOS/Unix-like
+### Linux/macOS/Unix
 
-Generally, the problem comes down to you either not having a font that supports the braille markers, or your terminal
-emulator is not using the correct font for the braille markers.
+If you're on a Unix-like system, generally, the problem comes down to you either not having a font that supports the
+braille markers, or your terminal emulator is not using the correct font for the braille markers.
 
-See [here](https://github.com/cjbassi/gotop/issues/18) for possible fixes if you're having font issues on Linux, which
-may also be helpful for macOS or other Unix-like systems.
+Some possible solutions include:
+
+- Uninstalling `gnu-free-fonts` if installed, as that is known to cause problems with braille markers
+- Installing a font like `ttf-symbola` or `ttf-ubraille` for your terminal emulator to try and automatically fall back to
+- Configuring your terminal emulator to use specific fonts for the `U+2800` to `U+28FF` range.
+  - For example for kitty, do `symbol_map U+2800-U+28FF Symbola`.
+
+See [this issue](https://github.com/cjbassi/gotop/issues/18) for more possible fixes.
 
 If you're still having issues, feel free to open a [discussion](https://github.com/ClementTsang/bottom/discussions/new/)
 question about it.
 
-### Installing fonts for Windows Command Prompt/PowerShell
+### Windows/Powershell
 
 **Note: I would advise backing up your registry beforehand if you aren't sure what you are doing!**
 
@@ -50,16 +56,16 @@ Let's say you're installing [Iosevka](https://github.com/be5invis/Iosevka). The
 
 4. Here, add a new `String value`, and set the `Name` to a bunch of 0's (e.g. `000` - make sure the name isn't already used), then set the `Data` to the font name (e.g. `Iosevka`).
 
-    <figure>
-        <img src="../assets/screenshots/troubleshooting/regedit_fonts.webp" alt="Regedit menu showing how to add a new font for Command Prompt/PowerShell"/>
-        <figcaption><sub>The last entry is the new entry for Iosevka</sub></figcaption>
-    </figure>
+<figure>
+    <img src="../assets/screenshots/troubleshooting/regedit_fonts.webp" alt="Regedit menu showing how to add a new font for Command Prompt/PowerShell"/>
+    <figcaption><sub>The last entry is the new entry for Iosevka</sub></figcaption>
+</figure>
 
 5. Then, open the Command Prompt/PowerShell, and right-click on the top bar, and open "Properties":
 
-    <figure>
-        <img src="../assets/screenshots/troubleshooting/cmd_prompt_props.webp" alt="Opening the properties menu in Command Prompt/PowerShell"/>
-    </figure>
+<figure>
+    <img src="../assets/screenshots/troubleshooting/cmd_prompt_props.webp" alt="Opening the properties menu in Command Prompt/PowerShell"/>
+</figure>
 
 6. From here, go to "Font", and set the font to your new font (so in this example, Iosevka):