Skip to content

About

Module for emacs to enhance its bookmarking system

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

102 Commits

Folders and files

Repository files navigation

bookmark-gt

https://melpa.org/packages/bookmark-gt-badge.svg

bookmark-gt extends the built-in bookmark.el and is fully compatible with it. When enabled, the standard bookmark keys run the corresponding bookmark-gt commands. Its bookmarks are ordinary bookmark.el records, thus a bookmark file written by bookmark-gt can still be read by the built-in bookmark package.

bookmark-gt is inspired by bookmark+.

bookmark-gt’s main features are:

  • tags, including default tags computed from the location being bookmarked;
  • several bookmarks with the same name, distinguished by their destination;
  • a bookmark list buffer for searching, filtering and updating many bookmarks at once;
  • bookmarks that follow their file when it is renamed inside Emacs;
  • a jump reader that works with marginalia, vertico, consult and orderless;
  • temporary bookmarks, which are never saved to disk;
  • auto-update bookmarks, which keep track of where you are in a long document;
  • bookmark types for URLs, Dired buffers, functions, keyboard macros and sequences of bookmarks.

A short demo: https://youtu.be/hitAyO8ArYM

Install

With use-package and a local checkout:

(use-package bookmark-gt
  :straight nil
  :load-path "~/.emacs.d/modules/bookmark-gt"
  :bind (("C-x r u" . bookmark-gt-create-url)  ; bookmark a URL
         ("C-x r U" . bookmark-gt-update))     ; move a bookmark to point
  :config
  (bookmark-gt-mode 1))

bookmark-gt requires Emacs 30.1 or later. While bookmark-gt-mode is on, the built-in bookmark keys are remapped to run the corresponding bookmark-gt functions:

KeyBuilt-inRuns
C-x r mbookmark-setbookmark-gt-create
C-x r bbookmark-jumpbookmark-gt-jump
C-x r lbookmark-bmenu-listbookmark-gt-list
M-xbookmark-deletebookmark-gt-delete
M-xbookmark-renamebookmark-gt-rename

Turning the mode off restores the original key bindings.

The following packages are optional; bookmark-gt uses them when they are installed and works without them:

  • marginalia adds tags, type and location to each candidate in the jump reader;
  • orderless enables the @type, +group and ;tag narrowing particles in the jump reader;
  • browser-gt is required only by bookmark-gt-browser-tabs-mode.

Which version is installed

M-x bookmark-gt-version shows the installed version followed by the Emacs version, which is the line to include in a bug report. With a prefix argument it inserts that text at point instead. From Lisp it returns the version string, which is also the value of the variable bookmark-gt-version.

Getting started

bookmark-gt-mode

bookmark-gt-mode is a global minor mode that turns on every bookmark-gt feature described in this manual. When bookmark-gt-mode is off, the built-in bookmark.el behaves as it does without bookmark-gt.

While bookmark-gt-mode is on, the following features are available:

  • bookmark-gt-create creates bookmarks. It prompts for the name with a suggestion derived from the location being bookmarked (not from the last bookmark you jumped to), already inserted as editable text, so RET accepts it and C-a C-k replaces it. It then prompts for tags, applies the same-name policy, and uses bookmark-gt’s Dired handler when the current buffer is a Dired buffer. Bookmarks whose names match bookmark-gt-auto-temp-names, such as org-capture-last-stored, are made temporary when they are stored.
  • Every jump increments the bookmark’s visits count and sets its last-visited time. This information is used to enable a most-recently-used ordering of the bookmarks.
  • bookmark-gt-jump replaces bookmark-jump. It lists the most recently used bookmarks first, shows marginalia annotations and accepts orderless narrowing particles (such as ;TAG, @TYPE and +GROUP) when those packages are loaded, and lets you filter by tag while it is reading (M-t adds a tag filter, M-d removes the last one, M-D removes all of them).
  • You can specify how a file bookmark is opened. A file bookmark whose filename matches a regexp in bookmark-gt-file-type-handlers is opened by the function associated with that regexp instead of by find-file.
  • When a file is renamed with rename-file (which Dired’s R uses), every bookmark pointing at the old name is changed to point at the new one.
  • Temporary bookmarks exist only for the current Emacs session. They appear in the list buffer and the jump reader like any other bookmark, but they are never written to the bookmark file, and creating them never causes the file to be saved. Making a temporary bookmark permanent, or a permanent one temporary, is a change to the bookmark file like any other.

Turning the mode off removes every advice and hook it installed. The three optional modes below are turned on and off separately.

Optional modes

The following global minor modes are off by default.

bookmark-gt-auto-update-mode

A bookmark with the auto-update property is moved to the current position of the buffer that visits its file, which is useful for keeping your place in a book, a long document or a PDF. The position is updated when Emacs has been idle for bookmark-gt-auto-update-interval seconds (default 60), when the buffer is killed, when the window configuration changes, and when the list buffer is opened or reverted.

To set or clear the property, press ^ in the list buffer (it acts on the marked rows, or on the row at point when none is marked), or use M-x bookmark-gt-auto-update-toggle. From Lisp, use bookmark-gt-auto-update-set.

