|
| 1 | + |
| 2 | +#+TITLE: LinkRemark — notes for web pages augmented by metadata |
| 3 | + |
| 4 | +* Introduction |
| 5 | + |
| 6 | +LinkRemark is a browser extension that allows to save some context |
| 7 | +while capturing notes using GNU Emacs [[https://orgmode.org][Org mode]]. |
| 8 | +The add-on attempts to extract some metadata of the current web page: |
| 9 | +author, time when the text was written. |
| 10 | +Actually it just generates (almost) text notes using a few elements |
| 11 | +of Org mode markup. |
| 12 | + |
| 13 | +The idea is that the note for a link should not be just a *bookmark* |
| 14 | +to the link target. It should reflect connection of the page |
| 15 | +where it is found and the site it points to. |
| 16 | +A site that brought you to the current page (referrer) could later |
| 17 | +help find more information related to the topic. |
| 18 | + |
| 19 | +This extension *is experimental so do not be too surprised |
| 20 | +if something does not work*. |
| 21 | + |
| 22 | +* Example of link capture |
| 23 | + |
| 24 | +#+begin_example org |
| 25 | +Link: Karl Voit: UOMF: Managing web bookmarks with Org Mode |
| 26 | + :PROPERTIES: |
| 27 | + :DATE_ADDED: [2020-12-25 18:06] |
| 28 | + :END: |
| 29 | + |
| 30 | +- Link URL :: [[https://karl-voit.at/2014/08/10/bookmarks-with-orgmode/]] |
| 31 | +- Link text :: Karl Voit: UOMF: Managing web bookmarks with Org Mode |
| 32 | + |
| 33 | +On the page |
| 34 | + |
| 35 | +- URL :: [[https://alphapapa.github.io/org-almanac/]] |
| 36 | +- title :: org-almanac |
| 37 | +- author :: Adam Porter |
| 38 | +- referrer :: [[https://www.google.com/]] |
| 39 | +#+end_example |
| 40 | + |
| 41 | +* Alternatives |
| 42 | + |
| 43 | +There are some projects that allows to capture URL + page title + |
| 44 | +selection text or URL + text link. I would like to save to my notes |
| 45 | +who and when wrote the text at least for sites that have such fields |
| 46 | +in page metadata. |
| 47 | + |
| 48 | +If you do not need metadata you could find more useful other project: |
| 49 | +- [[https://github.com/sprig/org-capture-extension/][GitHub - sprig/org-capture-extension: A Chrome and firefox extension facilitating org-capture in emacs]] |
| 50 | +- [[https://github.com/alphapapa/org-protocol-capture-html][GitHub - alphapapa/org-protocol-capture-html: Capture HTML from the browser selection into Emacs as org-mode content]] |
| 51 | +- [[https://github.com/karlicoss/grasp][GitHub - karlicoss/grasp: A reliable org-capture browser extension for Chrome/Firefox]] |
| 52 | + |
| 53 | +Unlike |
| 54 | +[[https://github.com/yantar92/org-capture-ref][GitHub - yantar92/org-capture-ref: Extract bibtex info from captured websites]] |
| 55 | +project, this extension does not have handlers for particular |
| 56 | +websites and do not use BibTeX format. However the goal is quite |
| 57 | +similar. |
| 58 | + |
| 59 | +* Install |
| 60 | + |
| 61 | +This extension is in its alpha stage, so it has not published to |
| 62 | +browsers' add-on catalogues. |
| 63 | + |
| 64 | +In Chrome create a symlink =manifest.json= to the =manifest-chrome.json= file |
| 65 | +and load it as unpacked extension. |
| 66 | + |
| 67 | +* Usage |
| 68 | + |
| 69 | +Optionally select some text and choose an option from the context menu (right click). |
| 70 | + |
| 71 | +By default the extension just shows preview for the note |
| 72 | +and offers to copt it to clipboard, |
| 73 | +so it can be just yanked to the text editor. |
| 74 | +[[https://orgmode.org/manual/Capture.html#Capture][Capture templates (web)]] |
| 75 | +or [[info:org#Capture]] is the next step. |
| 76 | +You could start with a very simple template |
| 77 | +#+begin_example |
| 78 | +"* %?%(org-get-x-clipboard 'CLIPBOARD) |
| 79 | +" |
| 80 | +#+end_example |
| 81 | + |
| 82 | +Later would likely decide to setup external protocol handler |
| 83 | +for [[https://orgmode.org/worg/org-contrib/org-protocol.html][org-protocol]] |
| 84 | +or to create a native messaging backend. |
| 85 | +In the latter case have a look at [[file:examples/backend-python/lr_example.py]] |
| 86 | +for inspiration. |
| 87 | + |
| 88 | +If you are not familiar with Org Mode capture feature, |
| 89 | +you could find description of workflow in blogs, e.g. |
| 90 | +[[https://sachachua.com/blog/2015/02/learn-take-notes-efficiently-org-mode/][Learn how to take notes more efficiently in Org Mode]] |
| 91 | +by Sacha Chua. |
| 92 | + |
| 93 | +* Troubleshooting |
| 94 | + |
| 95 | +1. Try to open Debug Info (Preview) extension page through context menu for |
| 96 | + the extension button in tool bar (extension browser action) |
| 97 | + end expand debug info section there. |
| 98 | +2. Look for errors in console pane in browser developer tools for the extension. |
| 99 | + It could be opened using "Inspect" link from the [[about:debugging#/runtime/this-firefox]] |
| 100 | + page for Firefox. In Chrome menu choose "More tools", "Extensions" and click on the link |
| 101 | + followed "Inspect views" on the add-on card. |
| 102 | + |
| 103 | +For native messaging backend problems see the related section in Mozilla |
| 104 | +[[https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging#Troubleshooting][developer guide]] |
| 105 | +and Chrome [[https://developer.chrome.com/docs/apps/nativeMessaging/#native-messaging-debugging][debugging native messaging]] |
| 106 | +docs. It is worth checking errors reported to the browser console |
| 107 | +(=Ctrl+Shift+J= in Firefox). To read messages from Chrome on Linux, start it from a terminal or maybe |
| 108 | +just try =journalctl --user --follow=. |
| 109 | + |
| 110 | +* License |
| 111 | + |
| 112 | +LinkRemark is published under [[https://www.gnu.org/licenses/gpl-3.0.html][the GNU GPLv3 license]] or any later |
| 113 | +version. See the [[file:LICENSE.txt]] file in this directory. |
0 commit comments