diff --git a/README.md b/README.md index 4adaedd..d37f74c 100644 --- a/README.md +++ b/README.md @@ -33,38 +33,170 @@ solution for anyone already using Org-mode for their personal wiki. ## Installation -You can install `org-roam` using `package.el`: +Down below you will find basic installation instructions for how to quickly +install `org-roam` using various environments for various purposes. For more +detailed information, please read the [manual][docs]. + +### Using `package.el` +
+Toggle instuctions + +You can install `org-roam` from [MELPA](https://melpa.org/) or [MELPA +Stable](https://stable.melpa.org/) using `package.el`: ``` M-x package-install RET org-roam RET ``` -Here's a sample configuration with `use-package`: +Here's a very basic sample for configuration of `org-roam` using `use-package`: ```emacs-lisp (use-package org-roam - :ensure t - :custom - (org-roam-directory (file-truename "/path/to/org-files/")) - :bind (("C-c n l" . org-roam-buffer-toggle) - ("C-c n f" . org-roam-node-find) - ("C-c n g" . org-roam-graph) - ("C-c n i" . org-roam-node-insert) - ("C-c n c" . org-roam-capture) - ;; Dailies - ("C-c n j" . org-roam-dailies-capture-today)) - :config - (org-roam-db-autosync-mode) - ;; If using org-roam-protocol - (require 'org-roam-protocol)) + :ensure t + :custom + (org-roam-directory (file-truename "/path/to/org-files/")) + :bind (("C-c n l" . org-roam-buffer-toggle) + ("C-c n f" . org-roam-node-find) + ("C-c n g" . org-roam-graph) + ("C-c n i" . org-roam-node-insert) + ("C-c n c" . org-roam-capture) + ;; Dailies + ("C-c n j" . org-roam-dailies-capture-today)) + :config + (org-roam-db-autosync-mode) + ;; If using org-roam-protocol + (require 'org-roam-protocol)) ``` -The `file-truename` function is only necessary when you use symbolic links -inside `org-roam-directory`: Org-roam does not resolve symbolic links. +Note that the `file-truename` function is only necessary when you use symbolic +link to `org-roam-directory`. Org-roam won't automatically resolve symbolic link +to the directory. +
-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. +### Using `straight.el` +
+Toggle instuctions + +Installation from MELPA or MELPA Stable using `straight.el`: + +```emacs-lisp +(straight-use-package 'org-roam) +``` + +Or with `use-package`: + +```emacs-lisp +(use-package org-roam + :straight t + ...) +``` + +If you need to install the package directly from the source repository, instead +of from MELPA, the next sample shows how to do so: + +```emacs-lisp +(use-package org-roam + :straight (:host github :repo "org-roam/org-roam" + :files (:defaults "extensions/*")) + ...) +``` + +If you plan to use your own local fork for the development and contribution, the +next sample will get you there: + +```emacs-lisp +(use-package org-roam + :straight (:local-repo "/path/to/org-roam-fork" + :files (:defaults "extensions/*") + :build (:not compile)) + ...) +``` +
+ +### Using Doom Emacs +
+Toggle instuctions + +Doom's `:lang org` module comes with support for `org-roam`, but it's not +enabled by default. To activate it pass `+roam2` flag to `org` module in your +`$DOOMDIR/init.el` (e.g. `(org +roam2)`), save the file and run `doom sync -u` +in your shell. + +To provide better stability, Doom pins the package to a specific commit. If you +need to unpin it *(not recommended doing that, request Doom to bump the package +instead)* use the next in your `packages.el`: + +```emacs-lisp +(unpin! org-roam) +``` + +If for some reasons you want to use a different recipe for `org-roam`, you can +use the next form in your `packages.el` to install the package from a recipe +repository (e.g. MELPA): + +```emacs-lisp +(package! org-roam) +``` + +You can pass `:pin "commit hash"` to pin the package to a specific commit. + +With the next sample you can install the package directly from the source +repository: + +```emacs-lisp +(package! org-roam + :recipe (:host github :repo "org-roam/org-roam" + :files (:defaults "extensions/*"))) +``` + +And if you plan to use your own local fork for the development or contribution, +the next sample will get you there: + +```emacs-lisp +(package! org-roam + :recipe (:local-repo "/path/to/org-roam-fork" + :files (:defaults "extensions/*") + :build (:not compile))) +``` +
+ +### Without a package manager +
+Toggle instructions + +To install the package without using a package manager you have the next two +options: + +1. Install the package by cloning it with `git` from the source repository. +2. Or install the package by downloading the latest [release + version](https://github.com/org-roam/org-roam/releases). + +In both of the cases you will need to ensure that you have all the required +dependencies. These include: + +- dash +- f +- s +- org (9.4 is the minimal required version!) +- emacsql +- emacsql-sqlite +- magit-section +- filenotify-recursive + +After installing the package, you will need to properly setup `load-path` to the +package: + +``` emacs-lisp +(add-to-list 'load-path "/path/to/org-roam/") +(add-to-list 'load-path "/path/to-org-roam/extensions/") +``` + +After which you should be able to resolve `(require 'org-roam)` call without any +problems. + +Org-roam also comes with `.texi` files to integrate with Emacs' built-in Info +system. Read the manual to find more details for how to install them manually. +
## Getting Started