Table of Contents
Block-ref and block-embed are two concepts in Roam Research. With the two functionalities, users can easily refer or include one block in another block or page. Roam-block has implemented these in emacs.
What’s the differences between block-ref and block-embed? Block-ref means a reference refers to a block, while block-embed embed one block in any place. When you change the content of the original block, both of the block-ref and block-embed content could be synchronized. But, there’re some differences.
For block-ref, you cannot change the content of it because it’s actually a reference literally. This feature suits the situation where you don’t want to change the block content any where but refer to the original one. In roam-block, block refs will be synchronized after buffer saved.
For block-embed, you can change the content of any embed blocks and all the blocks which are derived from one original block will be synchronized. In roam-block, embed blocks will be synchronized at real time.
Look at the gifs for a quick view:
Look at the video for details:
Firstly, install the dependencies:
Then, clone roam-block repo to your local directory and add the following codes to your emacs configuration:
(add-to-list 'load-path "path/to/roam-block/") (require 'roam-block) (setq roam-block-home '("~/roam-block/") roam-block-ref-highlight t roam-block-embed-highlight t) (roam-block-mode 1) (define-key roam-block-mode-map (kbd "C-c b r s") #'roam-block-ref-store) (define-key roam-block-mode-map (kbd "C-c b r i") #'roam-block-ref-insert) (define-key roam-block-mode-map (kbd "C-c b r d") #'roam-block-ref-delete) (define-key roam-block-mode-map (kbd "C-c b r t") #'roam-block-ref-highlight-toggle) (define-key roam-block-mode-map (kbd "C-c b e s") #'roam-block-embed-store) (define-key roam-block-mode-map (kbd "C-c b e i") #'roam-block-embed-insert) (define-key roam-block-mode-map (kbd "C-c b e t") #'roam-block-embed-highlight-toggle) (define-key roam-block-mode-map (kbd "C-c b d") #'roam-block-delete-block)
If you prefer
use-package, use the following codes:
(use-package roam-block :load-path "path/to/roam-block/" :hook (after-init . roam-block-mode) :init (setq roam-block-home '("~/roam-block/") roam-block-ref-highlight t roam-block-embed-highlight t) :bind (:map roam-block-mode-map (("C-c b r s" . roam-block-ref-store) ("C-c b r i" . roam-block-ref-insert) ("C-c b r d" . roam-block-ref-delete) ("C-c b r t" . roam-block-ref-highlight-toggle) ("C-c b e s" . roam-block-embed-store) ("C-c b e i" . roam-block-embed-insert) ("C-c b e t" . roam-block-embed-highlight-toggle) ("C-c b d" . roam-block-delete-block))))
Roam-block can only work on the directories defined in
roam-block-home. The value of the variable is a list, each item must be a valid directory path. You may want to add you org-roam directory to the variable.
Store the ref of current block or blocks in an active region.
Insert the ref at where you want to refer the blocks.
Delete the read only block ref at point or close to current point.
Highlight block ref display or not.
Store the embed block of current block.
Insert the embed block at point.
Highlight embed blocks or not.
Delete block at point.
Get an error message “(roam-block) No valid block here!” when try to store block-ref or block-embed. What to do?
Roam-block sets a uuid overly for each block after saving buffer. The error message means that there’s no uuid overlay in current block. You should first save buffer, then use the ‘store command’ of block-ref or block-embed. Considering of this, it’s better to set ‘auto-save’ for your emacs. similarly, the content of all block-refs will be synchronized after saving buffer.
- [ ] Quick insert a block-ref or block-embed by querying database instead of using the ‘store command’.
- [ ] Synchronize the content of block-ref at real time, like what block-embed have implemented.
- [ ] Support roam-block in markdown.
The code of roam-block was organized by module, it’s easy to read and understand. Welcome to contribute PRs.
Copyright © Kinney Zhang and contributors. Distributed under the GPL v3.0.