f206b5bbf9
When using gpg encrypted files it might happen (intended) that on a certain machine there is no key to decrypt that file. Currently an error of type 'file-error' will be raised and the cache building process will be aborted. So in a certain sense org-roam will not be functional in that case. Furthermore, when the the cache building process is run from the emacs initialisation it will come to a halt as well and the user will be left with a halfworking emacs instance. This patch changes the behaviour to just skipping over offending files while removing them from the db at the same time. Here an offending file is any file that cannot be read for indexing. As it stands this case only works reliably for the case of missing gpg keys. An error buffer will still show up and be prominently displayed, besides a log to the message buffer. Implementation note: This io error will only be caught during the first part of the cache rebuilding ("files and headlines"). If such an error would occur during the second part ("rebuild the rest") another (more severe) cause might be the problem and the user better be informed the hard way (i.e. the same behaviour as before). |
||
---|---|---|
.github | ||
doc | ||
tests | ||
.dir-locals.el | ||
.gitignore | ||
.readthedocs.yml | ||
BACKERS.md | ||
CHANGELOG.md | ||
default.mk | ||
LICENSE | ||
Makefile | ||
makem.sh | ||
org-roam-buffer.el | ||
org-roam-capture.el | ||
org-roam-compat.el | ||
org-roam-completion.el | ||
org-roam-dailies.el | ||
org-roam-db.el | ||
org-roam-dev.el | ||
org-roam-doctor.el | ||
org-roam-faces.el | ||
org-roam-graph.el | ||
org-roam-macs.el | ||
org-roam-protocol.el | ||
org-roam.el | ||
README.md |
Synopsis
NOTE: Org-roam builds upon Emacs and Org-mode, both of which are intricate tools that require time investment for mastery. This makes Org-roam less friendly for beginners, but extremely powerful for those familiar with the ecosystem, or willing to invest effort in it.
Org-roam is a Roam replica built on top of the all-powerful Org-mode.
Org-roam is a solution for effortless non-hierarchical note-taking with Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy. Org-roam should also work as a plug-and-play solution for anyone already using Org-mode for their personal wiki.
Org-roam aims to implement the core features of Roam, leveraging the mature ecosystem around Org-mode where possible. Eventually, we hope to further introduce features enabled by the Emacs ecosystem.
@technovangelist has produced a video describing Org-roam and the concepts behind it:
Important links:
A Preview
Here's a screencast of Org-roam. The org-roam-buffer
(window on the
right) shows backlinks for the active Org-roam buffer (window on the
left), as well as the surrounding content in the backlink file. The
database is built once, and updated incrementally. The graph is
generated from the link structure, and can be used to navigate to the
respective files.
Installation
You can install org-roam
using package.el
:
M-x package-install RET org-roam RET
Here's a sample configuration with using use-package
:
(use-package org-roam
:ensure t
:hook
(after-init . org-roam-mode)
:custom
(org-roam-directory "/path/to/org-files/")
:bind (:map org-roam-mode-map
(("C-c n l" . org-roam)
("C-c n f" . org-roam-find-file)
("C-c n g" . org-roam-graph-show))
:map org-mode-map
(("C-c n i" . org-roam-insert))
(("C-c n I" . org-roam-insert-immediate))))
org-roam-graph
by default expects to find the dot
executable
from the graphviz
package in the exec-path
.
Ensure graphviz
is installed and found if you want to use this
feature or customize your configuration for org-roam-graph
to use a
different tool.
For more detailed installation and configuration instructions (including for Doom and Spacemacs users), please see the documentation.
Frequently-asked Questions
Q: How do I create a note whose title already matches one of the candidates (e.g. creating bar
when barricade
already exists)?
A: With ivy
, you need to press C-M-j
to use the current input instead of the nearest candidate. (Source: ivy
’s
FAQ)
Getting Help
Before creating a new topic/issue, please be mindful of our time and ensure that it has not already been addressed on GitHub or on Discourse.
- If you are new to Emacs and have problem setting up Org-roam, please ask your question on Slack, channel #how-do-i.
- For quick questions, please ask them on Slack, channel #troubleshooting.
- If something is not working as it should, or if you would like to suggest a new feature, please create a new issue.
- If you have questions about your workflow with the slip-box method, please find a relevant topic on Discourse, or create a new one.
Knowledge Bases using Org-roam
Changelog
A changelog is being maintained here
Contributing
To report bugs and suggest new feature use the issue tracker. If you have some code which you would like to be merged, then open a pull request. Please also see CONTRIBUTING.md.
License
Copyright © Jethro Kuan and contributors. Distributed under the GNU General Public License, Version 3