orgability
Orgability is a reading list manager with offline access support. Orgability
lets you to easily create topics between reading list entries and org-brain
entries by adding topics to reading entries.
Installation
This package requires Emacs 25.1 or higher.
MELPA
This package is not yet available on MELPA.
Manual
Install org-mode
, org-cliplink
, org-board
, org-brain
, org-drawer-list
and then require this package in your init.el
file:
(require 'orgability)
Usage
Relations
There are several relations that one can create between different entries.
topic <-> resource
relation, whereorg-brain
entry is a topic for reading list entry and reading list entry is a resource fororg-brain
entry.
Commands
orgability-clip
: Stores an URL from the clipboard to theorgability-file
.- The title is fetched using
org-cliplink
. - When
orgability-auto-archive
is non-nil the URL is archived usingorg-board
for an offline access.
- The title is fetched using
orgability-store-url
: The same asorgability-clip
, but asks for an URL.orgability-open
: Opens archive usingorg-board
in theorg-board-default-browser
.orgability-add-topic
: Asks for aorg-brain
entry and creates atopic <-> resource
relation between reading list entry at the point and selectedorg-brain
entry. Reading list entry is resource oforg-brain
entry andorg-brain
entry is a topic of reading list entry.orgability-delete-topic
: Removestopic <-> resource
relation betweenorg-brain
entry and reading list entry in a two-way fashion. Thatโs why you should not manually remove topics fromorgability-file
.
Viewing reading list
Currently, orgability
doesnโt expose any special functionality to view all
your reading list, but you can use org-agenda
for this purpose. There is a
function orgability-agenda-format-topics
that can be used in
org-agenda-prefix-format
to insert topics.
("r" "Reading List" tags-todo "READING"
((org-agenda-overriding-header "Reading List")
(org-agenda-remove-tags t)
(org-agenda-prefix-format '((tags . "%(orgability-agenda-format-topics)")))
(org-agenda-sorting-strategy '(todo-state-down effort-up category-keep))))
Configurations
orgability-file
: File with reading list entries.orgability-add-to-top
: If non-nil, entries are added to the top of theorgability-file
.orgability-todo-keyword
: If non-nil, entries are added with a selected todo keyword.orgability-active-timestamp
: If non-nil, ADDED timestamp is active and inactive otherwise.orgability-auto-archive
: If non-nil, useorg-board
to archive reading list for offline access when adding it.orgability-use-relative-archive-url
: If non-nil, use relative links to archived reading list entry. Useful when using several computers with different$HOME
directories.orgability-auto-agenda-redo
: If non-nil, refreshorg-agenda
when adding reading list entry.orgability-title
: Title for a neworgability-file
.orgability-category
: Category for a neworgability-file
.orgability-file-tags
: File tags for a neworgability-file
.orgability-extract-http-title-f
: Function to extract title from http(s) URL. By default itโsorg-cliplink-retrieve-title-synchronously
from aorg-cliplink
package. This variable allows you to choose your own implementation.orgability-agenda-topics-column
: Width of topics block inorg-agenda
.
Testing
Ideally, you should use Cask for running tests. So first you need to install
cask
. If you are using emacs-plus, then you need to ignore dependencies during
cask
installation.
$ brew install cask --ignore-dependencies
One you have cask
, you need to install all dependencies.
$ cask install
Now you can run tests.
$ cask exec ert-runner
Special thanks
Special thanks to creators and maintainers of org-mode
, org-cliplink
,
org-brain
and org-board
. And to all the Emacs community.
Contributing
Everyone is welcome to contribute to orgability
project. Feature requests,
proposals, issue reports, documentation improvements, code patches - just to
name few things that the project can gain from.
Please note that the main upstream of orgability
is located on GitLab, and
itโs advisable to send your contributions there. But they can be accepted also
via email and GitHub.
This project has automated tests that are run on GitLab. If you are contributing outside of GitLab, please run the tests manually. For more information please refer to relevant section in readme file or contact me via email.
Happy hacking!