docs: add a troubleshooting guide (#473)

.github/ISSUE_TEMPLATE/bug.yml

@@ -14,7 +14,7 @@ body:
       label: Is there an existing issue outlining your problem?
       description: Please search to see if an issue already exists for your problem.
       options:
-        - label: I have searched the existing issues and they do not solve my problem.
+        - label: I have searched the existing issues and [troubleshooting guide](https://github.com/catppuccin/tmux/blob/main/docs/guides/troubleshooting.md), and they do not solve my problem.
           required: true
   - type: textarea
     attributes:
@@ -40,6 +40,13 @@ body:
       placeholder: tmux 3.5a
     validations:
       required: true
+  - type: input
+    attributes:
+      label: What shell are you using?
+      description: "You can find your shell by running `echo $SHELL`"
+      placeholder: bash
+    validations:
+      required: true
   - type: textarea
     attributes:
       label: Any additional comments?

README.md

@@ -57,13 +57,14 @@ options available.
 This method is recommended as TPM has some issues with name conflicts.
 
 <!-- x-release-please-start-version -->
+
 1. Clone this repository to your desired location (e.g.
    `~/.config/tmux/plugins/catppuccin`).
 
-    ```bash
-    mkdir -p ~/.config/tmux/plugins/catppuccin
-    git clone -b v2.1.2 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux
-    ```
+   ```bash
+   mkdir -p ~/.config/tmux/plugins/catppuccin
+   git clone -b v2.1.2 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux
+   ```
 
 1. Add the following line to your `tmux.conf` file:
    `run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux`.
@@ -75,21 +76,23 @@ Check out what to do next in the "[Getting Started Guide](./docs/tutorials/01-ge
 ### TPM
 
 <!-- x-release-please-start-version -->
-1. Install [TPM](https://github.com/tmux-plugins/tpm)
-1. Add the Catppuccin plugin:
+
+1.  Install [TPM](https://github.com/tmux-plugins/tpm)
+1.  Add the Catppuccin plugin:
 
     ```bash
     set -g @plugin 'catppuccin/tmux#v2.1.2' # See https://github.com/catppuccin/tmux/tags for additional tags
     # ...alongside
     set -g @plugin 'tmux-plugins/tpm'
     ```
 
-1. (Optional) Set your preferred flavor, it defaults to `"mocha"`:
+1.  (Optional) Set your preferred flavor, it defaults to `"mocha"`:
 
-    ```bash
-    set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha
-    ```
-<!-- x-release-please-end -->
+        ```bash
+        set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha
+        ```
+
+    <!-- x-release-please-end -->
 
 > [!IMPORTANT]
 > You may have to run `~/.config/tmux/plugins/tpm/bin/clean_plugins`
@@ -171,6 +174,7 @@ run ~/.config/tmux/plugins/tmux-plugins/tmux-battery/battery.tmux
 
 - [Getting Started](./docs/tutorials/01-getting-started.md)
 - [Custom Status Line Segments](./docs/tutorials/02-custom-status.md)
+- [Troubleshooting](./docs/guides/troubleshooting.md)
 
 ### Reference
 

docs/guides/troubleshooting.md

@@ -0,0 +1,37 @@
+# Frequently Asked Questions
+
+## Window Names
+
+By default, window names are the pane title, and the pane title is
+set by the shell running in each pane. Oh My ZSH does this [automatically](https://github.com/ohmyzsh/ohmyzsh/wiki/Settings#automatic-title),
+as does [fish](https://fishshell.com/docs/current/cmds/fish_title.html).
+
+The format string used can be changed by setting the following options:
+
+```bash
+set -g @catppuccin_window_text "#W"
+set -g @catppuccin_window_current_text "#W"
+```
+
+The window title is `#W`, the current path is `#{b:pane_current_path}`. A huge
+amount of customisation is possible, and is explained in depth
+in the "[tmux man page](https://man7.org/linux/man-pages/man1/tmux.1.html#FORMATS)".
+
+## Symbols are not displaying
+
+Make sure you have installed a [Nerd Font](https://www.nerdfonts.com/),
+and that your terminal is set to use that font.
+
+## My options are not being applied
+
+Go through these steps:
+
+1. Completely kill tmux and restart (`killall tmux`).
+1. Ensure every `@catppuccin.*` option is being set _before_
+   the plugin is loaded. Loading occurs where you have `run` in your config file.
+1. Double check for typos. There are two "c"s and two "p"s in "catppuccin".
+1. Do not use `-o` to set options that begin with `@`. The `-o` flag means that
+   the option will not be set if it has already been set. You do not need this
+   in your config file.
+1. Double check that any option that does _not_ start with `@` is set after the
+   plugin is loaded.