doc: modernize fav editor guide

Author: tophf

content/posts/how-to-edit-scripts-with-your-favorite-editor/editor-1.png

@@ -12,61 +12,75 @@ redirect_from:
   - /2017/03/14/How-to-edit-scripts-with-your-favorite-editor/
 ---
 
-For anyone who uses Violentmonkey, it is easy to find a way to edit a script like this:
+Since Violentmonkey is a lightweight script manager by design, its editor is simple and offers just a few options. It doesn't try to replicate a full-featured editor or IDE, which is problematic anyway due to browser's hardcoded hotkeys and other restrictions.
+
+<details>
+<summary>Screenshot of the built-in editor and its options</summary>
 
 ![](editor-1.png)
 
-However, it is really hard to make everyone love it. *A* probably likes a theme of `monokai`, while *B* prefers `eclipse`. *C* might use 2 spaces for indentation while *D* prefers tabs.
+Customization in the extension's settings:
 
-It is impossible to satisfy every single user. Lots of configurations may be added for this, but are they really worth it? A user would have to face lots of choices before he could use it just as a script manager, or have to look for a simple option among lots of unrelated editor options. What is worse, the browser may inhibit some shortcuts or operations that a local editor can have. In other words, an editor inside Violentmonkey will never be as good as your favorite one.
+![](editor-2.png)
 
-Here comes the question: How to edit my script with my favorite editor?
+</details>
 
-Save to a file
----
+<br/>
 
-First, copy the script to your favorite editor and save it to a file.
+Excellent external editors exist and using one to edit scripts in Violentmonkey is relatively simple, no need to reinvent the wheel.
 
-![](editor-2.png)
+## 1. One-time preparation
 
-VIM is my favorite editor, and the script is saved at `D:/Source/vm-script.user.js`. Note that the script file must have a name ending with `.user.js`, otherwise won't be recognized by Violentmonkey.
+1. Copy the code of the script from Violentmonkey into your editor.
+2. Save it to a file and give it a name ending with `.user.js`
 
-Install a local script
----
+## 2. Open this file in Violentmonkey installer
+
+⚠ The local file's name must end with `.user.js`, otherwise it won't be recognized by Violentmonkey. The only exception is method 2.1, which recognizes any `.js` file because you explicitly drag it into the extension.
 
-First make sure the local script is named with a suffix of `.user.js`.
+You can use any of these methods listed in the order of increasing complexity:
 
-Then use one of these methods:
+#### 2.1. Drag the file into any Violentmonkey tab or popup
 
-- Drag the file into any Violentmonkey tab or popup.
+⚠ Only implemented in Chrome/Chromium 86 or newer and Violentmonkey 2.16 or newer.
 
-  Requires Chrome/Chromium 86+ and Violentmonkey 2.16+.
+⚡ If you assigned a hotkey to activate Violentmonkey in the browser's options for extensions, you can press it while dragging the file, which opens the extension's popup into which you can drop the dragged file.
 
-- Drag the file into the browser toolbar or tab label area.
+#### 2.2. Drag the file into the browser toolbar or tab label area
 
   * In Chrome-like browsers you must enable *"Allow access to file URLs"* in Violentmonkey's details in `chrome://extensions` page first. Since this is dangerous (any userscript will be able to read any local file via GM_xmlhttpRequest), you may want to use the other methods instead.
 
-  * In modern Firefox-like browsers don't close the file tab while tracking as it's used to read the contents of the file.
+  * In modern Firefox-like browsers don't close the tab of this file while tracking as it's used to read the contents of the file.
 
-- Set up a server and navigate to `http://localhost:8080/my-script.user.js`.
+#### 2.3. Set up a server and navigate to `http://localhost:8080/my-script.user.js`
 
   The port number `:8080` may be different or even omitted depending on the server you installed.
 
-  We recommend [indexzero/http-server](https://github.com/indexzero/http-server#readme). Once you install it, just type `http-server -c5` at the directory of your script to start a server. The `-c5` option sets cache time for max-age header to 5 seconds ([more info](https://github.com/violentmonkey/violentmonkey/issues/460#issuecomment-434335758)), thus forcing a browser to query the server URL every 5 seconds. The caching can be disabled with `-c-1` option.  
+  A good server is [indexzero/http-server](https://github.com/indexzero/http-server#readme). Once you install it, just type `http-server -c5` at the directory of your script to start a server. The `-c5` option sets cache time for max-age header to 5 seconds ([more info](https://github.com/violentmonkey/violentmonkey/issues/460#issuecomment-434335758)), thus forcing a browser to query the server URL every 5 seconds. The caching can be disabled with `-c-1` option.
+
+  If you want a UI, there are such servers as well, e.g. `HTTP File Server` for Windows.
 
-  Make sure the hostname is `localhost` and the script name ends with `.user.js`.
+  ⚠ Make sure the hostname is `localhost` and the script name ends with `.user.js`.
+
+## 3. Enable tracking
 
 ![](editor-3.png)
 
-Click `Track external edits` button to confirm installation. You can also make it the default button for local files by ticking the checkbox on the right.
+Click `Track external edits` button to confirm installation and start tracking.
 
-Edit and sync
----
+You can also make it the default button for local files by ticking the checkbox on the right, so it can be invoked via the hotkey shown in parentheses.
+
+## 4. Edit the local file and save it
 
-After installation, the confirmation page will keep watching the file before the page is closed. Once the file is changed, the new version will be installed automatically. As a result, you edit the script in your favorite editor, and the changes are synced to Violentmonkey immediately.
+As long as the installer tab is open it will track your local file and install the new version automatically into Violentmonkey after you save the file. You can save it either manually or by configuring auto-save in the options of your editor.
+
+* The `Stop tracking` button may be useful for example when temporarily switching branches in your git repo. When finished, you can click `Track external edits` again.
+
+* The `Reload tab` option allows you to switch to another tab with a website [matched](/api/matching/) by this script, so that this tab will be reloaded automatically when changes are detected and this script still matches the tab's URL.
 
 ![](editor-4.png)
 
 Known issues
 ---
-- The older the file is, the more seldom a browser will query it. See [this Violentmonkey's issue](https://github.com/violentmonkey/violentmonkey/issues/460#issuecomment-434335758).
+
+- Firefox may throttle detection: the older the file is, the longer it takes to detect the changes. See [this report](https://github.com/violentmonkey/violentmonkey/issues/460#issuecomment-434335758).

content/posts/how-to-edit-scripts-with-your-favorite-editor/editor-2.png

@@ -32,7 +32,7 @@ export default function TOC(props) {
       // `tableOfContents` from MDX does not support inline markups,
       // as a result the text content may be truncated.
       if (articleRef.current) {
-        const h = articleRef.current.querySelector(`#${id}`);
+        const h = articleRef.current.querySelector(`#${CSS.escape(id)}`);
         if (h) a.textContent = h.textContent.trim();
       }
     });
@@ -42,7 +42,7 @@ export default function TOC(props) {
       const headings = list
         .map((a) => {
           const { id } = a.dataset;
-          const el = articleRef.current.querySelector(`#${id}`);
+          const el = articleRef.current.querySelector(`#${CSS.escape(id)}`);
           return (
             el && {
               id,