hhy5277 / org-brain

Org-mode wiki + concept-mapping

org-brain

org-brain implements a variant of concept mapping in Emacs, using org-mode. It is heavily inspired by a piece of software called The Brain, and you can view an introduction to that program here. They also provide a blog with great ideas of how you can think when organizing your Brain.

You can think of org-brain as a combination of a wiki and a mind map, where each wiki page / mind map node is an org-mode file which resides in your org-brain-path, or a headline with an ID property in one of those files. These are called entries. Entries can be linked together, and you can then view the network of links as a mind map, using M-x org-brain-visualize.

PINNED:  Index


               +-Python              Game development-+-Game design
               +-Programming books           |
   Programming-+-Emacs                       |
         |                                   |
         +-----------------+-----------------+
                           |
                           V
                    Game programming <-> Computer games

Game Maker  Unity

--- Resources ---------------------------------

- https://en.wikipedia.org/wiki/Game_programming
- Passing Through Ghosts in Pac-Man
- In-House Engine Development: Technical Tips

--- Text --------------------------------------

Game programming is the art of programming computer games...

When visualizing an entry, you will see the entry’s relationship to other entries. There are four different types of relationships in org-brain:

Parents

Entries above the visualized entry. If the visualized entry is a headline, then the parent headline in the org-mode file will be one of the parents. In the case of top level headlines, the file itself will be considered a parent. Additional parents can be added manually. In the example above, Programming and Game development are parents of the visualized Game programming entry.

Children

Entries below the visualized entry. This will by default be subheadings of the visualized entry (or level one headlines, if the visualized entry is a file). You can add other children, residing elsewhere, manually. In the example above, Game Maker and Unity are the children of Game programming.

Siblings

These appear to the right of the parent entries. Siblings are the other children of the visualized entry’s parents.

Friends

These appear to the right of the visualized entry. Friends provide a way of adding a hierarchy independent two-way relationship between two entries. Friends must be added manually. In the example above, Computer games and Game programming are friends.

Here’s an article describing how you can use the different relationships (The Brain’s jump thoughts are the equivalent of friends in org-brain).

Apart from the visualized entry’s relationships, org-brain-visualize also show pinned entries, which are shown independently of the visualized entry; Index is a pinned entry in the example above. org-brain-visualize also show a list of the entry’s resources (links and attachments), and the text in the entry. The example above have three resources, and a short text. The resources and text is gathered from org-mode automatically.

There’s also the option to visualize the entry as a tree, or similar to a mind map, where you can zoom in order to show grandparents and grandchildren.

The relationship entries, pinned entries and resources are all links; they can be pressed/clicked to visualize other entries, visit resources etc.

Setup and requirements

