awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-01 12:17:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

(doc) Update README (#1351)

Browse Source
This commit is contained in:
Jethro Kuan
2020-12-19 17:53:25 +08:00
committed by GitHub
parent ecf515f650
commit 3ce6e299d4
1 changed files with 46 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
README.md
View File

@ -1,47 +1,35 @@
[![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
[![GitHub Release](https://img.shields.io/github/v/release/org-roam/org-roam)](https://img.shields.io/github/v/release/org-roam/org-roam)
[![MELPA](https://melpa.org/packages/org-roam-badge.svg)](https://melpa.org/#/org-roam)
# Org-roam [![GitHub Release][release-badge]][release] [![MELPA][melpa-badge]][melpa] [![License GPL 3][gpl3-badge]][gpl3]
<img src="https://www.orgroam.com/img/logo.svg" align="right" alt="Org-roam Logo" width="240">
## Synopsis
Org-roam is a plain-text knowledge management system. It brings some of
[Roam's][roamresearch] more powerful features into the [Org-mode][org]
ecosystem.
> **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 borrows principles from the Zettelkasten method, providing a solution
for non-hierarchical note-taking. It should also work as a plug-and-play
solution for anyone already using Org-mode for their personal wiki.
Org-roam is a [Roam][roamresearch] replica built on top of the
all-powerful [Org-mode][org].
- **Private and Secure**: Edit your personal wiki completely offline, entirely
in your control. Encrypt your notes with GPG. Take lasting notes in
plain-text.
- **Networked Thought**: Connect notes and thoughts together with ease using
backlinks. Discover surprising and previously unseen connections in your notes
with the built-in graph visualization.
- **Extensible and Powerful**: Leverage Emacs' fantastic text-editing interface,
and the mature Emacs and Org-mode ecosystem of packages.
- **Free and Open Source**: Org-roam is licensed under the GNU General Public
License version 3 or later.
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](https://github.com/technovangelist/) has produced a video
describing Org-roam and the concepts behind it:
[![Making Connections in your Notes](http://img.youtube.com/vi/Lg61ocfxk3c/0.jpg)](http://www.youtube.com/watch?v=Lg61ocfxk3c "Making Connections in your Notes")
Important links:
<p align="center">
<img src="https://www.orgroam.com/img/screenshot.png" alt="Org-roam Screenshot" width="738">
</p>
- **[Documentation][docs]**
- **[Discourse][discourse]**
- **[Slack][slack]**
## 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.
![img](doc/images/org-roam-graph.gif)
- **[Frequently Asked Questions][faq]**
- **[Changelog](CHANGELOG.md)**
## Installation
@ -51,7 +39,7 @@ 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`:
Here's a sample configuration with `use-package`:
```emacs-lisp
(use-package org-roam
@ -69,44 +57,30 @@ Here's a sample configuration with using `use-package`:
(("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][docs].
## 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](https://github.com/abo-abo/swiper#frequently-asked-questions))
Org-roam requires sqlite to function. Org-roam optionally uses Graphviz for
graph-related functionality. It is recommended to install PCRE-enabled ripgrep
for better performance and extended functionality.
## 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][issues] or on
Before creating a new topic/issue, please be mindful of our time and ensure that
it has not already been addressed on [GitHub][issues] or on
[Discourse][discourse].
- If you are new to Emacs and have problem setting up Org-roam, please ask your question on [Slack, channel #how-do-i][slack].
- For quick questions, please ask them on [Slack, channel #troubleshooting][slack].
- If something is not working as it should, or if you would like to suggest a new feature, please [create a new issue][issues].
- If you have questions about your workflow with the slip-box method, please find a relevant topic on [Discourse][discourse], or create a new one.
- If you are new to Emacs and have problem setting up Org-roam, please ask your
question on [Slack, channel #how-do-i][slack].
- For quick questions, please ask them on [Slack, channel
#troubleshooting][slack].
- If something is not working as it should, or if you would like to suggest a
new feature, please [create a new issue][issues].
- If you have questions about your workflow with the slip-box method, please
find a relevant topic on [Discourse][discourse], or create a new one.
## Knowledge Bases using Org-roam
- [Jethro Kuan](https://braindump.jethro.dev/)
([Source](https://github.com/jethrokuan/braindump/tree/master/org))
## Changelog
A changelog is being maintained [here](CHANGELOG.md)
## Contributing
To report bugs and suggest new feature use the issue tracker. If you
@ -116,12 +90,18 @@ request. Please also see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
## License
Copyright © Jethro Kuan and contributors. Distributed under the GNU
General Public License, Version 3
General Public License, Version 3.
[roamresearch]: https://www.roamresearch.com/
[org]: https://orgmode.org/
[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg
[gpl3-badge]: https://img.shields.io/badge/license-GPL_3-green.svg
[gpl3]: http://www.gnu.org/licenses/gpl-3.0.txt
[melpa-badge]: https://melpa.org/packages/org-roam-badge.svg
[melpa]: https://melpa.org/#/org-roam
[release-badge]: https://img.shields.io/github/v/release/org-roam/org-roam
[release]: https://github.com/org-roam/org-roam/releases
[docs]: https://www.orgroam.com/manual.html
[discourse]: https://org-roam.discourse.group/
[slack]: https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg
[issues]: https://github.com/org-roam/org-roam/issues
[faq]: https://www.orgroam.com/manual.html#FAQ