{"id":13569054,"url":"https://github.com/Kungsgeten/org-brain","last_synced_at":"2025-04-04T05:31:13.825Z","repository":{"id":37549332,"uuid":"85571873","full_name":"Kungsgeten/org-brain","owner":"Kungsgeten","description":"Org-mode wiki + concept-mapping","archived":false,"fork":false,"pushed_at":"2024-07-03T20:50:02.000Z","size":451,"stargazers_count":1726,"open_issues_count":89,"forks_count":103,"subscribers_count":65,"default_branch":"master","last_synced_at":"2024-10-29T17:49:11.627Z","etag":null,"topics":["concept-map","emacs","org-mode","wiki"],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kungsgeten.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.org","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-20T12:01:26.000Z","updated_at":"2024-10-27T08:42:53.000Z","dependencies_parsed_at":"2023-01-17T15:01:04.109Z","dependency_job_id":"e60d7a00-a2a4-4317-a83a-507f81e478d6","html_url":"https://github.com/Kungsgeten/org-brain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kungsgeten%2Forg-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kungsgeten%2Forg-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kungsgeten%2Forg-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kungsgeten%2Forg-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kungsgeten","download_url":"https://codeload.github.com/Kungsgeten/org-brain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128701,"owners_count":20888232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concept-map","emacs","org-mode","wiki"],"created_at":"2024-08-01T14:00:35.485Z","updated_at":"2025-04-04T05:31:13.559Z","avatar_url":"https://github.com/Kungsgeten.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp","Open Source","Knowledge Management"],"sub_categories":["Editor Plugin"],"readme":"#+TITLE:org-brain [[http://melpa.org/#/org-brain][file:http://melpa.org/packages/org-brain-badge.svg]]\n\n=org-brain= implements a variant of [[https://en.wikipedia.org/wiki/Concept_map][concept mapping]] in Emacs, using [[http://orgmode.org/][org-mode]]. It\nis heavily inspired by a piece of software called [[http://thebrain.com/][The Brain]], and you can view an\nintroduction to that program [[https://www.youtube.com/watch?v=GFqLUBKCFdA][here]]. They also provide [[https://www.thebrain.com/blog/][a blog]] with great ideas of\nhow you can think when organizing your Brain.\n\nYou can think of =org-brain= as a combination of a wiki and a mind map, where\neach wiki page / mind map node is an =org-mode= file which resides in your\n=org-brain-path=, or a headline with an ID property in one of those files. These\nare called /entries/. Entries can be linked together, and you can then\nview the network of links as a mind map, using =M-x org-brain-visualize=. Here's [[https://www.youtube.com/watch?v=3EGOwfWok5s\u0026t=][a video introducing =org-brain=]].\n\n#+BEGIN_EXAMPLE\n  PINNED:  Index\n\n\n                 +-Python              Game development-+-Game design\n                 +-Programming books           |\n     Programming-+-Emacs                       |\n           |                                   |\n           +-----------------+-----------------+\n                             |\n                             V\n                      Game programming \u003c-\u003e Computer games\n\n  Game Maker  Unity\n\n  --- Resources ---------------------------------\n\n  - https://en.wikipedia.org/wiki/Game_programming\n  - Passing Through Ghosts in Pac-Man\n  - In-House Engine Development: Technical Tips\n\n  --- Text --------------------------------------\n\n  Game programming is the art of programming computer games...\n#+END_EXAMPLE\n\nWhen visualizing an entry, you will see the entry's relationship to other\nentries. There are four different types of relationships in =org-brain=:\n\n- Parents :: Entries above the visualized entry. If the visualized entry is a\n             headline, then the parent headline in the =org-mode= file will be\n             one of the parents. In the case of top level headlines, the file\n             itself will be considered a parent. Additional parents can be added\n             manually. In the example above, /Programming/ and /Game\n             development/ are parents of the visualized /Game programming/\n             entry.\n- Children :: Entries below the visualized entry. This will by default be\n              subheadings of the visualized entry (or level one headlines, if\n              the visualized entry is a file). You can add other children,\n              residing elsewhere, manually. In the example above, /Game Maker/\n              and /Unity/ are the children of /Game programming/.\n- Siblings :: These appear to the right of the parent entries. Siblings are the\n              other children of the visualized entry's parents.\n- Friends :: These appear to the right of the visualized entry. Friends provide\n             a way of adding a hierarchy independent two-way relationship\n             between two entries. Friends must be added manually. In the example\n             above, /Computer games/ and /Game programming/ are friends.\n\n[[http://blogarchive.thebrain.com/thought-relationships/][Here's an article]] describing how you can use the different relationships (The\nBrain's /jump thoughts/ are the equivalent of /friends/ in =org-brain=).\n\nApart from the visualized entry's relationships, =org-brain-visualize= also show\npinned entries, which are shown independently of the visualized entry; /Index/\nis a pinned entry in the example above. =org-brain-visualize= also show a list\nof the entry's resources (links and attachments), and the text in the entry. The\nexample above have three resources, and a short text. The resources and text is\ngathered from =org-mode= automatically.\n\nThere's also the option to visualize the entry as a tree, or similar to a\nmind map, where you can zoom in order to show grandparents and grandchildren.\n\nThe relationship entries, pinned entries and resources are all links; they can\nbe pressed/clicked to visualize other entries, visit resources etc.\n\nYou can also annotate the connection between the visualized entry and one of the\nother entries. You can think of it as annotating the edge between two nodes in a\ngraph. Annotations will show up in the mini-buffer when hovering over an\nannotated connection.\n\n* Setup and requirements\n\nThe easiest way is to get =org-brain= from MELPA. If you do not want to do that,\nclone this git repository or download =org-brain.el= and add it to your load-path.\nThe example below is using [[https://github.com/jwiegley/use-package][use-package]] and assumes that you're using MELPA, but\nyou could use =(require 'org-brain)= or add a =:load-path= to =use-package= instead.\nMost of the configuration below isn't necessary, but showcases some options.\n\n#+BEGIN_SRC emacs-lisp\n  (use-package org-brain :ensure t\n    :init\n    (setq org-brain-path \"directory/path/where-i-want-org-brain\")\n    ;; For Evil users\n    (with-eval-after-load 'evil\n      (evil-set-initial-state 'org-brain-visualize-mode 'emacs))\n    :config\n    (bind-key \"C-c b\" 'org-brain-prefix-map org-mode-map)\n    (setq org-id-track-globally t)\n    (setq org-id-locations-file \"~/.emacs.d/.org-id-locations\")\n    (add-hook 'before-save-hook #'org-brain-ensure-ids-in-buffer)\n    (push '(\"b\" \"Brain\" plain (function org-brain-goto-end)\n            \"* %i%?\" :empty-lines 1)\n          org-capture-templates)\n    (setq org-brain-visualize-default-choices 'all)\n    (setq org-brain-title-max-length 12)\n    (setq org-brain-include-file-entries nil\n          org-brain-file-entries-use-title nil))\n\n  ;; Allows you to edit entries directly from org-brain-visualize\n  (use-package polymode\n    :config\n    (add-hook 'org-brain-visualize-mode-hook #'org-brain-polymode))\n#+END_SRC\n\n1. =org-brain= requires Emacs 25 and org-mode 9. These need to be part of your\n   Emacs.\n2. Configure =org-brain-path= (defaults to =/brain= in your =org-directory=) to\n   a directory where you want to put your =org-brain= files (which could be the\n   location where you already keep your org files if you wish to transform your\n   existing org files into =org-brain= files). You can set this with the example\n   config presented above or through =M-x customize-group RET org-brain=.\n3. If you're an [[https://github.com/emacs-evil/evil][evil]] user, you'll want to add =(evil-set-initial-state\n   'org-brain-visualize-mode 'emacs)= to your =org-brain= configuration.\n4. =org-brain= use =org-id= in order to speed things up. Because of this, the\n   variable =org-id-track-globally= should be =t= (which it already is by default).\n   You may want to modify =org-id-locations-file= too. If you add entries to\n   =org-brain= directly from =org-mode= you must assign headlines an ID. A\n   comfortable way to do this is with the command\n   =org-brain-ensure-ids-in-buffer=. Even more comfortable is to add that to\n   =before-save-hook=, so that it runs when saving.\n5. =org-brain-prefix-map= can be bound to a key to make =org-brain= commands more\n   accessable if you edit entries from =org-mode=. See /Editing from org-mode/ under\n   /Usage/ below.\n6. You might want to add information at the end of an entry, without visiting\n   the file. A way to do this is to use a [[http://orgmode.org/manual/Capture.html][capture]] template, such as the one\n   presented above.\n7. If you have a lot of entries, it might take some time to gather information\n   about all entries when using =org-brain-visualize=. You could change the\n   value of =org-brain-visualize-default-choices= (which is ='all= by default)\n   to only include files, or even just files in the direct root of\n   =org-brain-path=.\n8. If you feel that =org-brain-visualize= is too cluttered, you may want to set\n   =org-brain-show-resources= and/or =org-brain-show-text= to =nil=.\n9. If you have very long entry names, =org-brain-visualize= may take a lot of\n   horizontal space. You can cap the shown length of entry titles, by setting\n   =org-brain-title-max-length=.\n10. Some users find it confusing having both /headline/ entries and /file/ entries\n    (see below). It may be preferable to only use headline entries, by setting\n    =org-brain-include-file-entries= to =nil=. If doing this, you should probably\n    also set =org-brain-file-entries-use-title= to =nil=. Another possibility is if\n    you're only using file entries, in which case you can set\n    =org-brain-scan-for-header-entries= to =nil=.\n11. =polymode= is a package (available on MELPA) which allows for several\n    major-modes in the same buffer. If you have required the package you can use\n    =M-x org-brain-polymode= inside =org-brain-visualize=, or (as in the example\n    above) add =org-brain-polymode= to =org-brain-visualize-mode-hook=.\n\n** Category icons\n\n=org-brain= supports showing icons for your entries, depending on their [[https://orgmode.org/manual/Categories.html][category]]. Use the variable =org-agenda-category-icon-alist= to specify icons for categories.\n\nSee example of using /all-the-icons/ for this below under /Other useful packages/.\n\n** Customizing the look of entry titles\n\nWhen visualizing you might want to see additional information about the entries. This can be done by customizing the following variables:\n\n- =org-brain-vis-title-prepend-functions=\n- =org-brain-vis-title-append-functions=\n- =org-brain-vis-current-title-prepend-functions=\n- =org-brain-vis-current-title-append-functions=\n\nEach of these variables should be a list of functions, which all takes an entry as the single parameter and returns a string. This string is the prepended or appended to the entry's title, according to the name of the function. The variables with the name =current= in them only applies the functions on the currently visualized entry (the focused one).\n\nSuitable functions to add to these lists might be:\n\n- =org-brain-entry-icon= (included in =org-brain-vis-title-prepend-functions= by default)\n- =org-brain-entry-todo-state=\n- =org-brain-entry-tags-string=\n\n* Headline and file entries\n\nThere are two types of entries in =org-brain=: /headline/ entries and /file/\nentries. For the most part these are used the same way, and the main difference\nbetween them is how their content is stored inside your =org-brain= directory.\nAll .org-files inside the =org-brain-path= are considered as /file/ entries (the\ncontent typically being the text before the first headline in the file) and all\nheadlines /with an ID property/ inside these files are considered as /headline/\nentries.\n\nBy default subdirectories inside =org-brain-path= are scanned recursively for\nfiles, so all subdirectories and their files are considered part of the brain.\nYou can choose to only have the root of =org-brain-path= be scanned for files, by\nsetting =org-brain-scan-directories-recursively= to =nil=.\n\nIf you have a headline entry, which you want to convert to a file entry, use =M-x\norg-brain-headline-to-file=. Unfortunately there is currently no function to\nconvert a file entry into a headline entry.\n\n** Limiting =org-brain= to headline entries\n\nMost of =org-mode= is tailored towards working with headlines, and because of this\n=org-brain= has some limitations regarding what's possible with /file entries/. The\nconcept of both headline and file entries is confusing to some users.\n\nIf you prefer to only use headline entries, you can set the variable\n=org-brain-include-file-entries= to =nil=. It then also makes sense to set\n=org-brain-file-entries-use-title= to =nil=.\n\nYou may choose to exclude the file part of entry names when choosing among\nentries. =org-brain= passes two objects, the file and the headline, to the emacs\n[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Formatting-Strings.html][format]] function. By setting =org-brain-headline-entry-name-format-string= to\n=\"%2$s\"=, =org-brain= will only show the headline title.\n\nHere's an example which may be suitable for a setup without file entries:\n\n#+BEGIN_SRC emacs-lisp\n  (setq org-brain-include-file-entries nil)\n  (setq org-brain-file-entries-use-title nil)\n  (setq org-brain-headline-entry-name-format-string \"%2$s\")\n\n  (setq my/default-org-brain-file \"brain\")\n  (setq org-brain-default-file-parent my/default-org-brain-file)\n#+END_SRC\n\n** Limiting =org-brain= to file entries\n\nIf you instead prefer to work with file entries, you can set\n=org-brain-scan-for-header-entries= to =nil=. It will still be possible to add\nheadline entries, but they will be excluded from most searches when choosing\namong entries.\n\n* Usage\n\nYou can create new entries by =M-x org-brain-visualize= and then\ntyping the name of a non-existing entry. You can go back to the\n=*org-brain*= buffer by =M-x org-brain-visualize-dwim=. It will switch\nto the =*org-brain*= buffer. If there's no such buffer, or if already\nthere, run =org-brain-visualize=. You could also use =M-x\norg-brain-add-entry= if you do not want to visualize the new entry.\nAlso commands which add children, parents and friends, or links to\nentries, can create new entries in the same way. Se /General\ninformation/ below.\n\nIf you find that =org-brain= is missing entries, or list entries which doesn't\nexist, try using =M-x org-brain-update-id-locations=, which syncs the\n=org-brain= entries with the =org-id= caching system.\n\n** =org-brain-visualize=\n\nThe primary usage of =org-brain= is through =M-x org-brain-visualize= (which you\nmight want to bind to a key). From there you can browse entries, add/remove\nrelationships, open entries for editing etc. The following keybindings are\navailable in =org-brain-visualize=:\n\n| Key         | Command                            | Description                                                                       |\n|-------------+------------------------------------+-----------------------------------------------------------------------------------|\n| m           | =org-brain-visualize-mind-map=       | Toggle between normal and mind-map visualization.                                 |\n| j or TAB    | =forward-button=                     | Goto next link                                                                    |\n| k or S-TAB  | =backward-button=                    | Goto previous link                                                                |\n| b           | =org-brain-visualize-back=           | Like the back button in a web browser.                                            |\n| h or *      | =org-brain-add-child-headline= *     | Add a new child /headline/ to entry                                                 |\n| c           | =org-brain-add-child= *              | Add an existing entry, or a new /file/, as a child                                  |\n| C           | =org-brain-remove-child= *           | Remove one the entry's child relations                                            |\n| e           | =org-brain-annotate-edge=            | Annotate the connection between the visualized entry and the entry link at point. |\n| p           | =org-brain-add-parent= *             | Add an existing entry, or a new /file/, as a parent                                 |\n| P           | =org-brain-remove-parent= *          | Remove one of the entry's parent relations                                        |\n| f           | =org-brain-add-friendship= *         | Add an existing entry, or a new /file/, as a friend                                 |\n| F           | =org-brain-remove-friendship= *      | Remove one of the entry's friend relations                                        |\n| n           | =org-brain-pin= *                    | Toggle if the entry is pinned or not                                              |\n| N           | =org-brain-add-nickname=             | Add a nickname for the entry (you can have several names for the same entry)      |\n| s           | =org-brain-select-dwim=              | Select an entry for batch processing.                                             |\n| S           | =org-brain-select-map=               | Prefix key to do batch processing with selected entries.                          |\n| t           | =org-brain-set-title=                | Change the title of the entry.                                                    |\n| T           | =org-brain-set-tags=                 | Change the tags of the entry.                                                     |\n| d           | =org-brain-delete-entry=             | Choose an entry to delete.                                                        |\n| l           | =org-brain-visualize-add-resource=   | Add a new resource link in entry                                                  |\n| r           | =org-brain-open-resource=            | Choose and open a resource from the entry.                                        |\n| C-y         | =org-brain-visualize-paste-resource= | Add a new resource link from clipboard                                            |\n| a           | =org-brain-visualize-attach=         | Run =org-attach= on entry (headline entries only)                                   |\n| A           | =org-brain-archive=                  | Archive the entry (headline entries only)                                         |\n| o           | =org-brain-goto-current=             | Open current entry for editing                                                    |\n| O           | =org-brain-goto=                     | Choose and edit one of your =org-brain= entries                                     |\n| v           | =org-brain-visualize=                | Choose and visualize a different entry                                            |\n| V           | =org-brain-visualize-follow=         | Similar to =org-agenda-follow-mode=; view visualized entry in another window.       |\n| w           | =org-brain-visualize-random=         | Visualize one of your entries at random.                                          |\n| W           | =org-brain-visualize-wander=         | Visualize at random, in a set interval. =W= again to cancel.                        |\n| C-c C-x C-v | =org-toggle-inline-images=           | Display org-mode images in the entry text.                                        |\n| M           | Move prefix                        | Move (refile) the current entry.                                                  |\n| M r         | =org-brain-refile=                   | Move current entry to another entry (change local parent).                        |\n| M p         | =org-brain-change-local-parent=      | Choose among the entry's parents and make another of them the local parent.       |\n\nThe commands above marked with =*= can be run with the universal argument =C-u= in\norder to operate on the entry link at point instead of the visualized entry.\n\nYou may use =org-store-link= inside of =org-brain-visualize= in order to store a\nlink to the currently visualized =org-brain= entry.\n\nIf the /universal argument/ =C-u= is used when running =org-brain-visualize-random= or\n=org-brain-visualize-wander=, the randomized targets are restricted to descendants\n(children, grandchildren, grand-grandchildren etc) of the currently visualized\nentry. Use for instance =C-u W= to wander among the descendants.\n\nThe /universal argument/ =C-u= can also be used with =org-brain-open-resource=. This\nlets you choose not only resource from the visualized entry, but also from\ndescendants (children, grand-children, etc) of that entry.\n\nIf the /universal argument/ =C-u= is used when calling =org-brain-annotate-edge= then\nthe annotation will be \"one-way\". The default behaviour is otherwise to annotate\nthe connection in both directions.\n\nWhen using the mind map visualization (toggle by pressing =m=), you can use the\nfollowing keybindings in order to show or hide successive levels of hierarchy\nrelative to the current entry.\n\n| Key | Command                         | Description                                                              |\n|-----+---------------------------------+--------------------------------------------------------------------------|\n| +   | =org-brain-show-descendant-level= | Show one more level of entries to the right (children of children, etc.) |\n| -   | =org-brain-hide-descendant-level= | Hide rightmost level of descendant entries                               |\n| z   | =org-brain-show-ancestor-level=   | Show one more level of entries to the left (parents of parents, etc.)    |\n| Z   | =org-brain-hide-ancestor-level=   | Hide leftmost level of ancestor entries                                  |\n\nIf you want to select several entries and then remove/add them as\nchildren/parents/friends you can use the =s= key (=org-brain-select-dwim=) to select\nan entry. If the point is over a button link to an entry, that entry will be\nselected, otherwise it will select the currently visualized entry. If the entry\nis already selected, it will be unselected instead.\n\nOnce you have selected all the entries you wish to use, you can use the =S= prefix\nkey to do batch processing on the selected entries. The keybindings in this\nprefix keymap is identical to those in =org-brain-visualize=. You could for\ninstance use =S c= to add all selected entries as children to the visualized\nentry, or =S P= to remove the parent relationship of the selected entries. When\nyou're done and wish to clear the selection use =org-brain-clear-selected=, which\nis bound to =S s=.\n\n** Editing text from =org-brain-visualize-mode=\n\nIf you have the =polymode= package installed you can edit your entries directly from =org-brain-visualize-mode=. Run =M-x org-brain-polymode= or add =org-brain-polymode= to =org-brain-visualize-mode-hook=. After editing you can use =C-x C-s= (bound to =org-brain-polymode-save=) to save your changes.\n\n** Editing from =org-mode=\n\nYou can edit =org-brain= entries directly from =org-mode=. You can use the default\n=org-mode= outline structure to define parent/children relationships, but keep in\nmind that only entries with an =ID= property will be considered as entries to\n=org-brain=; use =M-x org-brain-get-id= to create an =ID= property to the current\n=org-mode= headline. Another alternative is to use =M-x org-brain-refile= which will\ncreate the ids for you. You can also create IDs for all headlines in the buffer\nwith =M-x org-brain-ensure-ids-in-buffer=, and you might find it useful to add\nthis to =before-save-hook=.\n\nMost of the commands available in =org-brain-visualize= can also be used in\n=org-mode= directly, in which case they will operate on the \"entry at point\". In\nother words you can use =M-x org-brain-add-child= directly from =org-mode= in\norder to add a child to the =org-brain= entry at point. You may also want to use\nthe commands =org-brain-goto-\u003crelationsship\u003e= to navigate between entries.\n\nMost of the commands available in =org-brain-visualize-mode= is also bound to the\nprefix keymap =org-brain-prefix-map=. You can bind this to a key in =org-mode=, for\ninstance =C-c b=, and you could then type =C-c b p= to add a parent to the current\nentry. Example config: =(define-key org-mode-map (kbd \"C-c b\")\n'org-brain-prefix-map)=.\n\nYou may want to create a link to an =org-brain= entry in an =org-mode= file (not\nnecessarily an =org-brain= file itself). =org-brain= provides several link types\nfor this purpose. You can use =org-insert-link= (bound to =C-c C-l= in\n=org-mode= by default) to insert one of these links. They all have in common\nthat they, when clicked, will open the =org-brain= entry for editing. When\ninserting a link like this, =org-brain= will run completion upon all your\nentries.\n\n- =brain:= :: The default kind of link. Just let's you visit another =org-brain=\n  entry when clicked. If the variable =org-brain-backlink= is =t= a brain-link will\n  also be created as a resource in the link target, linking back to where the\n  link was created. If =org-brain-backlink= is set to a string, that string will\n  be added as a prefix to the title of the backlink. *Example:* You set\n  =org-brain-backlink= to =\"\u003c-- \"= and create a =brain:= link in =Rabbits= linking to\n  =Carrots=. Now a resource with the description =\u003c-- Rabbits= will be created in\n  =Carrots=.\n- =brain-child:= :: When inserted using =org-insert-link= this will make\n                    the linked entry a child to the current =org-brain= entry,\n                    upon completion. Keep in mind that this doesn't work if you\n                    type the link manually; only by completion through\n                    =org-insert-link=.\n- =brain-parent:= :: Like =brain-child:= but makes the linked entry a parent of\n     the current entry.\n- =brain-friend:= :: Like =brain-child:= but adds the linked entry as a friend.\n- =brainswitch= :: If you have multiple brains you may want a link which switches to a specific brain and one of its entries. The =brainswitch= link allows for this.\n\nThe 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.\n\n** Other commands\n\nIf you're browsing a file and want to add the file -- or the current line in the file -- as a resource to an entry, you can use =M-x org-brain-add-file-as-resource= or =M-x org-brain-add-file-line-as-resource=. If any of these are run with /universal argument/ =C-u= then add the resources to current/last visualized entry.\n\n** General information\n\nIf you try to add a child/parent/friend to an entry which doesn't exist, that\nentry will be created. The same is true for many other commands prompting for an\nentry, like =org-brain-visualize=. The name of a new entry can be written like\nthis: =file::headline=. The =headline= will be created as a level one headline in\n=file=. If you create a new entry without the headline part, it will by default be\ncreated as a file entry. It is possible to change that though by setting the\nvariable =org-brain-default-file-parent= to a default file. Let's say you set the\nvariable to =\"brain\"= and then add the entry =Bananas= (a non-existent entry). That\nwould be the same thing as writing =brain::Bananas=.\n\nWhen adding children, parents, or friends, multiple entries can be added at once\nby separating their titles with =org-brain-entry-separator= (which is =;= by\ndefault). For instance =M-x org-brain-add-parent RET music;artists= would add\nboth =music= and =artists= as parents.\n\nAnother available command is =M-x org-brain-agenda=, which can be used to run\n=org-agenda= on your =org-brain= files.\n\n** Slashes in file entry titles\n\nWhen giving a file entry a title, the title can not contain slashes (=/=) if\n=org-brain-file-entries-use-title= is =t=.\n\n** Renaming files in =org-brain=\n\nHeadline entries use =org-id= to identify themselves, so the headlines can be\nmanually renamed without worries. File entries, on the other hand, uses the\nfilename as the identifier. This will cause problems if you try to manually\nrename files inside of =org-brain=.\n\nIn order to rename a file, use =M-x org-brain-rename-file=.\n\n** Archiving entries\n\n=org-archive= has a problem in =org-brain=: relationships are maintained, even\nthough the entry should really be removed from the brain. Because of this,\nplease use =org-brain-archive= instead. This command removes relationships to\nthe entry in the brain, before archiving it. The command also inserts handy\nlinks to the archived entry's relationships.\n\n** Special tags\n\nYou might have a headline which you do not really want as an entry in\n=org-brain=. The most basic way to exclude such a headline is simply to not add\nan =ID= property to it. However, =org-brain= also provide two tags, which you\ncan use to tag the headline:\n\n- =:nobrain:= :: This tag excludes the headline, and its subheadings, from your\n                 =org-brain= entries. You can change the tag name by modifying\n                 =org-brain-exclude-tree-tag=.\n- =:childless:= :: This tag does not exclude the headline, but it excludes the\n                   subheadings. You can change the tag name by modifying\n                   =org-brain-exclude-children-tag=. Works on file entries.\n\nThe following tags modifies the kind of information that is shown when an entry\nis visualized:\n\n- =:notext:= :: Do not show the entry's text in =org-brain-visualize=. You can\n                change the tag name by modifying =org-brain-exclude-text-tag=.\n- =:resourceless:= :: Do not show the entry's resources in\n     =org-brain-visualize=. You can change the tag name by modifying\n     =org-brain-exclude-resources-tag=.\n- =:showchildren:= :: By default local child entries aren't shown as text. By\n     setting this tag the entry get the entire subtree as text. You can change\n     the tag name by modifying =org-brain-show-children-tag=. Works on file\n     entries.\n- =:nosiblings:= :: You may have an entry with lots of children, and when you visualize one of these children you might not want to see the siblings from this parent. A good example would be if you have an =index= entry or similar. By tagging the parent with =nosiblings= the parent's children will not show siblings from that parent. You can change the tag name by modifying =org-brain-exclude-siblings-tag=.\n- :nolocalparent: :: This is similar to =:nosiblings:= but the tagged parent will\n     not be shown at all when one of its local children are visualized.\n\nThe following tags modify the way how information is shown when an\nentry is visualized.\n\n- =:ownline:= :: Make each child of the tagged entry appear on its own\n                 line when the tagged entry is visualized. This\n                 only affects the tagged entry. It works akin to\n                 temporarily setting =org-brain-child-fill-column-sexp=\n                 to =0=.\n\n- =:nosort:= :: Display each child of the tagged node in the order the\n                children are listed in the file, rather than in the\n                sorted order determined by\n                =org-brain-visualize-sort-function=. This affects the\n                order of the node’s children in both the child list\n                (when the tagged node is being visited) and in the\n                sibling list (when one of the tagged node’s children\n                is being visited).\n\n** Having multiple brains\n\nYou 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=. You can also use =brainswitch:= links in =org-mode= to switch brains.\n\nIf you run =org-brain-visualize= from inside an org-file in /the root/ of an org-brain directory, =org-brain= will automatically switch to this brain.\n\n** Take note!\n\n=org-brain= creates and uses several headline properties in the =PROPERTIES=\ndrawer of =org-mode= headlines:\n\n- =BRAIN_PARENTS=\n- =BRAIN_CHILDREN=\n- =BRAIN_FRIENDS=\n- =BRAIN_EDGE_$IDENTIFIER=\n- =ID=\n- =NICKNAMES=\n\nThese properties are also mirrored as file keywords at the top of file entries,\nfor instance =#+BRAIN_CHILDREN: 00c0f06c-9bd4-4c31-aed0-15bb3361d9a2=.\n\nThese properties/keywords are /not meant to be manipulated directly/! If you want\nto remove these properties, use the corresponding command instead\n(=org-brain-remove-child= or similar). There's currently command to remove\n=NICKNAMES= though, so at the moment that has to be done manually.\n\nYou might also see that =org-brain= inserts a =RESOURCES= drawer. It is okay to\nmodify this drawer manually.\n\nThe names of the parents/children/friends properties, the prefix for edge\nproperties and the =RESOURCES= drawer can customized by setting the variables\n=org-brain-parents-property-name=, =org-brain-children-property-name=,\n=org-brain-friends-property-name=, =org-brain-edge-property-prefix-name= and\n=org-brain-resources-drawer-name=, respectively. Of course, after doing any\ncustomization, the property/drawer names of existing brain files have to be\nadjusted manually.\n\n** =org-brain= is slow!\n\nIf 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.\n\nShould only the first call of =org-brain-visualize= be slow, an option may be to try persistent caching of the variable =org-brain-headline-cache=. Choose a [[https://www.emacswiki.org/emacs/SessionManagement][session management solution]] that works for you [[https://github.com/thierryvolpiatto/psession][(an option for helm users)]]. A simple and built-in method is to use the savehist package. To do so, you may add the following configuration:\n\n#+begin_src emacs-lisp\n(savehist-mode 1)\n(setq savehist-additional-variables '(org-brain-headline-cache))\n#+end_src\n\n* FAQ\n** Wrong number of arguments: (0 . 0), 2\n\nYou are probably using the version of =org-mode= that came with your Emacs install, which has a lower version than 9.2. Check the version of org you have installed with =M-x org-version=. See [[https://github.com/Kungsgeten/org-brain/issues/278][Github issue #278]].\n* Export to other formats\n\n=org-brain= has no built-in functionality for exporting to other formats. I've\nstarted experimenting with another package named [[https://github.com/Kungsgeten/org-brain-export][org-brain-export]] which might be\nmerged into =org-brain= in the future. =org-brain-export= is in VERY early stages of\ndevelopment.\n* Helm and Ivy\n\nIf you use [[https://github.com/emacs-helm/helm][Helm]] or [[https://oremacs.com/swiper/][Ivy]] you can use the commands =helm-brain= or =counsel-brain= respectively. These allow for visualizing entries, and adding parents/children/friends to the entry at point. They also allow selecting multiple entries.\n\nThese commands do not have any keybindings by default.\n\n* Backwards compatibility breaking changes\n** 0.7\n\nAs of version 0.7 /entry descriptions/ are deprecated. They made visualization slow, and it was quite a hassle to actually write them. The \"help echo\" text is now used for edge annotations instead.\n\n** 0.4\n\n/This is only relevant if you've been using org-brain before version 0.4/\n\nAs of version 0.4 (June 2017) =org-brain= has been rewritten, in order to\nincrease performance and add more options. Because of this, older setups are\nconsidered obsolete. Prior to 0.4 only files were considered entries, but now\nalso headlines with an =ID= property are included as entries. Prior to 0.4\n=org-brain= was using the =brain:= link and =#+BRAIN_PINNED:= file keyword to\nconnect files, which was slow due to the need of searching all files for links.\nIn version 0.4 =org-brain= uses a combination of headline properties, file\nkeywords, =org-id=, and a data file (=org-brain-data-file=).\n\nNo data in old configurations should be lost, but you'll have to update the\nconnections between entries. This can be done by using =M-x\norg-brain-create-relationships-from-links=, but please backup your =org-brain=\ndirectory first.\n\nIt is still possible to add children to an entry by using the =brain-child:= link, but\nonly if the link is inserted with =org-insert-link= (bound to =C-c C-l= in\n=org-mode= by default). Linking to specific headlines in a file, via\n=brain:filename::*Headline= is *deprecated* and will no longer work, instead you\ncan convert the headline to an entry and link directly to that.\n\n* Other useful packages\n\nThere's some missing functionality in =org-brain=, which you may find useful.\nHowever there are other packages which might improve your =org-brain=\nexperience. Below are some suggestions (feel free to create an issue or send a\npull request if you have more examples), all of them should be available on\nMELPA.\n\n** Chronological entries with =org-expiry=\n\n=org-brain= doesn't add any information on when entries are created, so it is hard\nget a list of your entries in chronological order. I've managed to use\n=org-expiry= (part of =org-plus-contrib=) to add a =CREATED= property to all =org-brain=\nheadline entries. Then we can use =org-agenda= to show the entries in\nchronological order.\n\n#+BEGIN_SRC emacs-lisp\n  ;; Setup org-expiry and define a org-agenda function to compare timestamps\n  (require 'org-expiry)\n  (setq org-expiry-inactive-timestamps t)\n  (defun org-expiry-created-comp (a b)\n    \"Compare `org-expiry-created-property-name' properties of A and B.\"\n    (let ((ta (ignore-errors\n                (org-time-string-to-seconds\n                 (org-entry-get (get-text-property 0 'org-marker a)\n                                org-expiry-created-property-name))))\n          (tb (ignore-errors\n                (org-time-string-to-seconds\n                 (org-entry-get (get-text-property 0 'org-marker b)\n                                org-expiry-created-property-name)))))\n      (cond ((if ta (and tb (\u003c ta tb)) tb) -1)\n            ((if tb (and ta (\u003c tb ta)) ta) +1))))\n\n  ;; Add CREATED property when adding a new org-brain headline entry\n  (add-hook 'org-brain-new-entry-hook #'org-expiry-insert-created)\n\n  ;; Finally add a function which lets us watch the entries chronologically\n  (defun org-brain-timeline ()\n    \"List all org-brain headlines in chronological order.\"\n    (interactive)\n    (let ((org-agenda-files (org-brain-files))\n          (org-agenda-cmp-user-defined #'org-expiry-created-comp)\n          (org-agenda-sorting-strategy '(user-defined-down)))\n      (org-tags-view nil (format \"+%s\u003e\\\"\\\"\" org-expiry-created-property-name))))\n#+END_SRC\n\nNow we can use =org-brain-timeline= to view entries in chronological order (newest\nfirst).\n\n** [[https://github.com/rexim/org-cliplink][org-cliplink]]\n\n#+BEGIN_QUOTE\nA 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.\n#+END_QUOTE\n\nHere'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=.\n\n#+BEGIN_SRC emacs-lisp\n  (defun org-brain-cliplink-resource ()\n    \"Add a URL from the clipboard as an org-brain resource.\n  Suggest the URL title as a description for resource.\"\n    (interactive)\n    (let ((url (org-cliplink-clipboard-content)))\n      (org-brain-add-resource\n       url\n       (org-cliplink-retrieve-title-synchronously url)\n       t)))\n\n  (define-key org-brain-visualize-mode-map (kbd \"L\") #'org-brain-cliplink-resource)\n#+END_SRC\n\n** [[https://github.com/noctuid/link-hint.el][link-hint]]\n\n#+BEGIN_QUOTE\nlink-hint.el is inspired by the link hinting functionality in vim-like browsers\nand browser plugins such as pentadactyl. It provides commands for using avy to\nopen or copy \"links.\"\n#+END_QUOTE\n\nAfter installing =link-hint= you could bind =link-hint-open-link= to a key, and\nuse it in =org-brain-visualize-mode=. If you only want to use =link-hint= in\n=org-brain-visualize-mode=, you could add the following to your init-file:\n\n#+BEGIN_SRC emacs-lisp\n  (define-key org-brain-visualize-mode-map (kbd \"C-l\") #'link-hint-open-link)\n#+END_SRC\n\n** [[http://www.gnuvola.org/software/aa2u/][ascii-art-to-unicode]]\n\n#+BEGIN_QUOTE\nConverts simple ASCII art line drawings in the region of the current buffer to\nUnicode.\n#+END_QUOTE\n\n=ascii-art-to-unicode= is useful if you want =org-brain-visualize-mode= to look\na bit nicer. After installing, add the following to your init-file:\n\n#+BEGIN_SRC emacs-lisp\n  (defface aa2u-face '((t . nil))\n    \"Face for aa2u box drawing characters\")\n  (advice-add #'aa2u-1c :filter-return\n              (lambda (str) (propertize str 'face 'aa2u-face)))\n  (defun aa2u-org-brain-buffer ()\n    (let ((inhibit-read-only t))\n      (make-local-variable 'face-remapping-alist)\n      (add-to-list 'face-remapping-alist\n                   '(aa2u-face . org-brain-wires))\n      (ignore-errors (aa2u (point-min) (point-max)))))\n  (with-eval-after-load 'org-brain\n    (add-hook 'org-brain-after-visualize-hook #'aa2u-org-brain-buffer))\n#+END_SRC\n\n** [[https://github.com/domtronn/all-the-icons.el][all-the-icons]]\n\n#+BEGIN_QUOTE\nA utility package to collect various Icon Fonts and propertize them within Emacs.\n#+END_QUOTE\n\nAfter installing =all-the-icons= you could decorate the resources in =org-brain=, by using\n=org-brain-after-resource-button-functions=. Here's a small example:\n\n#+BEGIN_SRC emacs-lisp\n  (defun org-brain-insert-resource-icon (link)\n    \"Insert an icon, based on content of org-mode LINK.\"\n    (insert (format \"%s \"\n                    (cond ((string-prefix-p \"brain:\" link)\n                           (all-the-icons-fileicon \"brain\"))\n                          ((string-prefix-p \"info:\" link)\n                           (all-the-icons-octicon \"info\"))\n                          ((string-prefix-p \"help:\" link)\n                           (all-the-icons-material \"help\"))\n                          ((string-prefix-p \"http\" link)\n                           (all-the-icons-icon-for-url link))\n                          (t\n                           (all-the-icons-icon-for-file link))))))\n\n    (add-hook 'org-brain-after-resource-button-functions #'org-brain-insert-resource-icon)\n#+END_SRC\n\nYou could also use =all-the-icons= to add icons to entry [[https://orgmode.org/manual/Categories.html][categories]]. For instance if you have two categories named /computers/ and /books/ which you want icons for:\n\n#+BEGIN_SRC emacs-lisp\n  (setq org-agenda-category-icon-alist\n        `((\"computers\" ,(list (all-the-icons-material \"computer\")) nil nil :ascent center)\n          (\"books\" ,(list (all-the-icons-faicon \"book\")) nil nil :ascent center)))\n#+END_SRC\n\n** [[http://jblevins.org/projects/deft/][deft]]\n\n#+BEGIN_QUOTE\nAn Emacs mode for quickly browsing, filtering, and editing directories of plain\ntext notes, inspired by Notational Velocity.\n#+END_QUOTE\n\nAfter installing =deft=, you can add the function below to your init-file.\n\n#+BEGIN_SRC emacs-lisp\n  (defun org-brain-deft ()\n    \"Use `deft' for files in `org-brain-path'.\"\n    (interactive)\n    (let ((deft-directory org-brain-path)\n          (deft-recursive t)\n          (deft-extensions '(\"org\")))\n      (deft)))\n#+END_SRC\n\n** [[https://github.com/alphapapa/helm-org-rifle][helm-org-rifle]]\n\n#+BEGIN_QUOTE\nIt searches both headings and contents of entries in Org buffers, and it\ndisplays entries that match all search terms, whether the terms appear in the\nheading, the contents, or both.\n#+END_QUOTE\n\nAfter installing =helm-org-rifle=, you can add the function below to your\ninit-file.\n\n#+BEGIN_SRC emacs-lisp\n  (defun helm-org-rifle-brain ()\n    \"Rifle files in `org-brain-path'.\"\n    (interactive)\n    (let ((helm-org-rifle-close-unopened-file-buffers nil))\n      (helm-org-rifle-directories (list org-brain-path))))\n\n  (defun helm-org-rifle-open-in-brain (candidate)\n    (-let (((buffer . pos) candidate))\n      (with-current-buffer buffer\n        (goto-char pos)\n        (org-brain-visualize-entry-at-pt))))\n\n  (add-to-list 'helm-org-rifle-actions\n               (cons \"Show entry in org-brain\" 'helm-org-rifle-open-in-brain)\n               t)\n#+END_SRC\n\n** [[https://github.com/weirdNox/org-noter][org-noter]]\n\n#+BEGIN_QUOTE\nOrg-noter's purpose is to let you create notes that are kept in sync when you scroll through the [PDF etc] document\n#+END_QUOTE\n\nThanks to [[https://github.com/rosetree][rosetree]] for providing this tip! After installing =org-noter=, add the following to your init-file:\n\n#+BEGIN_SRC emacs-lisp\n(add-hook 'org-noter-insert-heading-hook #'org-id-get-create)\n(defun org-brain-open-org-noter (entry)\n    \"Open `org-noter' on the ENTRY.\nIf run interactively, get ENTRY from context.\"\n    (interactive (list (org-brain-entry-at-pt)))\n    (org-with-point-at (org-brain-entry-marker entry)\n      (org-noter)))\n#+END_SRC\n\n=org-brain-open-org-noter= will run =org-noter= on the current entry. This lets you save your PDF notes in =org-brain=, so you can link to them from other entries etc. It can be a good idea to add this command to =org-brain-visualize=, like this:\n\n#+BEGIN_SRC emacs-lisp\n  (define-key org-brain-visualize-mode-map (kbd \"\\C-c n\") 'org-brain-open-org-noter)\n#+END_SRC\n\n** [[https://github.com/scallywag/org-board][org-board]]\n#+BEGIN_QUOTE\norg-board is a bookmarking and web archival system for Emacs Org mode, building\non ideas from Pinboard. It archives your bookmarks so that you can access them\neven when you're not online, or when the site hosting them goes down.\n#+END_QUOTE\n\n* Similar packages\n\nThe Emacs Wiki has an article about [[https://www.emacswiki.org/emacs/WikiModes][wiki modes in Emacs]].\n\n** [[https://github.com/jethrokuan/org-roam][org-roam]]\n\n#+BEGIN_QUOTE\nOrg-roam is a Roam replica built on top of the all-powerful Org-mode.\n\nOrg-roam is a solution for effortless non-hierarchical note-taking with\nOrg-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.\nOrg-roam should also work as a plug-and-play solution for anyone already using\nOrg-mode for their personal wiki.\n\nOrg-roam aims to implement the core features of Roam, leveraging the mature\necosystem around Org-mode where possible. Eventually, we hope to further\nintroduce features enabled by the Emacs ecosystem.\n#+END_QUOTE\n\n** [[https://github.com/l3kn/org-zettelkasten][Org Zettelkasten]]\n\n#+begin_quote\nAn opinionated setup for managing large collections of interlinked org files.\n#+end_quote\n\n** [[https://github.com/caiorss/org-wiki][org-wiki]]\n\n#+BEGIN_QUOTE\nOrg-wiki is a org-mode extension that provides tools to manage and build\npersonal wiki or desktop wiki where each wiki page is a org-mode file.\n#+END_QUOTE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKungsgeten%2Forg-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKungsgeten%2Forg-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKungsgeten%2Forg-brain/lists"}