The easiest way is to get org-brain from MELPA. If you do not want to do that, clone this git repository or download org-brain.el and add it to your load-path. The example below is using use-package and assumer that you’re using MELPA, but you could use (require 'org-brain) or add a :load-path to use-package instead.

(use-package org-brain :ensure t
  :init
  (setq org-brain-path "directory/path/where-i-want-org-brain")
  ;; For Evil users
  (with-eval-after-load 'evil
    (evil-set-initial-state 'org-brain-visualize-mode 'emacs))
  :config
  (setq org-id-track-globally t)
  (setq org-id-locations-file "~/.emacs.d/.org-id-locations")
  (push '("b" "Brain" plain (function org-brain-goto-end)
          "* %i%?" :empty-lines 1)
        org-capture-templates)
  (setq org-brain-visualize-default-choices 'all)
  (setq org-brain-title-max-length 12))

1. org-brain requires Emacs 25 and org-mode 9. These need to be part of your Emacs.
2. Configure org-brain-path (defaults to /brain in your org-directory) to a directory where you want to put your org-brain files (which could be the location where you already keep your org files if you wish to transform your existing org files into org-brain files). You can set this with the example config presented above or through M-x customize-group RET org-brain.
3. If you’re an evil user, you’ll want to add (evil-set-initial-state 'org-brain-visualize-mode 'emacs) to your org-brain configuration.
4. org-brain use org-id in order to speed things up. Because of this, the variable org-id-track-globally should be t (which it already is by default). You may want to modify org-id-locations-file too.
5. You might want to add information at the end of an entry, without visiting the file. A way to do this is to use a capture template, such as the one presented above.
6. If you have a lot of entries, it might take some time to gather information about all entries when using org-brain-visualize. You could change the value of org-brain-visualize-default-choices (which is =’all= by default) to only include files, or even just files in the direct root of org-brain-path.
7. If you feel that org-brain-visualize is too cluttered, you may want to set org-brain-show-resources and/or org-brain-show-text to nil.
8. If you have very long entry names, org-brain-visualize may take a lot of horizontal space. You can cap the shown length of entry titles, by setting org-brain-title-max-length.

Headline and file entries

There are two types of entries in org-brain: headline entries and file entries. For the most part these are used the same way, and the main difference between them is how their content is stored inside your org-brain directory. All .org-files inside the org-brain-path are considered as file entries (the content typically being the text before the first headline in the file) and all headlines with an ID property inside these files are considered as headline entries.

If you have a headline entry, which you want to convert to a file entry, use M-x org-brain-headline-to-file. Unfortunately there is currently no function to convert a file entry into a headline entry.

Usage

If you find that org-brain is missing entries, or list entries which doesn’t exist, try using M-x org-brain-update-id-locations, which syncs the org-brain entries with the org-id caching system.

org-brain-visualize

The primary usage of org-brain is through M-x org-brain-visualize (which you might want to bind to a key). From there you can browse entries, add/remove relationships, open entries for editing etc. The following keybindings are available in org-brain-visualize:

Key	Command	Description
m	org-brain-visualize-mind-map	Toggle between normal and mind-map visualization.
j or TAB	forward-button	Goto next link
k or S-TAB	backward-button	Goto previous link
b	org-brain-visualize-back	Like the back button in a web browser.
h or *	org-brain-add-child-headline	Add a new child headline to entry
c	org-brain-add-child	Add an existing entry, or a new file, as a child
C	org-brain-remove-child	Remove one the entry’s child relations
p	org-brain-add-parent	Add an existing entry, or a new file, as a parent
P	org-brain-remove-parent	Remove one of the entry’s parent relations
f	org-brain-add-friendship	Add an existing entry, or a new file, as a friend
F	org-brain-remove-friendship	Remove one of the entry’s friend relations
n	org-brain-pin	Toggle if the entry is pinned or not
t	org-brain-set-title	Change the title of the entry.
T	org-brain-set-tags	Change the tags of the entry.
d	org-brain-delete-entry	Choose an entry to delete.
l	org-brain-visualize-add-resource	Add a new resource link in entry
r	org-brain-open-resource	Shortcut to choose and open a resource from the entry.
C-y	org-brain-visualize-paste-resource	Add a new resource link from clipboard
a	org-brain-visualize-attach	Run org-attach on entry (headline entries only)
A	org-brain-archive	Archive the entry (headline entries only)
o	org-brain-goto-current	Open current entry for editing
O	org-brain-goto	Choose and edit one of your org-brain entries
v	org-brain-visualize	Choose and visualize a different entry
w	org-brain-visualize-random	Visualize one of your entries at random.
W	org-brain-visualize-wander	Visualize at random, in a set interval. W again to cancel.

You can also use org-store-link inside of org-brain-visualize in order to store a link to the currently visualized org-brain entry.

When using the mind map visualization (toggle by pressing m), you can use the following keybindings in order to show or hide successive levels of hierarchy relative to the current entry.

Key	Command	Description
+	org-brain-show-descendant-level	Show one more level of entries to the right (children of children, etc.)
-	org-brain-hide-descendant-level	Hide rightmost level of descendant entries
z	org-brain-show-ancestor-level	Show one more level of entries to the left (parents of parents, etc.)
Z	org-brain-hide-ancestor-level	Hide leftmost level of ancestor entries

Editing from org-mode

You can edit org-brain entries directly from org-mode. You can use the default org-mode outline structure to define parent/children relationships, but keep in mind that only entries with an ID property will be considered as entries to org-brain; use M-x org-id-get-create to create an ID property to the current org-mode headline. Another alternative is to use M-x org-brain-refile which will create the ids for you.

Most of the commands available in org-brain-visualize can also be used in org-mode directly, in which case they will operate on the “entry at point”. In other words you can use M-x org-brain-add-child directly from org-mode in order to add a child to the org-brain entry at point. You may also want to use the commands org-brain-goto-<relationsship> to navigate between entries.

You may want to create a link to an org-brain entry in an org-mode file (not necessarily an org-brain file itself). org-brain provides several link types for this purpose. You can use org-insert-link (bound to C-c C-l in org-mode by default) to insert one of these links. They all have in common that they, when clicked, will open the org-brain entry for editing. When inserting a link like this, org-brain will run completion upon all your entries.

brain:

The default kind of link. Just let’s you visit another org-brain entry when clicked.

brain-child:

When inserted using org-insert-link this will make the linked entry a child to the current org-brain entry, upon completion. Keep in mind that this doesn’t work if you type the link manually; only by completion through org-insert-link.

brain-parent:

Like brain-child: but makes the linked entry a parent of the current entry.

brain-friend:

Like brain-child: but adds the linked entry as a friend.

The names of the relationship inserting links (brain-child, brain-parent and brain-friend) can be customized with the variables org-brain-child-link-name, org-brain-parent-link-name, and org-brain-friend-link-name. This customization should be done before loading org-brain. If you’re using use-package, put the customization in the :init block.

General information

If you try to add a child/parent/friend to an entry which doesn’t exist, that entry will be created. The name of a new entry can be written like this: file::headline. The headline will be created as a level one headline in file.

When adding children, parents, or friends, multiple entries can be added at once by separating their titles with org-brain-entry-separator (which is ; by default). For instance M-x org-brain-add-parent RET music;artists would add both music and artists as parents.

Another available command is M-x org-brain-agenda, which can be used to run org-agenda on your org-brain files.

Slashes in file entry titles

When giving a file entry a title, the title can not contain slashes (/) if org-brain-file-entries-use-title is t.

Renaming files in org-brain

Headline entries use org-id to identify themselves, so the headlines can be manually renamed without worries. File entries, on the other hand, uses the filename as the identifier. This will cause problems if you try to manually rename files inside of org-brain.

In order to rename a file, use M-x org-brain-rename-file.

Archiving entries

org-archive has a problem in org-brain: relationships are maintained, even though the entry should really be removed from the brain. Because of this, please use org-brain-archive instead. This command removes relationships to the entry in the brain, before archiving it. The command also inserts handy links to the archived entry’s relationships.

Special tags

You might have a headline which you do not really want as an entry in org-brain. The most basic way to exclude such a headline is simply to not add an ID property to it. However, org-brain also provide two tags, which you can use to tag the headline:

:nobrain:

This tag excludes the headline, and its subheadings, from your org-brain entries. You can change the tag name by modifying org-brain-exclude-tree-tag.

:childless:

This tag does not exclude the headline, but it excludes the subheadings. You can change the tag name by modifying org-brain-exclude-children-tag. Works on file entries.

The following tags modifies the kind of information that is shown when an entry is visualized:

:notext:

Do not show the entry’s text in org-brain-visualize. You can change the tag name by modifying org-brain-exclude-text-tag.

:resourceless:

Do not show the entry’s resources in org-brain-visualize. You can change the tag name by modifying org-brain-exclude-resources-tag.

:showchildren:

By default local child entries aren’t shown as text. By setting this tag the entry get the entire subtree as text. You can change the tag name by modifying org-brain-show-children-tag. Works on file entries.

Entry descriptions

You may add a description to an entry, which should be a short summary of what the entry is about. The description will be shown in org-brain-visualize as mouse tooltips for links, and also by eldoc-mode if point is at a link. Add a description by using a #+BEGIN_description block. Here’s an example:

* org-brain.el
  :PROPERTIES:
  :ID:       7cf9563e-24e7-4823-8742-64b7fcc5cafb
  :END:

  #+BEGIN_description
  Package for concept mapping using org-mode.
  #+END_description

  ...

At the moment there’s no way to add/remove/change descriptions directly from the org-brain-visualize interface, sorry!

Having multiple brains

You can have multiple brains simply by having more than one brain folder. In this way, each folder becomes a separate brain. You can switch between these using M-x org-brain-switch-brain.

Take note!

org-brain creates and uses several headline properties in the PROPERTIES drawer of org-mode headlines:

• BRAIN_PARENTS
• BRAIN_CHILDREN
• BRAIN_FRIENDS
• ID

These properties are also mirrored as file keywords at the top of file entries, for instance #+BRAIN_CHILDREN: 00c0f06c-9bd4-4c31-aed0-15bb3361d9a2.

These properties/keywords are not meant to be manipulated directly! If you want to remove these properties, use the corresponding command instead (org-brain-remove-child or similar).

You might also see that org-brain inserts a RESOURCES drawer. It is okay to modify this drawer manually.

org-brain is slow!

If you feel that org-brain is slow while indexing your entries (for instance when running M-x org-brain-visualize) you can customize org-brain-file-entries-use-title, and set it to nil. This will display file names when indexing, instead of the file entry’s title, which is faster.

Backwards compability breaking changes in 0.4

This is only relevant if you’ve been using org-brain before version 0.4

As of version 0.4 (June 2017) org-brain has been rewritten, in order to increase performance and add more options. Because of this, older setups are considered obsolete. Prior to 0.4 only files were considered entries, but now also headlines with an ID property are included as entries. Prior to 0.4 org-brain was using the brain: link and #+BRAIN_PINNED: file keyword to connect files, which was slow due to the need of searching all files for links. In version 0.4 org-brain uses a combination of headline properties, file keywords, org-id, and a data file (org-brain-data-file).

No data in old configurations should be lost, but you’ll have to update the connections between entries. This can be done by using M-x org-brain-create-relationships-from-links, but please backup your org-brain directory first.

It is still possible to add children to an entry by using the brain-child: link, but only if the link is inserted with org-insert-link (bound to C-c C-l in org-mode by default). Linking to specific headlines in a file, via brain:filename::*Headline is deprecated and will no longer work, instead you can convert the headline to an entry and link directly to that.

Other useful packages

There’s some missing functionality in org-brain, which you may find useful. However there are other packages which might improve your org-brain experience. Below are some suggestions (feel free to create an issue or send a pull request if you have more examples), all of them should be available on MELPA.

org-cliplink

A simple command that takes a URL from the clipboard and inserts an org-mode link with a title of a page found by the URL into the current buffer.

Here’s a command which uses org-cliplink to add a link from the clipboard as an org-brain resource. It guesses the description from the URL title. Here I’ve bound it to L in org-brain-visualize.

(defun org-brain-cliplink-resource ()
  "Add a URL from the clipboard as an org-brain resource.
Suggest the URL title as a description for resource."
  (interactive)
  (let ((url (org-cliplink-clipboard-content)))
    (org-brain-add-resource
     url
     (org-cliplink-retrieve-title-synchronously url)
     t)))

(define-key org-brain-visualize-mode-map (kbd "L") #'org-brain-cliplink-resource)

link-hint

link-hint.el is inspired by the link hinting functionality in vim-like browsers and browser plugins such as pentadactyl. It provides commands for using avy to open or copy “links.”

After installing link-hint you could bind link-hint-open-link to a key, and use it in org-brain-visualize-mode. If you only want to use link-hint in org-brain-visualize-mode, you could add the following to your init-file:

(define-key org-brain-visualize-mode-map (kbd "C-l") #'link-hint-open-link)

ascii-art-to-unicode

Converts simple ASCII art line drawings in the region of the current buffer to Unicode.

ascii-art-to-unicode is useful if you want org-brain-visualize-mode to look a bit nicer. After installing, add the following to your init-file:

(defface aa2u-face '((t . nil))
  "Face for aa2u box drawing characters")
(advice-add #'aa2u-1c :filter-return
            (lambda (str) (propertize str 'face 'aa2u-face)))
(defun aa2u-org-brain-buffer ()
  (let ((inhibit-read-only t))
    (make-local-variable 'face-remapping-alist)
    (add-to-list 'face-remapping-alist
                 '(aa2u-face . org-brain-wires))
    (ignore-errors (aa2u (point-min) (point-max)))))
(with-eval-after-load 'org-brain
  (add-hook 'org-brain-after-visualize-hook #'aa2u-org-brain-buffer))

all-the-icons

A utility package to collect various Icon Fonts and propertize them within Emacs.

After installing all-the-icons you could decorate the resources in org-brain, by using org-brain-after-resource-button-functions. Here’s a small example:

(defun org-brain-insert-resource-icon (link)
  "Insert an icon, based on content of org-mode LINK."
  (insert (format "%s "
                  (cond ((string-prefix-p "http" link)
                         (cond ((string-match "wikipedia\\.org" link)
                                (all-the-icons-faicon "wikipedia-w"))
                               ((string-match "github\\.com" link)
                                (all-the-icons-octicon "mark-github"))
                               ((string-match "vimeo\\.com" link)
                                (all-the-icons-faicon "vimeo"))
                               ((string-match "youtube\\.com" link)
                                (all-the-icons-faicon "youtube"))
                               (t
                                (all-the-icons-faicon "globe"))))
                        ((string-prefix-p "brain:" link)
                         (all-the-icons-fileicon "brain"))
                        (t
                         (all-the-icons-icon-for-file link))))))

(add-hook 'org-brain-after-resource-button-functions #'org-brain-insert-resource-icon)

deft

An Emacs mode for quickly browsing, filtering, and editing directories of plain text notes, inspired by Notational Velocity.

After installing deft, you can add the function below to your init-file.

(defun org-brain-deft ()
  "Use `deft' for files in `org-brain-path'."
  (interactive)
  (let ((deft-directory org-brain-path)
        (deft-recursive t)
        (deft-extensions '("org")))
    (deft)))

helm-org-rifle

It searches both headings and contents of entries in Org buffers, and it displays entries that match all search terms, whether the terms appear in the heading, the contents, or both.

After installing helm-org-rifle, you can add the function below to your init-file.

(defun helm-org-rifle-brain ()
  "Rifle files in `org-brain-path'."
  (interactive)
  (helm-org-rifle-directories (list org-brain-path)))

org-board

org-board is a bookmarking and web archival system for Emacs Org mode, building on ideas from Pinboard. It archives your bookmarks so that you can access them even when you’re not online, or when the site hosting them goes down.

Similar packages

The Emacs Wiki has an article about wiki modes in Emacs.

org-wiki

Org-wiki is a org-mode extension that provides tools to manage and build personal wiki or desktop wiki where each wiki page is a org-mode file.

emacs-freex

Emacs freex is a Pymacs/SQLite/Elisp system that implements a transcluding wiki. Emacs-freex is not compatible at this time with org-mode. Despite this, emacs-freex is an impressive system for maintaining a wiki. Further, because the data is stored both in files on disk and in an SQLite database, it opens the possibility for implementing something like org-brain’s visualize interface (ala TheBrain’s “plex”) by talking with SQLite, via Pymacs, to return the relationships between nodes. This would consistute a lot of work to implement but would be very impressive. If someone was to also add LaTeX rendering inside emacs-freex nuggets also, those two additional features would make emacs-freex more compelling. As it is, practically speaking, you may think of org-brain as implementing many of the features of emacs-freex, but with all of org-mode’s goodness included.