3  Editing the Bookmarks

3.1 Understanding the bookmark entry

A bookmark entry is one line in a category file, with up to three parts:

name <location> :handler

The name and location are required; the handler is optional. This chapter covers all three. Chapter 5 covers everything you can add on top of a plain entry like this — comments, tags, and flags.

To add a bookmark from the shell:

hlg> :add-bookmark
New bookmark for the 'default' category, e.g. `guardian <@guardian.co.uk> :chrome`: news <@bbc.com>
Added to the 'default' category.

:add-bookmark is also available as :a or :ab. If you’re inside a subcategory when you run it, the new line is inserted directly into that subcategory’s own block, not appended to the end of the whole file.

To change an existing bookmark’s name, location, or handler all at once, pick it and retype its whole line freely:

hlg> :update
Which bookmark? news
New line: news <@bbc.com>

The current line comes pre-filled, ready to edit or replace outright — this is also how you rename a bookmark, since there’s no separate rename command. :update is also available as :u.

Every change made through the shell — adding, updating, or anything else in this manual — is checked in a disposable copy of your whole database before anything real is touched, so a mistake here never corrupts your actual bookmark file.

3.2 The name

A bookmark’s name is what you type to launch it — as a command in the shell, or as an argument on the command line.

  • It must be at least two characters long — a single character is reserved for shortcut keys.
  • It must start and end with an alphanumeric character.
  • It cannot contain any of: / . : ? + * $ #.
  • Its first letter’s case decides its scope, local or global — see Chapter 2.

3.3 The location

A location is written in angle brackets: <location-here>. It’s the field that actually matters most, since it decides both what the bookmark resolves to and what kind of bookmark it is.

3.3.2 Command locations

A command location doesn’t resolve to a resource — it runs something. It’s marked by a colon as the very first character inside the brackets:

  • A script file: <:analysis.py> runs the script named “analysis.py”.
  • A one-liner: <:!echo "Hello world!"> runs the command after the ! directly. A one-liner is the only kind of location allowed to contain embedded spaces, since it’s the only one that genuinely needs them.

A command location runs right there in your terminal, with its output visible exactly as if you’d typed it yourself — so if it hangs (a one-liner like <:!ping google.com> used to check for a connection, say, with no response coming back), pressing Ctrl-C interrupts it normally and hands you straight back to the hlg> prompt, or back to your own shell if you launched it directly from the command line.

3.4 The handler

The handler is the program that actually opens a bookmark’s location — your browser, an editor, a media player, whatever fits. It’s the third field, marked with a leading colon:

news <@bbc.com> :firefox

If you leave it out, hande infers a sensible default from the kind of location it is (a web address opens in your configured browser, and so on — see Chapter 7 for where that’s configured). You only need to set a handler explicitly when you want something other than the default.

To give an existing bookmark a handler, or change the one it has:

hlg> :add-handler
Which bookmark? news
New handler for 'news' (e.g. chrome): firefox
'news' now uses the 'firefox' handler.

:add-handler is also available as :ah. If the bookmark already has a handler, you’ll be asked to confirm before it’s replaced.