Created How to understand a user.js file (markdown)

How-to-understand-a-user.js-file.md

@@ -0,0 +1,63 @@
+## Understanding `user.js` Syntax
+
+Think of your `user.js` file as a list of instructions you're giving to Firefox. Each instruction tells Firefox to set a specific preference to a particular value.
+
+### Basic Structure
+
+Every line that sets a preference follows this format:
+
+`user_pref("preference.name.here", value);`
+
+Let's unpack that:
+
+*   `user_pref`: This is just a command that tells Firefox, "Hey, I want to set a user preference." You'll see this at the start of almost every active line.
+*   `("preference.name.here", value)`: This part is enclosed in parentheses.
+    *   `"preference.name.here"`: This is the **name** of the Firefox setting you want to change. It's always a string of text, wrapped in double quotes. These names can look a bit like website addresses, with dots separating different parts. For example, `browser.startup.homepage` tells Firefox what page to load when it starts.
+    *   `,`: A comma separates the preference name from its value.
+    *   `value`: This is what you want to set the preference **to**. The type of value depends on the preference (see next section).
+*   `;`: Each `user_pref` line **must end with a semicolon**. This tells Firefox that the instruction is complete. Forgetting this is a common mistake!
+
+### Types of Values
+
+There are three main types of values you'll use:
+
+1.  **Boolean (True/False):**
+    *   This is for settings that are either on or off.
+    *   You'll use `true` (to turn it on) or `false` (to turn it off).
+    *   **Example:** `user_pref("browser.tabs.warnOnClose", false);` (This tells Firefox *not* to warn you when you close multiple tabs.)
+    *   **Important:** Don't put quotes around `true` or `false`. They are keywords, not text strings in this case.
+
+2.  **Integer (Numbers):**
+    *   This is for settings that require a whole number.
+    *   **Example:** `user_pref("network.http.max-persistent-connections-per-server", 6);` (This sets the maximum number of connections to a server to 6.)
+    *   **Important:** Just use the number. No quotes.
+
+3.  **String (Text):**
+    *   This is for settings that require text, like a URL or a file path.
+    *   Strings **must be enclosed in double quotes**.
+    *   **Example:** `user_pref("browser.startup.homepage", "https://www.duckduckgo.com");` (This sets your homepage to DuckDuckGo.)
+
+### Adding Comments
+
+Sometimes you want to leave notes in your `user.js` file to explain why you made a change, or to temporarily disable a setting without deleting it. You can do this with comments. Firefox ignores comments.
+
+*   **Single-line comment:** Start the line with `//`. Everything after `//` on that line is ignored.
+    *   `// This is a comment explaining the next line.`
+    *   `user_pref("some.setting", true); // This part is also a comment.`
+
+*   **Multi-line comment (less common in `user.js` but good to know):** Start with `/*` and end with `*/`. Everything between them is ignored.
+    *   `/*`
+    *   `This is a comment`
+    *   `that spans multiple lines.`
+    *   `*/`
+
+### Common Problem Areas
+
+*   **Typos:** A misspelled preference name or an incorrect value type will mean the setting won't apply.
+*   **Missing Semicolons:** Every `user_pref` line needs to end with `;`.
+*   **Quotes:** Use double quotes for preference names and string values. Don't use them for booleans (`true`/`false`) or integers.
+*   **Activating Changes:** Firefox only reads the `user.js` file when it starts up. So, if you make changes, you **must restart Firefox** to see them take effect.
+
+### Betterfox defaults
+
+The Betterfox project is a curated collection of these `user_pref` settings, designed to enhance your privacy, security, and browsing experience. We've put a lot of thought into these defaults, but feel free to make it your own.