Skip to content

Commit be14209

Browse files
Move the targets documentation to a separate file (#3316)
1 parent 91713d8 commit be14209

7 files changed

Lines changed: 194 additions & 189 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
## 2026
44

5+
- 2026-08-30: Overhauled the user documentation with generated and grouped action, modifier, and scope reference pages, richer descriptions and examples, dedicated paired-delimiter and target guides, and a streamlined landing page. ([#3303](https://github.com/cursorless-dev/cursorless/pull/3303); [#3304](https://github.com/cursorless-dev/cursorless/pull/3304); [#3305](https://github.com/cursorless-dev/cursorless/pull/3305); [#3306](https://github.com/cursorless-dev/cursorless/pull/3306); [#3307](https://github.com/cursorless-dev/cursorless/pull/3307); [#3308](https://github.com/cursorless-dev/cursorless/pull/3308); [#3309](https://github.com/cursorless-dev/cursorless/pull/3309); [#3310](https://github.com/cursorless-dev/cursorless/pull/3310); [#3311](https://github.com/cursorless-dev/cursorless/pull/3311); [#3312](https://github.com/cursorless-dev/cursorless/pull/3312); [#3313](https://github.com/cursorless-dev/cursorless/pull/3313); [#3314](https://github.com/cursorless-dev/cursorless/pull/3314); [#3315](https://github.com/cursorless-dev/cursorless/pull/3315); [#3316](https://github.com/cursorless-dev/cursorless/pull/3316))
56
- 2026-05-03: Add support for if and for statements in Talon-script. [`#3274`](https://github.com/cursorless-dev/cursorless/pull/3274)
67
- 2026-03-12: Added `userColor3` and `userColor4` as additional user-configurable hat colors. They are disabled by default until you enable and name them. ([#3206](https://github.com/cursorless-dev/cursorless/pull/3206))
78
- 2026-03-11: Moved scope tests out of VSCode so they can run as regular unit tests with faster local and CI feedback. ([#3210](https://github.com/cursorless-dev/cursorless/pull/3210))

‎packages/app-vscode/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -738,7 +738,7 @@
738738
"additionalProperties": false
739739
},
740740
"cursorless.hatEnablement.shapes": {
741-
"markdownDescription": "Which shapes to enable. See the [docs](https://www.cursorless.org/docs/#shapes) if you're not sure which shape name corresponds to which hat shape.",
741+
"markdownDescription": "Which shapes to enable. See the [docs](https://www.cursorless.org/docs/user/targets#shapes) if you're not sure which shape name corresponds to which hat shape.",
742742
"type": "object",
743743
"order": 3,
744744
"properties": {

‎packages/app-web-docs/sidebarItemsGenerator.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ const items: (Group | string)[] = [
2020
"Actions",
2121
"Modifiers",
2222
"Scopes",
23+
"Targets",
2324
"Destinations",
2425
"Paired delimiters",
2526
],

‎packages/app-web-docs/src/docs/user/README.md‎

Lines changed: 12 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -4,202 +4,28 @@ slug: /
44

55
# Cursorless
66

7-
Welcome to Cursorless! You may find it helpful to start with the [tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs).
7+
Welcome to Cursorless! If you're new, start with the [tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs) or the [how-to guides](./how-to.md).
88

9-
This guide assumes you've already [installed Cursorless](installation.md).
9+
This guide assumes you've already [installed Cursorless](./installation.md).
1010

11-
Once you understand the concepts, you can pull up a cheatsheet for reference by saying either `"cursorless reference"` or `"cursorless cheatsheet"` with VSCode focused.
11+
Once you understand the concepts, you can pull up a cheatsheet by saying `"cursorless reference"` or `"cursorless cheatsheet"` with VSCode focused. You can return to these docs by saying `"cursorless docs"` or `"cursorless help"` within VSCode.
1212

13-
You can get back to these docs by saying `"cursorless docs"`, `"cursorless help"` within VSCode.
14-
15-
Note: If you'd like to customize any of the spoken forms, please see [Customization](customization.md).
13+
To change any spoken forms, see [Customization](./customization.md).
1614

1715
## Overview
1816

19-
Every cursorless command consists of an action performed on a target. For example, the command `"chuck bat"` deletes the token with a hat over the `b`. In this command, the action is `"chuck"` (delete), and the target is `"bat"`. There are no actions without at least one target.
20-
21-
![`"chuck bat"`](images/chuckBat.gif)
22-
23-
## Targets
24-
25-
There are two types of targets: primitive targets and compound targets. Compound targets are constructed from primitive targets, so let's begin with primitive targets.
26-
27-
### Primitive targets
28-
29-
A primitive target consists of a mark and one or more optional modifiers. The simplest primitive targets just consist of a mark without any modifiers, so let's begin with those
30-
31-
#### Marks
32-
33-
There are several types of marks:
34-
35-
##### Decorated symbol
36-
37-
This is the first type of mark you'll notice when you start using cursorless. You'll see that for every token on the screen, one of its characters will have a hat on top of it. We can refer to the given token by saying the name of the character that has a hat, along with the color if the hat is not gray, and the shape of the hat if the hat is not the default dot:
38-
39-
- `"air"` (if the color is gray)
40-
- `"blue bat"`
41-
- `"blue dash"`
42-
- `"blue five"`
43-
- `"fox bat"`
44-
- `"blue fox bat"`
45-
46-
The general form of this type of mark is:
47-
48-
`"[<color>] [<shape>] (<letter> | <symbol> | <number>)"`
49-
50-
Combining this with an action, we might say `"take blue air"` to select the token containing letter `'a'` with a blue hat over it.
51-
52-
###### Colors
53-
54-
The following colors are supported. Note that to target the default (gray) hat you don't need to specify a color.
55-
56-
| Spoken form | Color | Internal ID | Enabled by default? |
57-
| ---------------- | ------- | ------------ | ------------------- |
58-
| N/A | grey | `default` | ✅ |
59-
| `"blue"` | blue | `blue` | ✅ |
60-
| `"green"` | green | `green` | ✅ |
61-
| `"red"` | red | `red` | ✅ |
62-
| `"pink"` | pink | `pink` | ✅ |
63-
| `"yellow"` | yellow | `yellow` | ✅ |
64-
| `"navy"` | navy | `userColor1` | ❌ |
65-
| `"apricot"` | apricot | `userColor2` | ❌ |
66-
| `"user color 3"` | user 3 | `userColor3` | ❌ |
67-
| `"user color 4"` | user 4 | `userColor4` | ❌ |
68-
69-
You can enable or disable colors in your VSCode settings, by searching for [`cursorless.hatEnablement.colors`](vscode://settings/cursorless.hatEnablement.colors) and checking the box next to the internal ID for the given shape as listed above. To navigate to your VSCode settings, either say "show settings", or go to File --> Preferences --> Settings.
70-
71-
You can also tweak the visible colors for any of these colors in your VSCode settings, by searching for [`cursorless.colors`](vscode://settings/cursorless.colors) and changing the hex color code next to the internal ID for the given shape as listed above. Note that you can configure different colors for dark and light themes. See our [visual accessibility guide](visual-accessibility.md) for more on visual accessibility.
72-
73-
If you find these color names unintuitive / tough to remember, their
74-
spoken forms can be [customized](customization.md) like any other spoken form
75-
in Cursorless. If you change a spoken form to be more than one syllable, you
76-
can change the penalty in the [`cursorless.hatPenalties.colors`](vscode://settings/cursorless.hatPenalties.colors) setting to the
77-
number of syllables you use, so that Cursorless can optimize hat allocation to
78-
minimize syllables.
79-
80-
###### Shapes
81-
82-
The following shapes are supported. Note that to target the default (dot) shape you don't need to specify a shape.
83-
84-
| Spoken form | Shape | Internal ID | Enabled by default? |
85-
| ----------- | ------------------------------------------------------------------ | ------------ | ------------------- |
86-
| N/A | ![Default](../../../../../resources/images/hats/default.svg) | `default` | ✅ |
87-
| `"bolt"` | ![Bolt](../../../../../resources/images/hats/bolt.svg) | `bolt` | ❌ |
88-
| `"curve"` | ![Curve](../../../../../resources/images/hats/curve.svg) | `curve` | ❌ |
89-
| `"fox"` | ![Fox](../../../../../resources/images/hats/fox.svg) | `fox` | ❌ |
90-
| `"frame"` | ![Frame](../../../../../resources/images/hats/frame.svg) | `frame` | ❌ |
91-
| `"play"` | ![Play](../../../../../resources/images/hats/play.svg) | `play` | ❌ |
92-
| `"wing"` | ![Wing](../../../../../resources/images/hats/wing.svg) | `wing` | ❌ |
93-
| `"hole"` | ![Hole](../../../../../resources/images/hats/hole.svg) | `hole` | ❌ |
94-
| `"ex"` | ![Ex](../../../../../resources/images/hats/ex.svg) | `ex` | ❌ |
95-
| `"cross"` | ![Crosshairs](../../../../../resources/images/hats/crosshairs.svg) | `crosshairs` | ❌ |
96-
| `"eye"` | ![Eye](../../../../../resources/images/hats/eye.svg) | `eye` | ❌ |
97-
98-
You can enable or disable shapes in your VSCode settings, by searching for [`cursorless.hatEnablement.shapes`](vscode://settings/cursorless.hatEnablement.shapes) and checking the box next to the internal ID for the given shape as listed above. To navigate to your VSCode settings, either say "show settings", or go to File --> Preferences --> Settings.
99-
100-
If you find these shape names unintuitive / tough to remember, their
101-
spoken forms can be [customized](customization.md) like any other spoken form
102-
in cursorless. If you change a spoken form to be more than one syllable, you
103-
can change the penalty in the [`cursorless.hatPenalties.shapes`](vscode://settings/cursorless.hatPenalties.shapes) setting to the
104-
number of syllables you use, so that cursorless can optimize hat allocation to
105-
minimize syllables.
106-
107-
##### `"this"`
108-
109-
The word `"this"` can be used as a mark to refer to the current cursor(s) or selection(s) as a target. Note that when combined with a modifier, the `"this"` mark can be omitted, and it will be implied.
110-
111-
- `"chuck this"`
112-
- `"take funk this"`
113-
- `"pre funk"`
114-
- `"chuck line"`
115-
116-
Note that if you say `"this"` with an empty selection, it refers to the token containing your cursor.
117-
118-
##### `"that"`
17+
Every Cursorless command consists of an action performed on a target. For example, `"chuck bat"` deletes the token with a hat over the `b`: `"chuck"` is the action and `"bat"` is the target.
11918

120-
The word `"that"` can be used as a mark to refer to the target of the previous cursorless command.
19+
![`"chuck bat"`](./images/chuckBat.gif)
12120

122-
- `"pre that"`
123-
- `"round wrap that"`
124-
125-
##### `"row <number>"`
126-
127-
The word `"row"` followed by a number can be used to refer to a line by its line number. Note that the line numbers are modulo 100, meaning that you only say the last two digits of the line number. Also note that the line must be visible within the viewport.
128-
129-
- `"chuck row twenty four"`
130-
- `"post row eighty nine"`
131-
- `"pour row eleven"`
132-
133-
##### `"up <number>"` / `"down <number>"`
134-
135-
The word `"up"` or `"down"` followed by a number can be used to refer to the line that is `<number>` lines above or below the cursor. The line may be outside of the viewport. In the case of multiple selections, this mark only refers to the line relative to the primary selection. You can turn on relative line numbers in the VSCode settings to make these marks easier to use.
136-
137-
- `"copy up one"`
138-
- `"comment down two"`
139-
140-
#### Modifiers
141-
142-
Modifiers change a target's extent or interpretation. See the [modifier reference](./modifiers/README.md) for the available modifiers and their detailed behavior.
143-
144-
Scopes expand a target to a containing text or syntax-tree structure. See the [scope reference](./scopes/README.md) for the available scopes, and use the [scope visualizer](./scope-visualizer.md) to explore the scopes supported in your code.
145-
146-
### Compound targets
147-
148-
Individual targets can be combined into compound targets to make bigger targets or refer to multiple selections at the same time.
149-
150-
#### Range targets
151-
152-
A range target uses one primitive target as its start and another as its end to form a range from the start to the end. For example, `"air past bat"` refers to the range from the token with a hat over its 'a' to a token with a hat over its 'b'.
153-
154-
Note that if the first target is omitted, the start of the range will be the current selection(s).
155-
156-
- `"take [blue] air past [green] bat"`
157-
- `"take past [blue] air"`
158-
- `"take funk [blue] air past [blue] bat"` (note end of range inherits `"funk"`)
159-
- `"take funk [blue] air past token [blue] bat"`
160-
- `"take past end of line"`
161-
- `"take past start of line"`
162-
- `"take [blue] air past end of line"`
163-
164-
eg:
165-
`take blue air past green bat`
166-
Selects the range from the token containing letter 'a' with a blue hat past the token containing letter 'b' with a green hat.
167-
168-
##### Vertical ranges
169-
170-
The `"slice"` range modifier is used to refer to multiple targets that are vertically aligned. It is commonly used with the `"pre"` action to add multiple cursors to the editor. Each cursor is inserted at the same column on each row requested within the command.
171-
172-
- `"pre <TARGET 1> slice past <TARGET 2>"`: Add cursors from the first target through to the second target's line(inclusive end)
173-
- `"pre <TARGET 1> slice <TARGET 2>"`: Shortened version of above `"slice past"` command
174-
- `"pre <TARGET 1> slice until <TARGET 2>"`: Add cursors until the second target's line(non-inclusive end)
175-
- `"pre <TARGET 1> slice between <TARGET 2>"`: Add cursors between first and second target's lines(non-inclusive start and end)
176-
177-
For example:
178-
179-
- `"pre air slice bat"`: Places cursors at the same position on every line (inclusive) between token with hat over the `a` and token with the hat over the `b`. The position will be the start of the token with a hat over the `a`
180-
- `"chuck tail air slice end of block"`: Delete the end of every line from air through the end of its non-empty line block.
181-
182-
##### `"every"` ranges
183-
184-
If the range target begins with `"every <scope>"`, eg `"take every line air past bat"`, then you will end up with one target for each instance of `<scope>` in the range. For example, `"post every line air past bat"` will put a cursor at the end of every line from the line containing the token with a hat over the letter `a` to the line containing the token with a hat over the letter `b`.
185-
186-
These `"every"` ranges also play nicely with exclusive ranges, eg `"take every funk air until bat"` will select every function starting from the function containing the token with a hat over the letter `a` up until, but not including, the function containing the token with a hat over the letter `b`.
187-
188-
#### List targets
189-
190-
In addition to range targets, cursorless supports list targets, which allow you to refer to multiple targets at the same time. When combined with the `"take"` action, this will result in multiple cursors, for other actions, such as `"chuck"` the action will be applied to all the different targets at once.
21+
## Actions
19122

192-
- `"take [blue] air and [green] bat"`
193-
- `"take funk [blue] air and [green] bat"` (note second target inherits `"funk"`)
194-
- `"take funk [blue] air and token [green] bat"`
195-
- `"take air and bat past cap"`
23+
An action determines what happens to a target. For example, `"chuck air"` removes the target, while `"take air"` selects it.
19624

197-
eg:
198-
`take blue air and green bat`
199-
Selects both the token containing letter 'a' with a blue hat AND the token containing 'b' with a green hat.
25+
See the [action reference](./actions/README.md) for the complete list of actions, syntax, behavior, and examples.
20026

201-
## Actions
27+
## Targets
20228

203-
Every Cursorless command combines an action with a target. The action determines what happens to the target. For example, `"chuck air"` removes the target, while `"take air"` selects it.
29+
A target identifies the text or position that a command acts on. Targets can refer to a single token or selection, a containing scope, a range, or a list of several targets.
20430

205-
See the [action reference](./actions/README.md) for the complete list of actions, syntax, behavior, and examples.
31+
See the [target guide](./targets.md) to learn how marks, modifiers, scopes, ranges, and lists combine to form targets. For detailed lookup, use the [modifier reference](./modifiers/README.md) and [scope reference](./scopes/README.md).

0 commit comments

Comments
 (0)