diff --git a/CHANGELOG.md b/CHANGELOG.md index c21bcb5..148840f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog ## TBD +### Breaking +- [#2054](https://github.com/org-roam/org-roam/pull/2054) node: simplify default `org-roam-node-display-template`. + This was done so completions work fine by default on all completion systems. To restore the tabular vertical completion interface, set this in your configuration: + + ```emacs-lisp + (setq org-roam-node-display-template + (concat "${title:*} " + (propertize "${tags:10}" 'face 'org-tag))) + ``` + ### Added - [#2042](https://github.com/org-roam/org-roam/pull/2042) db: add `org-roam-db-extra-links-elements` and `org-roam-db-extra-links-exclude-keys` for fine-grained control over additional link parsing - [#2049](https://github.com/org-roam/org-roam/pull/2049) capture: allow ID to be used as part of `org-roam-capture-templates` diff --git a/README.md b/README.md index 907aeaa..807b504 100644 --- a/README.md +++ b/README.md @@ -47,30 +47,6 @@ Stable](https://stable.melpa.org/) using `package.el`: ``` M-x package-install RET org-roam RET ``` - -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)) -``` - -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. ### Using `straight.el` @@ -198,6 +174,33 @@ 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. +## Configuration + +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 + ;; If you're using a vertical completion framework, you might want a more informative completion interface + (setq org-roam-node-display-template (concat "${title:*} " (propertize "${tags:10}" 'face 'org-tag))) + (org-roam-db-autosync-mode) + ;; If using org-roam-protocol + (require 'org-roam-protocol)) +``` + +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. ## Getting Started [David Wilson](https://github.com/daviwil) of [System diff --git a/doc/org-roam.org b/doc/org-roam.org index d1926a0..5ce7b55 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -455,14 +455,15 @@ through `org-roam-node-read`. The presentation of these nodes are governed by closure is evaluated and the return value is used as the template. The closure must evaluate to a valid template string. -The default template is optimized for vertical completion frameworks, such as -Ivy and Selectrum. The additional space injected into the node completions may -confuse users that aren't using these frameworks. To remove the additional -spacing from the completions, set the node display template to something -simpler, such as: +If you're using a vertical completion framework, such as Ivy and Selectrum, +Org-roam supports the generation of an aligned, tabular completion interface. +For example, to include a column for tags up to 10 character widths wide, one +can set ~org-roam-node-display-template~ as such: #+begin_src emacs-lisp - (setq org-roam-node-display-template "${title}") + (setq org-roam-node-display-template + (concat "${title:*} " + (propertize "${tags:10}" 'face 'org-tag))) #+end_src * Customizing Node Caching diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 5ea3341..fc4dbb0 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -750,14 +750,15 @@ closure is evaluated and the return value is used as the template. The closure must evaluate to a valid template string. @end defvar -The default template is optimized for vertical completion frameworks, such as -Ivy and Selectrum. The additional space injected into the node completions may -confuse users that aren't using these frameworks. To remove the additional -spacing from the completions, set the node display template to something -simpler, such as: +If you're using a vertical completion framework, such as Ivy and Selectrum, +Org-roam supports the generation of an aligned, tabular completion interface. +For example, to include a column for tags up to 10 character widths wide, one +can set @code{org-roam-node-display-template} as such: @lisp -(setq org-roam-node-display-template "$@{title@}") +(setq org-roam-node-display-template + (concat "$@{title:*@} " + (propertize "$@{tags:10@}" 'face 'org-tag))) @end lisp @node Customizing Node Caching diff --git a/org-roam-node.el b/org-roam-node.el index 2a704c3..6140b0f 100644 --- a/org-roam-node.el +++ b/org-roam-node.el @@ -36,8 +36,7 @@ ;;; Options ;;;; Completing-read -(defcustom org-roam-node-display-template - (concat "${title:*} " (propertize "${tags:10}" 'face 'org-tag)) +(defcustom org-roam-node-display-template "${title}" "Configures display formatting for Org-roam node. Patterns of form \"${field-name:length}\" are interpolated based on the current node.