Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alphapapa/org-recent-headings

Go to recently used Org headings
https://github.com/alphapapa/org-recent-headings

emacs org-mode

Last synced: 2 months ago
JSON representation

Go to recently used Org headings

Awesome Lists containing this project

README 

        
#+TITLE: org-recent-headings



[[https://melpa.org/#/org-recent-headings][file:https://melpa.org/packages/org-recent-headings-badge.svg]] [[https://stable.melpa.org/#/org-recent-headings][file:https://stable.melpa.org/packages/org-recent-headings-badge.svg]]



This package lets you quickly jump to recently used Org headings using Helm, Ivy, or plain-ol' =completing-read=.



* Installation



** MELPA



Install package =org-recent-headings= and put this in your init file (using [[https://github.com/jwiegley/use-package][use-package]]):



#+BEGIN_SRC elisp

  (use-package org-recent-headings

    :config (org-recent-headings-mode))

#+END_SRC



** Quelpa



Installing with [[https://framagit.org/steckerhalter/quelpa][Quelpa]] is easy:



1.  Install [[https://framagit.org/steckerhalter/quelpa-use-package#installation][quelpa-use-package]] (which can be installed directly from MELPA).

2.  Add this form to your init file:



#+BEGIN_SRC elisp

  (use-package org-recent-headings

    :quelpa

    (org-recent-headings :fetcher github :repo "alphapapa/org-recent-headings"

                         :files (:defaults (:exclude "helm-org-recent-headings.el")))



    :config

    (org-recent-headings-mode))

#+END_SRC



** Helm



If you use Helm, you may also install the package =helm-org-recent-headings= from MELPA, or use this:



#+BEGIN_SRC elisp

  (use-package helm-org-recent-headings

    :quelpa

    (helm-org-recent-headings :fetcher github :repo "alphapapa/org-recent-headings"

                              :files ("helm-org-recent-headings.el")))

#+END_SRC



* Usage



When =org-recent-headings-mode= is active, whenever you jump to an Org heading (e.g. in the Agenda, with =helm-org-rifle=, or with any function listed in =org-recent-headings-advise-functions=), the heading you jump to will be added to =org-recent-headings-list=.  Then you can jump to those headings with these commands:



+  =org-recent-headings=

+  =helm-org-recent-headings= (if installed)



** Customization



The =org-recent-headings-advise-functions= list has several commonly used functions, but users will likely want to customize this list.  You might want to add functions to it, like =isearch= functions, [[https://github.com/abo-abo/worf][Worf]] functions, or commands from other packages you may use.  (Suggestions for the default list of functions are welcome!)



=org-recent-headings-show-entry-function= lets you choose the default way to jump to headings, either in their real buffer, or in an indirect, narrowed buffer (with =org-tree-to-indirect-buffer=).



There are a few other settings as well.  Customize the =org-recent-headings= group to see them all.



** Helm



If you use Helm and have installed =helm-org-recent-headings=, you can use =helm-source-org-recent-headings= with Helm commands, e.g.:



#+BEGIN_SRC elisp

  (helm :sources helm-org-recent-headings-source)



  (helm-other-buffer (list helm-source-buffers-list

                           helm-org-recent-headings-source)

                     "My Helm command")

#+END_SRC



* Changelog



** 0.2-pre



*Added*

+  Variable ~org-recent-headings-reject-any-fns~ may be a list of functions used to test new entries; if any return non-nil, an entry is not saved to the recent headings list.  This may be used to e.g. only save entries from certain directories by using a function like:

#+BEGIN_SRC elisp

  (lambda (entry)

    (not (string-match (rx-to-string `(seq bos ,(expand-file-name "~/org/")) t)

                       (org-recent-headings-entry-file entry))))

#+END_SRC



*Fixed*

+  Storing entries from indirect buffers.

+  Display an error if ~org-id-find~ can't find an entry.

+  Storing and finding outline paths which include links in headings.



*Changed*

+  Entries are now stored as structs.  The list should be automatically converted to the new format.



*Removed*

+  Helm-related functionality, now moved to a separate package, =helm-org-recent-headings=.

+  Ivy-related functionality, which only consisted of a single command that bound =completing-read-function= to =ivy-completing-read= and called =org-recent-headings=.  Ivy users will probably use =ivy-mode=, which obviates the removed command (just call =org-recent-headings=).  Removing it avoids dependency problems which can be very frustrating to users.



** 0.1



First tagged release, almost 2 years since first commit.



* Development



Bug reports, suggestions, feedback — /oh my/! 



Suggestions for functions to add to =org-recent-headings-advise-functions= are especially welcome.  I'd like the default to be as useful as possible.



* Credits



+  Thanks to [[https://github.com/zeltak][zeltak]] for his faithful help testing this and other packages of mine!



* License



GPLv3 or any later version.