Setting up The Home Bookmark

ON the page on starting hlg, we learnt that calling hlg without any arguments brings up your home bookmark.

As to what that home bookmark is depends mainly with your settings. The next section gets into detail on setting a home bookmark.

A home bookmark is automatically called when no argument is passed to hlg. But then the bookmark needs to be set up beforehand.

hlg looks for your home bookmark in three places in this order:

  1. The home option in the configuration file (otherwise known as the main home bookmark),

  2. The default category’s home bookmark, and

  3. The built-in default home bookmark.

The main home bookmark

Setting up a category home bookmark by a * symbol works for each category that you have in your database.

But what happens if you have many categories? Which bookmark will be launched and used as the main home bookmark?

The answer lies in fiddling with the "home option in your configuration file."

To set a main home bookmark, you edit the "home" option in the configuration file.

We refer to this bookmark as the "main home bookmark" as it is given the first priority once set.

To do this, you have to provide not only the bookmark name, but also the category in which that bookmark is found.

We refer to this category as "home-linked category" throughout this guide to differentiate it from the "default category", hence:

  • A default category is the category that is always referred to by hlg for any bookmark called without a category name. This category will be considered the container of a bookmark called without a name.

  • A home-linked category is that category which may, or may not be, the default category. Its primary feature is that it is a category with the bookmark that must be opened when hlg is called without any argument.

  • In short, a home-linked category is that category that has the main home bookmark as set in the configuration file.

For example, if you have a category called "electronics", and a bookmark called "radios", you can set your home bookmark in the configuration file by doing this:

  1. First launch your configuration file with hlg --edit-configuration

  2. Then find the entry for the "home" option.

  3. Change it to look like this:

home = "electronics.radios"

In this instance, "electronics" is a home-linked category. It may not be your default category, but the fact that it has the "radios" bookmark that hlg must open when called without arguments is what makes it special.

In the event that you do not provide a category name to the bookmark name and enter it like this:

home = "radios"

hlg will look for the "radios" bookmark in the category which is set as your default.

In that case, your default category is also your home-linked category.

The disadvantage to setting a bookmark this way is that if you decide to change your default-category option to some other category without the referenced "radios" bookmark, this bookmark will not work.

So hlg will complain of not finding a bookmark called "radios" in the new default category and will not run.

If, on the other hand, you provide a fully-qualified main home bookmark name, then no matter how many times you change your default category, the bookmark will still resolve correctly.

Example of setting up the main home bookmark

To set the main home bookmark, do the following:

  • Launch hlg with the --edit-configuration option like this:

    hlg --edit-configuration

    or

    hlg -E

  • Find the "home" entry in the configuration file.

  • By default, it looks like this:

    home = "default.hi"

  • Delete the "default.hi" and type in the bookmark name you want, remembering to qualify it if it is not in the default category like this:

    home = "radios"

    or

    home = "electronics.radios"

  • Save the file and exit.

  • From now on, the set bookmark "radios" will be the main home bookmark, and "electronics" will be the home-linked category.

The default-category home bookmark

Another type of home bookmark is the category home bookmark.

In a bookmark file, you can indicate that a bookmark must be a home bookmark by appending a star or asterisk * to it.

If that bookmark file is set as your default category in the configuration file, then when you enter hlg ., this bookmark will be launched.

If you have not set the main home bookmark in the configuration file, hlg will look to the default category’s home bookmark. In that case:

The default category’s home bookmark will serve two purposes:

  • First as the category home bookmark, and

  • Act as the main home bookmark.

So you can type hlg without arguments or hlg . just to do the same thing.

While the "home" option may not be set in a configuration file, a "default-category" must always be set.

A home bookmark is one of the special bookmarks and the following must be kept in mind when assigning a "home" status to a bookmark in any category:

  • Only one bookmark in the category is allowed to attain this status. If more than one bookmark is marked as "home", hlg will refuse to run and prompt you to rectify this by simply having one bookmark marked as "home"

  • While other bookmarks can be deactivated, a home bookmark cannot be deactivated.

  • A home bookmark—​whether the main home bookmark or the category bookmark—​must not have a shortcut key. It does not make sense to assign a shortcut key for a bookmark you can simply launch with:

    hlg

    for the main home bookmark, or

    hlg .

    for the category home bookmark.

  • hlg will not run if you violate these conditions, and tell you of the error.

Example of setting a category home bookmark

An example of setting a bookmark as a category home bookmark is as follows:

hi* <https://hlg.access-computing.com/> :chromium
It is possible to have both a main home bookmark and a default-category home bookmark in one file. You mark the category home bookmark with a star, and then set the main home bookmark on another bookmark in that category file in the configuration file.

For example, the following two bookmarks are both in the default category but save different purposes: In the "electronics" bookmark file:

flashy-gadgets <https://example.com/gadgets>
technews* <https://techcrunch.com/>

In the `config.toml`[1] we have this entry:

home = "electronics.flashy-gadgets"

If we have set the "electronics" as our default-category, it means:

  • That the "electronics" category is both a default-category and a home-linked category;

  • It is default because we set it as the "default-category"

  • It is home-linked category because it is providing the "flashy-gadgets" bookmark which is launched by default by hlg when typed without arguments.

  • To launch the main home bookmark, which is the "flashy-gadgets" in our case, we type hlg without arguments; and

  • To launch the category home bookmark, we type hlg . This time it launches "technews" and not "flashy-gadgets" because "technews" has a star after its name.

  • If you delete the "home" option in the configuration file, then the "technews" becomes both the main home bookmark and the default home bookmark.

Do not set one bookmark as both the main home bookmark and the category home bookmark. hlg will refuse to start and indicates that it cannot find the main home bookmark. So make sure not to mark the main home bookmark with a star or to add any shortcut keys to it. A bookmark can only serve both purposes only because hlg did not find the main home bookmark, so uses the default-category’s home bookmark. You must not deliberately mark a bookmark as a category home bookmark and then enter it as the value to the "home" option in the configuration file.

The Built-in default Home Bookmark

In the event that your "home" option is not set in the configuration file and that your default-category has no bookmark with a star appended to it, then hlg will launch the Quick Start guide.

The HLG Quick Start Guide summarises the content of this guide and helps you quickly get started using hlg

This means that at any time, hlg will have some page to open when typed without arguments:

  1. First, check the home option in the configuration file;

  2. If that is not set or its entry is not there altogether, look for the default-category and use its home bookmark; or else

  3. When the default-category has no bookmark set as a home bookmark, hlg will launch the "Quick Start Guide"

So the hlg Quick Start Guide is the built-in home bookmark where you can learn how to quickly become productive with hlg without necessarily going through this manual.

The home bookmark is a powerful feature that you have to take advantage of when working with hlg

It saves time and help you quickly jump to your preferred bookmark in a short time. It functions more or less like the browser homepage.

1. The configuration file