Add section for experimental custom regex scopes to customization.md (#…

…2315)

## Checklist

- [X] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [X] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [X] I have not broken the cheatsheet

* No functionality was changed, so no tests were written
* Updated docs, but not cheatsheet (since it's only user settings
change, not Cursorless change)
* No changes to cheatsheet were made

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Pokey Rule <755842+pokey@users.noreply.github.com>

docs/user/customization.md

@@ -70,6 +70,40 @@ push down, editor.action.moveLinesDownAction
 
 Now when you say eg "push down air and bat", cursorless will first select the two tokens with a gray hat over the `a` and `b`, then issue the VSCode command `editor.action.moveLinesDownAction`, and then restore your original selection.
 
+## \[Experimental\] Cursorless custom regex scopes
+
+You can define custom scopes using regexes in `user/cursorless-settings/experimental/regex_scope_types.csv`
+
+:::tip
+
+Use `"visualize <scope>"` to see a live preview of the regex scope in [the scope visualizer](./scope-visualizer.md). It updates in real time every time you save `regex_scope_types.csv`.
+
+:::
+
+For example, here's what `"visualize dotted"` would show with the scope type `dotted,"[\w.]+"`:
+
+<div class="light-mode-invert">
+  ![visualization of a custom regex scope](./images/custom-regex-scopes.png)
+</div>
+
+You can then use commands such as
+
+- `"take dotted sun"` to select `user.text` (line 10)
+- `"copy dotted urge"` to copy `user.chrome_mod` (line 11)
+- `"take every dotted urge"` to select `user.chrome_mod`, `shift`, and `a`
+
+:::tip
+
+> Check out [our wiki page](https://github.com/cursorless-dev/cursorless/wiki/Custom-regex-scopes) for a recipe book of user-created regex scopes!
+
+:::
+
+:::warning
+
+Regex matches cannot cross line boundaries (so multiline matches are not supported). The regexes also have the unicode flag set.
+
+:::
+
 ## Toggling "hat" display
 
 It is possible to show / hide the hats with a command. Keep in mind that many users, often after less than a week using Cursorless, find that their brain starts to tune out the hat display. Some start to miss them when they're gone 🥲

packages/cursorless-org-docs/src/css/custom.css

@@ -20,3 +20,7 @@
 [data-theme="dark"] .dark-mode-invert {
   filter: invert(90%) hue-rotate(180deg);
 }
+
+[data-theme="light"] .light-mode-invert {
+  filter: invert(90%) hue-rotate(180deg);
+}