Org-starter is a framework for basic configuration of Emacs Org Mode. It allows you to configure Org Mode easily even with many files and directories.
The standard way to configure Org Mode is set a bunch of variables such
org-refile-targets. This makes it hard to
add/delete files to/from the configuration. Org-starter lets you
configure Org Mode in a file-centric and incremental manner, which
scales well especially if you have many Org files and sometimes have to
tweak the file list.
In other words, org-starter allows you to configure Org Mode in a manner similar to use-package. The following is an example file configuration with org-starter:
(org-starter-define-file "subjects.org" :agenda t :refile '(:maxlevel . 9))
Table of contents
- Configure directories
- Configure files
- org-starter-def macro
- Configure capture templates
- Helm interface to visit an Org file
- Counsel interface
- Related packages
- Emacs 25.1
- dash and dash-functional
Install from MELPA.
helm-org-starter in this repository are not
available on MELPA yet. Install them individually after installing
org-starter if you need them.
Load path for org files
You can set up a “load path” for Org files. This path is later used to
find an Org file with a specific file name. To set the load path,
You can also add directories to the load path by calling
External configuration files
An obvious way to configure Org files using org-starter is to put the configuration in your Emacs initialization file, i.e.
~/.emacs.d/init.el. Org-starter also allows you to put it in an external configuration file residing in the same directory as your Org files. This is useful if have some host-local configuration and don’t want to put it in your
init.el. Org-starter is about Org files, so it makes sense to configure the package in alongside the files.
To use this feature, set
org-starter-load-config-files custom variable to t.
Now you can put your configuration in
~/org/ is included in
;; ~/.emacs.d/init.el: Configure org-starter (use-package org-starter :custom ;; Enable external configuration files loaded from org-starter-path (org-starter-load-config-files t)) ;; Your custom-file: Set org-starter-path (custom-set-variables ... '(org-starter-path (quote ("~/org/"))) ... ) ;; Now you can put your configuration in ~/org/.org-config.el (org-starter-def "cpb.org")
You can put the configuration in any directories in
org-starter-path. It is possible for you to put the configuration in a different directory
org-starter-swiper-config-files command available from
org-starter-swiper.el in this repository lets you run swiper through your configuration files. It is handy for finding a particular location in your configuration. It may be a good idea to bind a key to the command:
(add-to-list 'org-starter-extra-alternative-find-file-map '(";" org-starter-swiper-config-files "config") t)
org-starter-extra-alternative-find-file-map is a list of commands available when you run
(define-key (kbd "C-c j") #'org-starter-alternative-find-file-by-key)
org-capture template lets you add a configuration quickly to one of your org-starter configuration files.
org-starter-find-config-file lets you select an existing configuration file, and the entire target function navigates to the end of the selected file:
(org-starter-def-capture "e" "Personal Emacs configuration" plain (function (lambda () (org-starter-find-config-file) (goto-char (point-max)))) "%i" :unnarrowed t)
Loading local variables in Org files without confirmation
You may have added local variables to your Org files.
It is annoying to answer “yes” every time Emacs asks you if you are sure you want to load the variables. This can be skipped by enabling
org-starter-mode and setting
:all. That is,
enable-local-variables is temporarily overridden while a file registered by org-starter is loaded.
Since variables defined in your own files are trusted, this is generally considered safe. However, when you set this option to
:all, please don’t add a file that can be edited by someone else to
org-starter-known-files, as local variables defined by others can bring a security risk.
org-starter-define-directory function to define a directory that
contains Org files. You can add the directory to agenda files and/or
refile targets via its options.
You can also add it to the load path via
For details of options, run
C-h f org-starter-define-directory.
org-starter-define-file function to define an Org file. As with
directory definitions, you can add the file to agenda files and/or
You can also define Org files inside
For details, run
C-h f org-starter-define-file.
Quickly access a particular file with a shortcut key
org-starter-define-file accepts optional
:key property, whose value should be a key passed to
kbd function. This property is used by
org-starter-refile-by-key commands, which enter a transient state to operate on a particular file quickly.
You can also add custom commands to the transient keymaps by setting
(setq org-starter-extra-refile-map '(("/" org-refile "normal refile")))
You can also use
org-starter-def define either a file or a directory.
Depending on the type of the argument, it calls either
org-starter-define-directory. It supports
the same functionality as the two functions, but it allows you to define
files and directories slightly more concisely.
It basically supports the same as options as
org-starter-define-file=/=org-starter-define-directory, but it doesn’t
need quoting. For example, the following two directives are equivalent:
(org-starter-define-file "~/hello.org" :refile '(:maxlevel . 3)) (org-starter-def "~/hello.org" :refile (:maxlevel . 3))
When you define a directory using
org-starter-def, you can pass
multiple arguments as
(org-starter-def "~/my-directory" :files ("file1.org" :agenda t) ("file2.org" :agenda nil :required nil))
It also supports an additional option
:config. Its argument is
evaluated after the other options are applied, as in
is executed if and only if the file/directory exists. It can take
(org-starter-def "~/my-directory" :config (do-something) (do-another-thing))
Configure capture templates
Org-starter provides two ways to incrementally define org-capture templates:
org-starter-define-file, which lets you omit the file name of each template target.
org-starter-def-capturemacro, which lets you omit the directory of a file name in template target. The file is searched from the load path. If there is no file existing in the load path, the template is not added.
Templates added by org-starter are sorted alphabetically, so they are grouped by prefix letters even if they are defined in distributed locations.
Each template entry added by these functions is transformed by a function specified as the value of
org-starter-capture-template-map-function custom variable. This can be used to apply rules to your capture templates.
There is also
org-starter-initial-capture-templates custom variable, which is a recommended way to define template groups.
Locate a file
You can use
org-starter-locate-file function to find an Org file
contained in one of the directories in
To locate a file which is not in the path but already registered (defined) as a known file, use the function with an extra third argument. This function first tries to find a file in the list of known files:
(org-starter-locate-file "file-not-in-path.org" nil t)
Load all known files
It is sometimes convenient to load a specific set of Org files into
Emacs as buffers. For example, you can search headings in the live Org
- To load all files registered by
org-starter-define-fileinto Emacs, use
- To load all files in
org-starter-pathinto Emacs, use
If you set Jump to a file
:keyof a file in
org-starter-define-file, you can jump to the file quickly with
You can also define extra bindings for the commands by adding entries to
;; Add a binding to jump to your Emacs init file (setq org-starter-extra-find-map '(("e" (lambda () (interactive) (find-file "~/.emacs.d/init.el")) "init.el")))
Jump to a file (alternative mode)
This package also provides
org-starter-alternative-find-file-by-key, which provides an alternative mode for jumping to a file. Like
org-starter-define-file, it displays options based on
:key property of your files, but it uses a different function, which is configured as
org-starter-alternative-find-function, for visiting a selected file. For example, you can use helm-org-rifle-files for performing a search in the selected file:
(setq org-starter-alternative-find-function 'helm-org-rifle-files)
Refile an entry to a file
When you are visiting a file in Org mode, you can use
org-starter-refile-by-key to refile the current entry to a particular file. The refile level as set in
:refile option is used for producing candidates.
Like the previous commands, you can add extra bindings to the command through
org-starter-extra-refile-map. If you use org-reverse-datetree, it is a good idea to define a custom refile function for your datetree file and add it to the map.
org-starter-extras.el in this repository provides a shortcut for defining such a function concisely:
;; Define org-starter-refile-cpb-datetree function (org-starter-extras-def-reverse-datetree-refile "cpb.org" '("CREATED_TIME" "CLOSED")) (add-to-list 'org-starter-extra-refile-map '("p" org-starter-refile-cpb-datetree "cpb"))
Helm interface to visit an Org file
A separate package
helm-org-starter.el provides a Helm command named
helm-org-starter which you can use to select an Org file in various
categories or create a new one in a known directory.
counsel-org-starter.el provides the following commands:
counsel-org-starter-known-file, which lets you choose a known file.
counsel-org-starter, which lets you choose a known file or a file in
You may find the following packages useful if you use org-starter: