Assigning Shortcut keys

Except for the home bookmark and the favorite or starred bookmark, you can choose to assign a shortcut key to any bookmark. This is the key that will be used to launch the bookmark with a single keystroke.

Before assigning a bookmark, though, you have to decide whether the keystroke you want to assign will be a category or global in scope.

A category shortcut only works for the bookmarks in the given category, while
A global shortcut key will work throughout the database across all the categories.
Choose whether the key you want to assign is the first character of the bookmark name or you want to use any key.
A bookmark can only have one shortcut key.
So before assigning a key, decide whether the key is to be category or global in scope.
A home bookmark—whether the main or category—must not have a shortcut key.

Category shortcuts

A category shortcut key is created by either,

Placing an underscore symbol (_) before the name of the bookmark, or
Placing the desired key in the key assignment brackets.

A category shortcut is local to its category, which means that it only works within the given category.

This makes it possible to use the same keystroke in the other categories without problems.

Keys assigned in the default category can be passed directly to hlg without qualifying them with a category name.

As an example, we can set the bookmark, "itsfoss" to take us to the itsfoss site as follows:

_itsfoss <https://itsfoss.com/>

This will set the i key as its shortcut key as we had prefixed the bookmark name with the underscore.

So if "itsfoss" is in the default category, we can simply type:

hlg i

But sometimes, we may want to use the i for some other bookmark. Also putting the underscore as the prefix of a bookmark may be restrictive: we can only assign the first character of the bookmark as its shortcut key.

So we decide to use the letter s as the shortcut key. The problem is that s is not the first character to the "itsfoss" bookmark.

We have to use the key assignment brackets or KAB for short. Key assignment brackets are denoted by a pair of parentheses attached as a suffix to the bookmark name.

The advantage with the KAB approach is that you are not restricted to assigning keys that are part of the bookmark name:

You can use any key as a shortcut key; and
The Key assignment brackets are the only way to assign global shortcut keys.

So for our example of “itsfoss”, to use s, we have to do the following:

itsfoss(s) <https://itsfoss.com/>

Global shortcut keys

To assign global shortcut keys to a bookmark, you also choose whether to set its first character as its shortcut or any other character. Unlike the category keys though, you can only use key assignment brackets in either case.

To assign the first character of a bookmark name as a shortcut key, enter a colon by itself inside the key assignment brackets.
For example, to set the letter t of the “techcrunch” bookmark as a global shortcut, we will do it like this:
```
techcrunch(:) <https://www.techcrunch.com> :brave
```
You will also notice that just like the use of the underscore at the category level, this is also too restrictive as we cannot choose any key as a shortcut key.
To set any other key other than the first character, after the colon type the preferred key.
For example, to use n as the shortcut key for the “techcrunch” bookmark, we would do it like this:
```
techcrunch(:n) <https://www.techcrunch.com/> :chromium
```
Remember that global shortcut keys are unique in the database, so throughout the database, make sure keys are not reassigned on other bookmarks as global shortcut keys.

Some notes on shortcut keys

Shortcut keys are case-sensitive. This makes a pool of the keys wide enough to have the same letter in different cases be used for two different bookmarks.
hlg will check for the existence of the typed key in the case it is typed in. So make sure that the case you use in assigning keys is the same you use when accessing a bookmark.
You can only use alphabetic and numeric characters as your shortcut keys.
Shortcut keys only work when they are assigned: which means that a key not assigned will not work for any bookmark.

Thus, even if we have a bookmark that starts with a certain character, hlg will not pick it simply because it starts with the typed character. Instead, it only works with single keystrokes for assigned characters.

So in the following set of bookmarks, w will not be used for the first bookmark, but for the second one:^[1]

wildlife-africa <https://wildlifeafrica.co.za/> :opera
encyclopaedia(w) <https://en.wikipedia.org/> :chromium

The “encyclopaedia” bookmark (which comes later) takes precedence over the key w because it is specifically assigned.

Do not assign a single key to more than one bookmark. Even if these bookmarks are assigned keys differently, hlg will complain of double-key assignments in the following scenario:

_news <https://cnn.com/>
gnu(n) <https://gnu.org/>

These two bookmarks are sharing the n key in the same category. hlg will see this and tell you to resolve key assignments before it can run.

This limitation also works for global shortcut keys:

Once the first character of the bookmark is set as a shortcut key through the (:), you cannot then reassign that key with the (:<key>) option.
For example, this is wrong as the letter d is assigned to two different bookmarks differently:
```
daily_news(:) <https://www.iol.co.za/dailynews>
readers_digest(:d) <https://www.rd.com/>
```

It is still possible to have one key assigned as a global key and as a category key. No key conflict takes place due to scoping rules.

In the following scenario:

gnu(:) <https://www.gnu.org>
engadget(g) <https://www.engadget.com/>

The two bookmarks are using the same keystroke, g without problem.

This has to do with scoping rules: “gnu” is using g in the global scope while “engadget” is using it in the category scope.
There will be no conflict of keys as hlg looks them up differently.

Despite the scoping rules, a bookmark cannot have two shortcut keys assigned to it. For example:

_readers_digest(:) <https://rd.com/> :brave

This will have hlg raise an error. Only assign one shortcut key to a bookmark at a time. This is why you have to decide beforehand whether the key to be assigned is at category or global level, but not both.

Inspecting keys

Sometimes you are no longer sure of which key is assigned to which bookmark. This is important before assigning a new key:

It may be tortuous to go through the whole bookmark file looking for key assignments;
You may have assigned a key six months ago and forgot about the assigned key.

You can have hlg help out with its key inspector:

For category shortcut keys, launch hlg with the --list-category-keys or simply -k (that is, lowecase k)
- hlg will show you a total number of bookmarks in the category and the number of bookmarks with shortcut keys.
- The list of the bookmarks will be presented along with their assigned keys.
To inspect assigned global keys,
- You launch hlg with the --list-global-keys or -K (that is the uppercase k)
- hlg will show you the total number of globally assigned keys;
- It will then show you:
  1. The assigned key;
  2. The bookmark name; and
  3. The category in which the bookmark is found.
You are advised to first inspect assigned keys before making new assignments.
Just remember that to work with any category, other than the default, to inspect its keys, you have to pass the name of the category on the command-line as an option like this:
```
$ hlg --list-category-keys --category electronics
```

or in its short form, with the options abbreviated:

$ hlg -kc electronics

to inspect the keys for the “electronics” category.

1. despite the fact that the first bookmark starts with the letter w and the second one starts with the letter e