bookmark-gt-default-tags-mode

This mode proposes tags for a new bookmark based on its location. The proposed tags become the initial input of the tag prompt, where you can edit or clear them (see Tag reader). The tags come from bookmark-gt-default-tags, which can be a single tag, a list of tags, or a function of the newly created record that returns either:

(setq bookmark-gt-default-tags "work")                    ; one tag
(setq bookmark-gt-default-tags '("work" "urgent"))        ; several tags
(setq bookmark-gt-default-tags                            ; a function
      (lambda (record)
        (cond ((string-prefix-p "/proj/" (bookmark-gt-filename-of record))
               '("project"))
              ((eq (bookmark-gt-handler-type record) 'url)
               '("web"))
              (t nil))))

If the function signals an error, bookmark-gt shows a warning and proposes no tags. If bookmark-gt-prompt-for-tags-flag is nil, there is no tag prompt and the proposed tags are stored as they are.

bookmark-gt-browser-tabs-mode

This mode shows the tabs open in your browser as temporary URL bookmarks. It requires browser-gt to be installed and connected to the browser.

The tab bookmarks are rebuilt each time they are about to be shown: when bookmark-gt-jump starts reading, when the list buffer is opened or reverted with g, when the mode is turned on while a browser is connected, and when you run M-x bookmark-gt-browser-tabs-refresh. There is no timer. A refresh never prompts for tags and never causes the bookmark file to be saved, since tab bookmarks are temporary.

Making a tab bookmark permanent with T in the list buffer turns it into an ordinary URL bookmark that is saved like any other; because the tab is still open, the next refresh adds a temporary bookmark for it again. Deleting a tab bookmark deletes only the bookmark, and the next refresh adds it again while the tab is open; as with every bookmark-gt bookmark, deleting it does not affect what it points to. Turning the mode off deletes the tab bookmarks it created, and leaves alone the bookmarks of other packages that use browser-gt.

A tab bookmark’s visits and last-visited count the jumps bookmark-gt made to it, not the browser’s own record of when the tab was used, so a tab you have never jumped to is listed after those you have. These values are kept when the tab bookmarks are rebuilt, matched by browser name and tab id, but they are lost when the browser restarts, when the mode is turned off, and when Emacs exits.

Two options select which tabs are shown: bookmark-gt-browser-tabs-browsers lists the browser clients to ask (nil asks every connected browser), and bookmark-gt-browser-tabs-filter is nil to keep every tab, a regexp that the tab’s URL must match, or a predicate called with the tab.

User interface

The *Bookmarks-gt List* buffer

M-x bookmark-gt-list opens the list buffer. It is a tabulated-list-mode buffer, so you can sort by clicking a column header or with S on a column; s cycles the sort through all the columns, including the marker columns.

Columns

ColHeaderMeaning
0** if the row is marked with m, D if it is flagged for deletion with d
1^^ if the bookmark has the auto-update property
2tt if the bookmark is temporary
3NameThe name, truncated at bookmark-gt-list-name-width (default 32)
4TypeFile, URL, EWW, Dired, Info, Org, PDF, BrowserTab, Function, Sequence, Kmacro, BkView, …
5GroupWeb, File, Doc, Code, Media or Other
6TagsThe tags, separated by commas, truncated at bookmark-gt-list-tags-width (default 24)
7LocThe file name, or the URL for a bookmark without a file

The name of a bookmark whose file no longer exists is shown struck through (face bookmark-gt-face-missing-file). Remote (Tramp) files are not checked.

Keys

KeyAction
RETJump
o, C-oJump in another window
TABShow the bookmark in another window, leaving point in the list
mMark the row (with a numeric prefix, mark N rows)
uUnmark the row
UUnmark every row
dFlag the row for deletion
xDelete the flagged rows, after confirmation
^Toggle auto-update (selection)
TToggle temporary (selection)
t eEdit tags as a comma-separated list, adding and removing in one prompt (selection)
t aAdd tags, one per prompt; empty RET or M-RET ends (selection)
t rRemove tags, completing over the tags present (selection)
rRename
RRelocate: change the file name or URL
aEdit the annotation
iShow the record
HShow or hide temporary bookmarks in this buffer
/Filter by type, group, tag or name regexp, or remove the filters
sCycle the sort column
VReset the view: sort by name, no filters, default display of temporary bookmarks
gRefresh browser tabs and auto-update positions (if those modes are on), then redraw
C-x C-sSave the bookmark file
qQuit

Marks belong to the bookmark, not to the line, so they are kept when the buffer is sorted, reverted or redrawn after a change.

Acting on several bookmarks at once

The commands marked selection in the table act on every row marked with m, or on the row at point when no row is marked. For example, after marking a few rows, t a adds the tags you type to all of them, t r removes tags from all of them, and t e replaces their tag lists. The prompts say how many bookmarks are affected, and t e and t r offer every tag that appears on any of the marked bookmarks.

T and ^ set the same value on every marked row: they turn the property on for all of them, unless all of them already have it, in which case they turn it off for all of them. A mixed selection therefore becomes uniform on the first press.

A selection command clears the marks when it finishes. If you end a tag prompt without typing anything, nothing changes and the marks are kept.

Commands act only on the rows the buffer shows. A marked row that is hidden by a filter or by H is left alone and keeps its mark, so you can apply a command to part of a selection by narrowing the view first. Tags offered by t e and t r, and the value a toggle sets, are also computed from the visible rows only. If every marked row is hidden, the command stops with “No selected bookmarks in this view” instead of acting on the row at point.

The deletion flag D is separate from the selection: x is the only command that uses it, and the selection commands ignore it. x deletes only the flagged rows the buffer shows, and refuses when all of them are hidden.

r, R, a, i and the jump commands act on the row at point and ignore the marks.

Keeping the view

The sort column, the display of temporary bookmarks and the active filters are kept when you call bookmark-gt-list again in the same session. To keep them across Emacs sessions as well, set bookmark-gt-list-persist-state:

(setq bookmark-gt-list-persist-state t)

The view is then saved to bookmark-gt-list-state-file (by default (locate-user-emacs-file "bookmark-gt-list-state")) after every change to it and when Emacs exits, and read the next time the list buffer is created. Marks and the position of point are not saved. V (bookmark-gt-list-reset-view) restores the default view.

Jumping: bookmark-gt-jump

bookmark-gt-jump replaces bookmark-jump, and C-x r b runs it while bookmark-gt-mode is on. It reads the bookmark with completing-read, so it works with any completion interface, such as vertico or the default *Completions* buffer. When orderless is loaded, three particles narrow the candidates:

  • @TYPE keeps bookmarks of TYPE (@URL, @Info, @PDF, …);
  • +GROUP keeps bookmarks in GROUP (+Web, +File, +Doc, …);
  • ;TAG keeps bookmarks that have TAG.

Particles are case-sensitive unless completion-ignore-case is non-nil, so by default you type the names as they are displayed.

While reading, M-t adds a tag filter and restarts the read, showing the active filters in the prompt; M-d removes the most recent filter, and M-D removes all of them.

The annotation

With marginalia loaded, each candidate shows its tags, its type and its location (the file name or the URL). The annotation starts at the first multiple of 10 columns past the widest candidate name, and names are truncated at bookmark-gt-jump-name-max-width (default 58), so the annotation always starts at the same column during one read. bookmark-gt positions the annotation itself, so marginalia-align and marginalia-align-offset do not apply to it.

The location takes the columns the name, tags and type leave free, so it is wider on a wide frame. Its width is limited by bookmark-gt-jump-location-max-width: an integer is a number of columns (default 100), a float is a fraction of marginalia-field-width as marginalia computes it for the current display (at most 80), and nil means no limit other than the free space. The limit keeps a location that is very long but not informative, such as a window configuration stored in a URL, from taking every free column. A file location is truncated on the left so that the file name stays visible, and a URL on the right so that the scheme and host stay visible.

marginalia-field-width itself does not limit these fields, because bookmark-gt gives marginalia the widths as column counts. As a result the annotation can be wider than the half of the window that marginalia normally allows.

Using bookmark-gt from Lisp

bookmark-gt provides an API to create custom bookmark jumping functions. The three entry points take keyword arguments only:

(cl-defun bookmark-gt-jump
    (&key bookmark display-function bookmarks-list bookmarks-filter
          sort-by preselect))

(cl-defun bookmark-gt-jump-other-window
    (&key bookmark bookmarks-list bookmarks-filter sort-by preselect))

(cl-defun bookmark-gt-jump-tagged
    (&key tag bookmark bookmarks-list bookmarks-filter sort-by preselect))
  • :BOOKMARK is a bookmark name or record to jump to without prompting.
  • :DISPLAY-FUNCTION is called with the target buffer, as in bookmark-jump.
  • :BOOKMARKS-LIST is the alist to choose from (default bookmark-alist), and :BOOKMARKS-FILTER is a predicate that a record must satisfy to be offered. Both are ignored when :BOOKMARK is given.
  • :SORT-BY is mru (most recently visited first), visits (most visited first) or nil (the order of the list). It defaults to bookmark-gt-jump-default-sort, which is mru.
  • :PRESELECT is a positive integer N. When vertico is in use, the reader starts with the N-th candidate selected, so with MRU sorting :preselect 1 selects the bookmark you visited before the last one.
  • :TAG (for bookmark-gt-jump-tagged) is the tag filter the read starts with.
;; Jump to a known bookmark
(bookmark-gt-jump :bookmark "my-bookmark")

;; Display the target in another frame
(bookmark-gt-jump :display-function #'switch-to-buffer-other-frame)

;; Choose among file bookmarks only
(bookmark-gt-jump :bookmarks-filter #'bookmark-gt-handler-file-p)

;; Choose among file bookmarks tagged "urgent"
(bookmark-gt-jump-tagged :tag "urgent"
                         :bookmarks-filter #'bookmark-gt-handler-file-p)

bookmark-gt-jump-candidate-format-function (default bookmark-gt-jump-candidate-default) builds each candidate string from a record. A replacement must put the record in the bookmark-gt-record text property and the name in bookmark-gt-name, and may put the narrowing particles in bookmark-gt-particles; see the default function’s docstring. Without bookmark-gt-record, the reader has to find the selected bookmark by name, and cannot tell apart two bookmarks with the same name.

Bookmark types besides files

URL bookmarks: bookmark-gt-create-url

M-x bookmark-gt-create-url prompts for a URL (defaulting to the URL at point), a name and tags. It can also be called from Lisp:

(bookmark-gt-create-url "https://example.org" "Example" '("web" "reference"))

Jumping opens the URL with browse-url, so it follows your browse-url-browser-function and browse-url-handlers settings.

Dired bookmarks

The built-in Dired has no bookmark handler, so bookmark-gt provides bookmark-gt-handler-dired-jump. A Dired bookmark records, and its jump restores:

  • dired-directory, so plain directories, wildcards such as /tmp/*.el and explicit file lists are all restored as they were;
  • dired-marked, the marked files and their mark characters;
  • dired-subdirs, the subdirectories inserted with i;
  • dired-hidden-dirs, the subdirectories hidden with $;
  • dired-switches, the ls switches in effect.

These keys are the ones bookmark+ uses (bmkp-jump-dired), so Dired bookmarks can be moved between the two packages in either direction. Records with bookmark+’s handler are classified as Dired, and M-x bookmark-gt-migrate-from-bookmark-plus converts them to bookmark-gt’s handler (see Migrating from bookmark+).

Virtual Dired

A bookmark created in a virtual Dired buffer (M-x dired-virtual, or V in dired-x) also stores the buffer’s listing under dired-listing and sets dired-virtual. Jumping recreates the same buffer from the stored listing, even if the directory no longer exists. bookmark+ does not do this; it opens the directory as an ordinary Dired buffer.

Because the bookmark file is read whole at startup and written whole on every save, the listing is limited to bookmark-gt-dired-virtual-max-size bytes (default 524288, that is 512 KB). Creating a bookmark in a larger virtual Dired buffer is an error.

Function bookmarks: bookmark-gt-create-function

A function bookmark stores a function (a symbol or a lambda) under the function key, and jumping calls it. M-x bookmark-gt-create-function prompts for the name and the command. From Lisp:

(bookmark-gt-create-function "rebuild" #'my-project-rebuild)
(bookmark-gt-create-function "flip-theme" (lambda () (my-toggle-theme)))

Keyboard-macro bookmarks: bookmark-gt-create-kmacro

A keyboard-macro bookmark stores a vector of key events under the kmacro key, and jumping replays it with execute-kbd-macro, using the prefix argument as the repeat count.

M-x bookmark-gt-create-kmacro offers your named keyboard macros, plus [last-kbd-macro] for the most recently defined one, which is the default when it exists; it is an error if there is no macro at all. A named macro is a symbol whose function definition is a string or vector, or that has a kmacro property, as created by M-x kmacro-name-last-macro. From Lisp:

(bookmark-gt-create-kmacro "type-hi" [?h ?i])
(bookmark-gt-create-kmacro "type-abc" "abc")   ; parsed by `read-kbd-macro'

bookmark+ stores keyboard macros as function bookmarks. bookmark-gt gives them a type of their own so that the list buffer and the jump reader can distinguish them, which means a bookmark+ macro bookmark is shown as a Function bookmark in bookmark-gt.

Sequence bookmarks: bookmark-gt-create-sequence

A sequence bookmark jumps to a list of bookmarks in order. M-x bookmark-gt-create-sequence prompts for its name and then for existing bookmarks, one per prompt, until you enter an empty input. From Lisp:

(bookmark-gt-create-sequence "morning-workspace"
                             '("inbox" "todo.org" "calendar"))

The members are stored under the sequence key. A member name that matches exactly one bookmark is replaced by that bookmark’s id (see Record identity), so the sequence still works after the member is renamed.

File-type handlers

bookmark-gt provides a way to specify how to open bookmarks. bookmark-gt-file-type-handlers maps file-name regexps to bookmark handler functions. Jumping to a file bookmark whose filename matches one of the regexps calls the associated function with the record, instead of visiting the file. The first matching entry is used. For example, to open PDF and video files with macOS’s open command:

(defun my-mac-open (bookmark)
  "Open BOOKMARK's file with macOS's `open' command."
  (call-process "open" nil 0 nil
                (bookmark-prop-get bookmark 'filename)))

(setq bookmark-gt-file-type-handlers
      '(("\\.pdf\\'"               . my-mac-open)
        ("\\.\\(mp4\\|mkv\\)\\'"   . my-mac-open)))

View bookmarks

It is possible to create a bookmark to the current state of the *Bookmarks-gt List* buffer.

A view bookmark stores the list buffer’s filters, sort column and display of temporary bookmarks (under the filters, sort-key and show-temp keys). To create one, set up the list buffer the way you want it and run M-x bookmark-gt-create there. Jumping to it opens the list buffer with that view. Marks and the position of point are not stored.

Creating and changing bookmarks

Tag reader

bookmark-gt-tags-read asks for tags one at a time, completing over the tags already in use, most recently used first. Each non-empty RET adds a tag and asks for the next; an empty RET finishes, and M-RET adds the current input and finishes. The prompt shows the tags entered so far, as in Tags [foo,bar] (M-RET or empty RET to finish):.

The creation commands (bookmark-gt-create, bookmark-gt-create-url, bookmark-gt-create-function, bookmark-gt-create-kmacro and bookmark-gt-create-sequence) compute the tags of a new bookmark in three steps:

  1. if bookmark-gt-default-tags-mode is on, the default tags;
  2. if bookmark-gt-prompt-for-tags-flag is non-nil (the default), the tag reader, starting with the tags from step 1;
  3. the functions on bookmark-gt-create-tag-reader-hook, which receive the tags from step 2.

These steps run after the name has been accepted, so a name that bookmark-gt-allow-same-name-bookmarks refuses is reported before you are asked for tags.

From Lisp, the TAGS argument of a creation command is either a list of tags, which is stored as given with no prompt, or t, which runs the three steps (interactive calls pass t):

(bookmark-gt-create-url "https://example.org" "example" '("web"))  ; stores ("web")
(bookmark-gt-create-url "https://example.org" "example" t)         ; runs the steps

bookmark-gt-create-non-file, which creates a record with a given handler, never runs these steps; the record gets the tags entry of its PROPS argument, if any.

Bookmarks that share a name

A bookmark name is a label, not an identifier, so several bookmarks may share one, such as a todo bookmark in each of several projects. Two bookmarks with the same name and the same destination, however, are almost always a mistake. bookmark-gt-allow-same-name-bookmarks decides whether bookmark-gt-create may reuse a name:

ValueCreating with a name already in use
neverrefused
different-destination (default)allowed if the two point at different files or URLs, refused if at the same
alwaysallowed

The destination is the file or URL, not the position, so two bookmarks at different places in one file have the same destination. A refused name is an error that names the conflicting bookmark; the new bookmark is not stored under a modified name. If you meant to move the existing bookmark, use bookmark-gt-update, as the error message suggests.

The names in bookmark-gt-unique-names (by default those of org-capture and org-refile) always identify a single bookmark, whatever the setting. For handlers in bookmark-gt-unique-name-handlers, storing a bookmark with the name of an existing bookmark of the same handler replaces it.

Telling them apart

Bookmarks that share a name are displayed with a suffix, as in todo and todo<2>, the way Emacs names buffers. The suffix is only displayed: the bookmark file contains the name you typed, so deleting or renaming one of the bookmarks renumbers the others.

Loading a file that breaks the setting

A bookmark file can contain names the setting forbids, if it was written by the built-in bookmark package, by bookmark-gt with a different setting, or on another machine. When such a file is loaded, the bookmarks the setting forbids are left out of bookmark-alist, and a warning shows each of them in full, since until the file is saved the warning is the only other copy. The first bookmark with a given name is always kept, and under the default setting a later one is kept if it points somewhere no kept bookmark does. The same check runs when the list buffer is opened or reverted and when the jump reader starts, so it also catches bookmarks created some other way, such as by bookmark-set called from Lisp.

The bookmarks left out are still in the file, and they are removed from it the next time it is saved. To keep them, set the option to always and load the file again before saving. Leaving them out does not by itself cause the file to be saved.

When you expect two bookmarks and see one

First count the bookmarks with that name:

(seq-filter (lambda (r)
              (equal (substring-no-properties (car r)) "todo"))
            bookmark-alist)

If there are two, the list buffer is not showing one of them, either because a filter is active (filters can be kept from an earlier session; V removes them), or because one of them is temporary and temporary bookmarks are hidden (H shows them; T is different, it makes the bookmark at point temporary or permanent).

If there is one, the second was never stored: either bookmark-gt-create refused it, with an error at the time, or it was left out when the file was loaded, with a warning listing it (see the previous section).

Which command acts on which bookmark

The built-in bookmark-get-bookmark looks a name up with assoc, so the built-in commands act on the first bookmark with that name. bookmark-gt’s commands work with records: given a record, they act on it, and given a name that several bookmarks share, they ask which one. Selecting the second of two todo bookmarks in the jump reader or the list buffer therefore jumps to, renames, relocates or deletes that bookmark, and the jump counts as a visit to it.

While bookmark-gt-mode is on, M-x bookmark-delete, bookmark-rename, bookmark-jump and bookmark-set run bookmark-gt’s versions. The functions themselves are not changed, because packages depend on their behavior: org-capture and org-refile, for example, store a bookmark under a fixed name each time and rely on bookmark-set replacing the previous one. From Lisp, bookmark-gt-jump-record, bookmark-gt-rename-record and bookmark-gt-delete-record take a record, and signal an error when given a name.

Record identity

Each bookmark has a bookmark-gt-id, a symbol assigned when the bookmark is created; bookmarks that lack one (for example, because another package wrote them) get one when the bookmark file is loaded, the list buffer is drawn or the jump reader starts. The id lets a reference outlive a rename, which is why sequence bookmarks store their members by id. You never type an id; it appears only in i in the list buffer and in the bookmark file, and the built-in bookmark package ignores it. A file copied between machines can contain the same id twice; a bookmark is looked up by its id when it has one, and by its name otherwise.

Changing an existing bookmark

CommandChangesRun it from
bookmark-gt-updatewhere it points: to pointthe new location
bookmark-gt-relocatewhere it points: to a file or URL you typeanywhere
bookmark-gt-renameits nameanywhere

Each command takes a bookmark record, name or id, and prompts when given none. Given a name that several bookmarks share, it asks which one.

bookmark-gt-update

bookmark-gt-update records the current location and stores it in the existing bookmark. The bookmark keeps its name, id, tags, annotation, creation time and visit history; everything that describes where it points is replaced, so data left from its previous type (a PDF page, an Org heading id, Dired marks) is removed. It asks for confirmation before changing the bookmark’s type, for example from PDF to Org. It cannot update URL, function, keyboard-macro or sequence bookmarks, since they have no location in a buffer; use bookmark-gt-relocate for those.

bookmark-gt-relocate

bookmark-gt-relocate asks for the new target instead of recording the current location, so it works without visiting the target. For a file bookmark it reads a file name, starting from the current one, and keeps the position, since the usual reason to relocate is a file that was moved. For a URL bookmark, including a browser-tab bookmark, it reads a URL. Other bookmarks cannot be relocated. It refuses a target of a different type (an Org file for a PDF bookmark, for example), because the bookmark’s handler could not open it; use bookmark-gt-update to change the type. In the list buffer, R relocates the bookmark at point.

bookmark-gt-rename

bookmark-gt-rename renames the bookmark you select, not the first one with its name. The new name is checked the same way as a new bookmark’s name (see Bookmarks that share a name). In the list buffer, r renames the bookmark at point.

Deleting

M-x bookmark-gt-delete deletes the bookmark you select, not the first one with its name. If a sequence bookmark refers to it, the command tells you before deleting, since that reference will no longer work. In the list buffer, d flags rows and x deletes them.

Bookmarks in the buffer

Cycling through a file’s bookmarks

M-x bookmark-gt-cycle-next and M-x bookmark-gt-cycle-prev move point to the next or previous bookmark in the current file, ordered by position, wrapping around at either end and showing the bookmark’s name. Bookmarks without a numeric position, such as Dired bookmarks, are skipped. Cycling does not depend on highlighting being on. Example bindings:

(global-set-key (kbd "C-c n") #'bookmark-gt-cycle-next)
(global-set-key (kbd "C-c p") #'bookmark-gt-cycle-prev)

Highlighting

While bookmark-gt-mode is on, each bookmark is highlighted in the buffers that visit its file, using bookmark-gt-face-highlight (which inherits from hl-line). A bookmark at a point highlights its line, and a region bookmark highlights the lines of its region; moving the mouse over the highlight shows the bookmark’s name.

Highlights are added when a file is visited and updated after each change to a bookmark. A bookmark without a numeric position, such as an Org heading bookmark, is highlighted at the place its last jump arrived, once you have jumped to it. Highlights are not saved, and they are removed when the mode is turned off. To turn them off while keeping the mode on, set bookmark-gt-highlight-enable to nil.

Region bookmarks

If the region is active when you run bookmark-gt-create, the bookmark stores the region and selects it again after a jump. The record stores the start in position and the end in end-position, plus bookmark-gt-region-context-size characters (default 40) before and after the end, under front-context-region-string and rear-context-region-string, which locate the end again if the text has changed. These keys are the ones bookmark+ uses; the built-in bookmark package ignores them and jumps to position. To neither store nor restore regions, set bookmark-gt-use-region to nil.

Tracking

Visits

Every jump increments the bookmark’s visits count and sets its last-visited time, which is what the jump reader’s mru and visits sorting use. These changes do not mark the bookmark file as modified, so jumping never causes a save; they are written the next time the file is saved for another reason.

File renames

While bookmark-gt-mode is on, renaming a file with rename-file, which Dired’s R also uses, changes every bookmark that points at the old file name to point at the new one. Renaming a directory changes only bookmarks that point at the directory itself, not at files inside it. Renames to a backup file name are ignored, because Emacs renames a file to its backup name when it saves it, and the bookmark should stay with the file. To turn rename tracking off, set bookmark-gt-track-renames to nil.

Extending bookmark-gt

Handler registry

bookmark-gt-handler-alist maps each handler function to a description of its bookmark type:

(HANDLER . (:type TYPE-SYMBOL :name STRING :group GROUP-SYMBOL
            :face FACE :doc STRING))

Several handlers can share a type; URL bookmarks, for example, have three handler names. bookmark-gt registers file, URL, EWW, Dired, Info, Org, Org-roam (org-roam-gt), PDF, browser tab, Magit, Help, Image and EPUB (nov.el) bookmarks. To register a new handler, or another name for an existing type:

(bookmark-gt-handler-register
 '(my-custom-jump my-legacy-jump-handler)
 (list :type 'custom :name "Custom" :group 'other
       :face 'bookmark-gt-face-file
       :doc "My custom bookmark type."
       :preview #'my-preview-fn))   ; optional

The optional :preview function is what TAB in the list buffer calls with the record, inside save-selected-window; without it, TAB jumps to the bookmark in another window. A preview function lets you, for example, show a URL in EWW while RET still opens it in the external browser.

A handler that is not registered is classified automatically. If it has a bookmark-handler-type property, as bookmark-bmenu-list expects, that is its type name. Otherwise its name is used without the usual suffixes (-bookmark-jump-handler, -bookmark-jump, -jump-handler, --handle-bookmark), so foo-bookmark-jump is shown as type “Foo”. Either way, its group is other.

Each registered type has a predicate: bookmark-gt-handler-file-p, -url-p, -eww-p, -dired-p, -info-p, -org-p, -org-roam-p, -pdf-p, -browser-tab-p, -magit-p, -help-p, -image-p, -epub-p, -function-p, -sequence-p, -kmacro-p and -view-p, each equivalent to (eq (bookmark-gt-handler-type record) 'TYPE).

Group registry

Groups combine several types into one category, so that you can filter by “web” instead of by URL, EWW and browser tab separately. A bookmark’s group is computed from its handler’s registration and is not stored in the record.

SymbolNameTypes
webWeburl, eww, browser-tab
fileFilefile, dired
docDocinfo, org, org-roam, pdf, help, epub
codeCodemagit
mediaMediaimage
otherOthereverything else

bookmark-gt-group-alist holds the groups. To add one:

(bookmark-gt-group-register
 'science '(:name "Sci" :doc "Science and research bookmarks."))

The group is shown in the list buffer’s Group column, can be filtered with /, and is matched by the +GROUP particle in the jump reader. (bookmark-gt-handler-group RECORD) returns a record’s group.

Hooks and registries

  • bookmark-gt-create-name-reader-hook runs in bookmark-gt-create before the name prompt. Each function is called with the suggested name and the new record’s data, and can return a different suggestion; the first non-nil value is used.
  • bookmark-gt-create-tag-reader-hook is the last step of the tag computation (see Tag reader); it does not run in bookmark-gt-create-non-file. Each function is called with the record and the tags so far, and returns the tags passed to the next function.
  • bookmark-gt-record-changed-hook runs after every change to a bookmark, with the record and a symbol naming the change: create, update, relocate, rename, tags, temp, auto-update or delete.
  • bookmark-gt-jump-before-read-hook runs once each time bookmark-gt-jump, bookmark-gt-jump-other-window or bookmark-gt-jump-tagged is about to prompt (not when :BOOKMARK is given, and not again when a tag filter restarts the read). Use it to rebuild bookmarks that must be current when the reader shows them; bookmark-gt-browser-tabs-mode adds bookmark-gt-browser-tabs-refresh to it.
  • bookmark-gt-list-before-read-hook runs when the list buffer is opened or reverted, before the rows are drawn. bookmark-gt-browser-tabs-mode adds bookmark-gt-browser-tabs-refresh to it, and bookmark-gt-auto-update-mode adds bookmark-gt-auto-update-tick.
  • bookmark-gt-session-only-props lists record keys whose values are valid only while another program is running, such as a browser tab id. When a temporary bookmark is made permanent, these keys are removed from it, so they are never saved. bookmark-gt-browser-tabs-mode registers the three keys its tab bookmarks use.
  • bookmark-gt-filter-alist and bookmark-gt-sort-alist hold the list buffer’s filters (for /) and sort orders.

Compatibility

Data compatibility with bookmark+

bookmark-gt reads and writes these record keys with the same meaning as bookmark+, so either package can read the other’s bookmark file:

KeyMeaning
tagsList of tag strings
bmkp-tempThe bookmark is temporary
auto-updateThe position is kept up to date
visitsNumber of visits
last-visitedTime of the last visit
createdTime of creation
last-modifiedTime of the last change

Two differences are handled when reading. bookmark+ stores the string " - no file -" in filename for bookmarks without a file, which bookmark-gt-filename-of treats as no file name; bookmark-gt omits filename for such bookmarks. bookmark+ stores a URL under location, while bookmark-gt uses url; bookmark-gt-url-of reads both. bookmark-gt adds one key of its own, bookmark-gt-id (see Record identity), which bookmark+ and the built-in bookmark package ignore.

Migrating from bookmark+

Bookmarks saved by bookmark+ name handler functions that exist only when bookmark+ is loaded (bmkp-jump-dired, bmkp-jump-url-browse, bmkp-jump-url-browse-other-window and bmkp-gt-browsel-tabs-jump). bookmark-gt classifies them correctly in the list buffer and the jump reader, but jumping to them fails because the function is not defined. M-x bookmark-gt-migrate-from-bookmark-plus converts them once:

;; Changes `bookmark-alist' only; the file is not written.
(bookmark-gt-migrate-from-bookmark-plus)
;; Check the result in M-x bookmark-gt-list, then save:
(bookmark-save)

For each bookmark+ record, the migration replaces the handler with bookmark-gt’s, moves a URL from location to url, and removes the " - no file -" placeholder from filename. It also removes keys that bookmark-gt does not use: bmkp-gt-load-index, buffer-name, front-context-region-string, rear-context-region-string, and an empty annotation or tags. It keeps a real filename, position, front-context-string, rear-context-string, visits, last-visited, created, last-modified and the Dired keys, which bookmark-gt’s Dired handler reads the same way bookmark+’s did. Records already in bookmark-gt’s form, and plain file bookmarks, are not changed. Keep a copy of your bookmark file before migrating.

Reference

Selected options

VariableDefaultDescription
bookmark-gt-list-name-width32Width of the list buffer’s Name column; longer names are truncated.
bookmark-gt-list-type-width12Width of the Type column.
bookmark-gt-list-tags-width24Width of the Tags column.
bookmark-gt-list-buffer-name"*Bookmarks-gt List*"Name of the list buffer.
bookmark-gt-list-selection-mark?*Character shown for rows marked with m.
bookmark-gt-list-deletion-mark?DCharacter shown for rows flagged with d.
bookmark-gt-list-default-show-temptWhether a new list buffer shows temporary bookmarks; H changes it per buffer.
bookmark-gt-list-persist-statenilWhether the list buffer’s view is saved across sessions.
bookmark-gt-jump-name-max-width58Width at which the jump reader truncates names, so that long names leave room for the annotation.
bookmark-gt-jump-location-max-width100Limit on the width of the location in the jump annotation: columns (integer), a fraction of marginalia-field-width (float), or no limit (nil).
bookmark-gt-jump-default-sortmruSort order of bookmark-gt-jump when :sort-by is not given: mru, visits, or nil for the list’s order.
bookmark-gt-dired-virtual-max-size524288Largest virtual Dired listing, in bytes, that a bookmark can store.
bookmark-gt-auto-update-interval60Seconds of idle time between updates of auto-update bookmarks.
bookmark-gt-track-renamestWhether renaming a file updates the bookmarks pointing at it.
bookmark-gt-default-tagsnilTags proposed by bookmark-gt-default-tags-mode: a string, a list of strings, or a function of the record.
bookmark-gt-prompt-for-tags-flagtWhether creating a bookmark interactively prompts for tags; default tags and bookmark-gt-create-tag-reader-hook apply either way.
bookmark-gt-allow-same-name-bookmarksdifferent-destinationWhen a new bookmark may reuse a name: never, different-destination or always.
bookmark-gt-unique-names("\\`org-capture-last-stored\\'" "\\`org-refile-last-stored\\'")Regexps of names that always identify a single bookmark, whatever the previous option says.
bookmark-gt-unique-name-handlers(burly-bookmark-handler)Handlers whose bookmarks are one per name: storing one replaces the existing bookmark of that name and handler.
bookmark-gt-auto-temp-names("\\`org-capture-last-stored\\'" "\\`org-refile-last-stored\\'")Regexps of names whose bookmarks are made temporary when stored.
bookmark-gt-highlight-enabletWhether bookmarks are highlighted in the buffers visiting their files.
bookmark-gt-file-type-handlersnilFile-name regexps mapped to the functions that open matching file bookmarks.
bookmark-gt-browser-tabs-browsersnilBrowser clients asked for tabs, such as ("chrome" "firefox"); nil asks every connected browser.
bookmark-gt-browser-tabs-filternilWhich tabs to keep: nil for all, a regexp the URL must match, or a predicate called with the tab.

Acknowledgements

bookmark-gt owes a great deal to Drew Adams and his bookmark+ package, in design and in code. Most of its features (tags, URL, EWW, region, function, sequence and keyboard-macro bookmarks, temporary bookmarks, visit tracking, highlighting and filtering by tag) first appeared in bookmark+.

The URL handler (bookmark-gt-handler-url-jump) and the Dired handler (bookmark-gt-handler-dired-jump) were adapted from bookmark+’s bmkp-jump-url-browse and bmkp-jump-dired. The record keys tags, bmkp-temp, auto-update, visits, last-visited, location, front-context-region-string and rear-context-region-string are bookmark+’s, so these fields are kept when a bookmark file is used by both packages. The one exception is the " - no file -" placeholder, which bookmark-gt reads but does not write (see Data compatibility with bookmark+); whether bookmark+ accepts a record without filename has not been tested.

bookmark-gt is a rewrite, not a fork: it is built on tabulated-list-mode and on registries of handlers, groups, filters and sort orders. Its features, its design ideas and the handler code it adapts come from Drew’s work.

License

GPL-3.0-or-later. See LICENSE.

About

Module for emacs to enhance its bookmarking system

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages