Update documentation instructing the users to use community snippets (#…

…2733) ## Checklist - [/] 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) - [/] I have not broken the cheatsheet --------- Co-authored-by: Phil Cohen <[email protected]>
cursorless-dev · Jan 18, 2025 · 362ec98 · 362ec98
1 parent ca1a80e
commit 362ec98
Showing 1 changed file with 14 additions and 10 deletions.
diff --git a/packages/cursorless-org-docs/src/docs/user/experimental/snippets.md b/packages/cursorless-org-docs/src/docs/user/experimental/snippets.md
@@ -3,6 +3,20 @@
 ![Wrapper snippet demo](images/tryWrapFine.gif)
 ![Link wrap](images/linkWrap.gif)
 
+## Using community snippets (RECOMMENDED)
+
+The community Talon files now support their own snippet format, which is now preferred.
+
+If you'd like to use these snippets for wrapping and inserting with Cursorless instead of the legacy Cursorless snippets, add the following line to your `settings.talon` file:
+
+```talon
+tag(): user.cursorless_use_community_snippets
+```
+
+Note that this line will also disable any Cursorless snippets defined in your Cursorless customization CSVs. You will need to migrate your Cursorless snippets to the new community snippet format [described in community](https://github.com/talonhub/community/blob/main/core/snippets/README.md). If you'd be interested in a tool to help with this migration, please leave a comment on [cursorless-dev/cursorless#2149](https://github.com/cursorless-dev/cursorless/issues/2149), ideally with a link to your custom snippets for us to look at.
+
+## Cursorless experimental snippets (DEPRECATED)
+
 Cursorless has its own experimental snippet engine that allows you to both insert snippets and wrap targets with snippets. Cursorless ships with a few built-in snippets, but users can also use their own snippets.
 
 ## Using snippets
@@ -88,16 +102,6 @@ Note that each snippet can use `insertionScopeTypes` to indicate that it will au
 | `"snippet funk"`    | Function; phrase becomes name           | Function                     | ✅                       |
 | `"snippet link"`    | Markdown link; phrase becomes link text |                              | ✅                       |
 
-## Using community snippets
-
-The community Talon files now support their own snippet format. If you'd like to use these snippets for wrapping / cursorless insertion instead of snippets defined in Cursorless, add following line to your `settings.talon` file:
-
-```talon
-tag(): user.cursorless_use_community_snippets
-```
-
-Note that this line will also disable any Cursorless snippets defined in your Cursorless customization CSVs. You will need to migrate your Cursorless snippets to the new community snippet format [described in community](https://github.com/talonhub/community/blob/main/core/snippets/README.md). If you'd be interested in a tool to help with this migration, please leave a comment on [cursorless-dev/cursorless#2149](https://github.com/cursorless-dev/cursorless/issues/2149), ideally with a link to your custom snippets for us to look at.
-
 ## Customizing spoken forms
 
 As usual, the spoken forms for these snippets can be [customized by csv](../customization.md). The csvs are in the files in `cursorless-settings/experimental` with `snippet` in their name.