Install LinkRemark:

• Firefox add-on at addons.mozilla.org,
• Extension in Chrome Web Store.

LinkRemark is a browser extension that allows to save some context while capturing notes using Org mode for GNU Emacs. The add-on attempts to extract some metadata from the current web page, e.g. author, time when the text was written. Actually it just generates (almost) text notes using a few elements of Org mode markup.

The idea is that the note for a link should not be just a bookmark to the link target. It should reflect connection of the page where it is found and the site it points to. A site that brought you to the current page (referrer) could later help find more information related to the topic. Consider it as an element of associative trails described by Vannevar Bush (As We May Think, The Atlantic Monthly, Jul 1945) However implementation is hardly approaching ideas developed by Douglas Engelbart.

I have not seized experiments with this extension, that is why I could not give compatibility promise. Unsure if it is reliable enough, personally I find it acceptable. Be ready to edit created notes. Almost every site has its own peculiarities, so you will have to manually add some info and to remove some redundant entries.

* Link: Karl Voit: UOMF: Managing web bookmarks with Org Mode
:PROPERTIES:
:DATE_ADDED: [2021-09-28 Tue 12:15]
:END:

- Link URL :: [[https://karl-voit.at/2014/08/10/bookmarks-with-orgmode/]]
- Link text :: Karl Voit: UOMF: Managing web bookmarks with Org Mode

#+begin_quote
author: Karl Voit
published: [2014-08-10 Sun]
#+end_quote

On the page

** Adam Porter — org-almanac
:PROPERTIES:
:DATE_ADDED: [2021-09-28 Tue 12:15]
:LAST_MODIFIED: [2021-09-18 Tue 01:23]​ 09/18/2021 01:23:46
:END:

- URL :: [[https://alphapapa.github.io/org-almanac/]]
- title :: org-almanac
- author :: Adam Porter
- referrer :: [[https://www.google.com/]]

You can install LinkRemark from browser extension catalogues, see addons.mozilla.org for Firefox or Chrome Web Store. Packages are mirrored in the releases section on GitHub https://github.com/maxnikulin/linkremark/releases

It is possible to try latest development version by loading content of this repository as a temporary add-on in Firefox or as an unpacked extension in Chrome. Create a symlink manifest.json to either manifest-firefox.json or =manifest-chrome.json file.

For everyday use you might wish to configure native application helper or desktop-wide org-protocol handler instead of clipboard to pass captures to your notes.

Optionally select some text and choose an option from context menu (right click, [Menu] or [Shift+F10] keys). Unless you are going to capture a particular link, you can click on the extension icon in browser toolbar (“browser action”) or may configure a shortcut on the add-ons page.[fn:addons]

By default the extension just shows preview for the note and offers to copy it to clipboard, so you just can paste it to a text editor. Emacs Org mode has a convenient command C-c C-x C-y, org-paste-subtree.[fn:pastesubtree] A hint: to navigate to the parent heading before pasting you can use C-u C-c C-w, org-refile or C-c C-j, org-goto (maybe with prefix argument as well).

Capture templates (web) or info “(org) Capture” is the next step for Org mode users. You could start with a very simple template having “plain” type

(custom-set-variables
 '(org-capture-templates
   (quote (
    ("c" "Clipboard with tree (plain)"
     plain (file "~/org/capture.org")
     "%(org-get-x-clipboard 'CLIPBOARD)"
     :empty-lines 1)
))))

You can add such entry using M-x customize-variable RET org-capture-templates. On the current development stage I do not recommend :immediate-finish option, it is better to inspect capture result. It is impossible to refile plain entry directly from a capture buffer, so likely you wish to change “plain” (Plain text) to “entry” (Org entry) type in Emacs configuration and to change template to

"* %(org-get-x-clipboard 'CLIPBOARD)"

Please, update “Template type configured in org-capture-templates” in add-on settings as well (may be opened from preview page, or from browser add-ons page[fn:addons].

There is an option to avoid preview page for successful captures: disable “Open preview tab with capture result for clipboard”.

Usually, to minimize keyboard and mouse interaction, it is recommended to setup desktop-wide org-protocol: handler (currently readme for Org Capture Extension may be more useful than Worg page). I am a bit afraid that some web page may try to inject some malicious content into my notes when I click on an innocent link, so I suggest to consider exporting through a native messaging application as a safer option.[fn:snap] LinkRemark repository contains a simple variant in examples/backend-python/lr_emacsclient.py Run it with -h option for a brief guide. To enable it, you should do something like (Linux, Firefox)

mkdir ~/.mozilla/native-messaging-hosts
python3 examples/backend-python/lr_emacsclient.py --manifest-firefox \
   >~/.mozilla/native-messaging-hosts/lr_emacsclient.json

and should specify ”native-messaging” for “Communication Channel” / “Method how to pass capture to desktop environment” and ”lr_emacsclient” for “Browser native messaging communication channel” / “Name of native messaging backend application” add-on settings. Emacs init file should have something like the following:

(custom-set-variables
 '(org-capture-templates
   (quote (
    ("r" "LinkRemark (entry)"
     entry (file "~/org/capture.org")
     "* %:initial"
     :empty-lines 1)
))))

Certainly Emacs server should be running: M-x server-start and org-protocol should be loaded: M-: (require ‘org-protocol). Keep capture type in Emacs consistent with “Template type configured in org-capture-templates” add-on setting. Another option you may find useful is “Template name”. They are in the “Org Protocol” section, but applied for native app export as well.

If you wish to experiment with metadata formatting, have a look at examples/backend-python/lr_example.py for inspiration. See the next section for a more powerful native messaging helper.

If you are not familiar with Org Mode capture feature, you could find description of workflow in blogs, e.g. Learn how to take notes more efficiently in Org Mode by Sacha Chua.

[fn:addons] “Manage extension” or “Preferences” in context menu (right click) for the add-on’s browser action button or through generic browser menu, e.g. Firefox: “Add-ons and Themes” from hamburger menu or from “Tools” in menu bar, [Ctrl+Shift+A].

[fn:pastesubtree] There is some bug and subtree is not recognized first time in X clipboard. Workaround is yank C-y, undo C-/ (required once per Emacs session), and C-c C-x C-y to paste subtree.

[fn:snap] There is a problem with browsers distributed as snap or flatpack. Such applications works with additional level of isolation in respect to system files, so external application can not be invoked even through native messaging API. Chromium in Ubuntu is shipped as snap package only since Ubuntu-20.04 LTS focal, for Firefox snap is made default option in Ubuntu-21.10 impish, but Firefox is still can be installed as a deb package using apt. Related Firefox bugs:

• Bug 1661935: Snap: cannot install/manage extensions from extensions.gnome.org,
• Bug 1621763: (flatpak) native messaging support missing.

This is a new feature in LinkRemark-0.2, it was not included in 0.1 version. Please, consider current implementation as a proof of concept, there are a lot of things to polish yet. It is tested on Linux only.

bURL https://github.com/maxnikulin/burl native messaging app (backend) is required. It allows to invoke emacsclient directly without setting up of desktop-wide handler for org-protocol. I do not think that protocol of internal communication between LinkRemark and bURL is stabilized already.

README file for bURL describes how to install and to configure the native application (unsure if it is clear enough). Key points:

• Server (info “(emacs) Emacs Server”) is running in Emacs unless it is enough to just see locations of same URL in your notes. Otherwise neither clicks on found mentions nor org-protocol capture would work.
• org-protocol (info “(org) Protocols”) is loaded and a template is configured to enable capture feature. Alternatively use clipboard and C-c C-x C-y, org-paste-subtree.
• Native application is enabled in browser for LinkRemark extension. On Linux a JSON file should be created.
• List of files to search for URLs is provided to bURL. Currently it is achieved by creating of a wrapper shell script for burl_backend.

bURL may create configuration files for your. To enable native backend for particular user of Firefox on Linux assuming that burl_backend binary is copied to ~/.local/bin, run a command similar to the following one:

mkdir ~/.mozilla/native-messaging-hosts
~/.local/bin/burl_backend -manifest-firefox ~/.mozilla/native-messaging-hosts/ \
    -backend burl \
    -wrapper ~/.local/bin/burl_wrapper \
    -org ~/org/notes.org \
    -org ~/org/capture.org

It should create burl_wrapper shell script and burl.json file (io.github.maxnikulin.burl.json without -backend option) in ~/.mozilla/native-messaging-hosts/ (its basename is the identifier of the native application).

Open LinkRemark settings page[fn:addons]. Set “Name of native messaging backend application” in the “Browser native messaging communication channel” section to the id of configured native app (e.g. burl or io.github.maxnikulin.burl). Grant permission for “Exchange messages with other programs” (in Firefox, while compatibility with Firefox-78 is maintained, this permission is requested during installation).

Known URLs should be reported in response to capture of pages already present in your notes. Preview and debug info page has a form for testing of this feature.

You can set “Method how to pass capture to desktop environment” to “native-messaging”, however it is not required. You can continue with clipboard or org-protocol desktop-wide handler.

There are some projects that allows to capture URL + page title + selection text or URL + text link. It is not enough for me. I would like to save to my notes who and when wrote the text at least for sites that have such fields in page metadata.

To capture a minimal bookmark one of the following projects could be more convenient:

• GitHub - sprig/org-capture-extension: A Chrome and Firefox extension facilitating org-capture in Emacs.
• GitHub - alphapapa/org-protocol-capture-html: Capture HTML from the browser selection into Emacs as org-mode content.
• GitHub - karlicoss/grasp: A reliable org-capture browser extension for Chrome/Firefox.

If you would like to have more details on web pages in you notes then consider GitHub - yantar92/org-capture-ref: Extract metadata/bibtex info from websites for org-capture. It is suitable if web browser of your choice is Emacs or Qute Browser. Unlike this extension, it supports custom handlers for particular websites, and has recipes for scientific papers and BibTeX format.

You could find more information what every requested permission means on the following page from the Mozilla Support site: Permission request messages explained.

Chrome: “Read and change all your data on all websites”.

The add-on may gather data for a group of selected (highlighted) tabs in Firefox or from subframes loaded from other site than top level page in the tab. Due to some limitations of WebExtensions API, per-site permission requests on demand may require several steps of interaction with user to complete a capture. It may be annoying after all. This permission may be perceived as “too much”. In future I may consider making it optional one.

It is a bug, if this extension attempts to inspect content of some tab without explicit user action.

Chrome: “Communicate with cooperating native applications”, optional.

Allows the extension to communicate with Emacs without global org-protocol handler, so allows to have more secure setup. On the other hand you need to install and configure an extra application, so you should either trust this external tool or should develop it yourself.

This permission is relevant for experienced Emacs and Org Mode users.

This permission can not be requested on demand in Firefox-78.10 ESR available in Debian stable, see https://bugzilla.mozilla.org/1630415 “1630415 - make nativeMessaging an optional permission”.

Extension can not launch any application till it is explicitly added to a configuration file (manifest) by the user, so do not worry, extensions can not run arbitrary binaries with no cooperation from users.

Chrome: “Read your browsing history”.

It is necessary to reliably restore tree of nested frames. Consider the case when some element is focused in a subframe and capture is invoked using keyboard shortcut. Maybe I will add a less reliable fallback in future to make this permission optional.

Open browser extensions preferences[fn:addons] to manage this set of permissions. Switches are available on add-on custom settings page and in browser settings UI. They may be requested on demand to successfully complete requested action taking into account current settings.

Additional feature is available in Firefox only. When granted, it is possible to capture a group of tabs. Select some tabs e.g. by holding [Ctrl] while clicking on tab headers and open context menu (right click) for a header of selected tab.

Requested on demand when not granted.

In Chrome it is called “Modify data you copy and paste”, but due to better tracking of user action context it is not required.

In Firefox, without such permission, an extension can not copy data to clipboard except if it is immediate action in response to e.g. click on a button. Clicking on extension button is not the case since a lot of work should be done before data become ready for copy, so it is not considered as “in response to user action”. Enable this permission if you prefer to avoid preview page as an intermediate state.

Browsers consider overwriting clipboard content as a potentially dangerous action, so they perform, some measures to protect users. Security model in Chrome is different from Firefox, so this permission does not do anything really useful in Chrome. However unlike Firefox it allows to call document.execCommand("copy") from content scripts, so the extension can do its job. For privileged tabs (e.g. PDF files) preview page is unavoidable in Chrome and can appear for a second. Sorry for this inconvenience.

This permission may be revoked as soon as you configure native application or desktop-wide org-protocol handler.

1. Try to open Debug Info (Preview) extension page through context menu for the extension button in tool bar (extension browser action) end expand debug info section there.
2. Look for errors in console pane in browser developer tools for the extension. It could be opened using “Inspect” link from the about:debugging#/runtime/this-firefox page for Firefox. In Chrome menu choose “More tools”, “Extensions” and click on the link followed “Inspect views” on the add-on card.

For native messaging backend problems see the related section in Mozilla developer guide and Chrome debugging native messaging docs. It is worth checking errors reported to the browser console (Ctrl+Shift+J in Firefox). To read messages from Chrome on Linux, start it from a terminal or maybe just try journalctl --user --follow.

LinkRemark is published under the GNU GPLv3 license or any later version. See the LICENSE.txt file in this directory.