Gkroam is a lightweight Roam Research replica, built on top of emacs org-mode. It uses ‘ripgrep’ to search links on pages and insert references at the bottom of org pages automatically. The principle of Gkroam is “Be faithful to Roam Research”.
More demo pictures see here.
Clone this repo and add gkroam to your emacs load-path. My configurations are as follows. Feel free to modify them as to however you prefer.
Now, you can also install gkroam from Melpa with package-install.
(use-package gkroam
:ensure t
:hook (after-init . gkroam-mode)
:init
(setq gkroam-root-dir "~/gkroam/org/")
(setq gkroam-prettify-page-flag t
gkroam-show-brackets-flag nil
gkroam-use-default-filename t
gkroam-window-margin 4)
:bind
(:map gkroam-mode-map
(("C-c r I" . gkroam-index)
("C-c r d" . gkroam-daily)
("C-c r D" . gkroam-delete)
("C-c r f" . gkroam-find)
("C-c r i" . gkroam-insert)
("C-c r n" . gkroam-dwim)
("C-c r e" . gkroam-link-edit)
("C-c r u" . gkroam-show-unlinked)
("C-c r p" . gkroam-toggle-prettify)
("C-c r t" . gkroam-toggle-brackets)
("C-c r R" . gkroam-rebuild-caches)
("C-c r g" . gkroam-update))))- db is used to cache page and headline ids.
- company is used to auto-complete double bracket links and hashtags.
- ripgrep(rg) is used to search reference links.
- Install the command line search tool ripgrep(rg) first and make sure it is in the exec-path list.
- Page’s headline should not match the regexp “^* [0-9]+ Linked References.*” because it’s the delimiter for page contents and reference region.
- Use
gkroam-rebuild-cachesto generate all caches. If you got an error when click a headline link, this command is also very useful. - For the following v2.4.2 update. Because v2.4.2 changed the format of backlink, please call command
gkroam-update-allbefore using other functions.
- page link:
{[<title>]} - page link with alias:
{[<title>][<alias>]} - headline link:
{[<title> » <headline>]} - headline link with alias:
{[<title> » <headline>][<alias>]}
gkroam-find
Find a gkroam file and open it. If it does not exist, create a new one. Just like ido-find-file.
gkroam-insert
Insert a page bracket link at point.
gkroam-delete
Delete one or more gkroam pages.
gkroam-daily
Create or open ‘daily notes’ page.
gkroam-dwim
Smartly create a new file. If in a region, read the text in region as file title. If a word at point, read the text at point as file title. Otherwise, use gkroam-find. Finally, insert a file link at point or in region.
gkroam-index
Show gkroam index buffer. Index buffer includes all gkroam pages’ title, word counts, mentions, updated time and created time. You can click mentions number to see all references in a side window.
gkroam-link-edit
Edit link in minibuffer. This function is very useful when brackets are hidden.
gkroam-show-unlinked
Show page’ unlinked references in a side window. Click link in unlinked references to link it to reference.
gkroam-toggle-brackets
Hide and show brackets of link and hashtag.
gkroam-toggle-prettify
Whether to prettify gkroam page.
gkroam-update
Update current buffer’s references. Actually, references are updated automatically.
gkroam-rebuild-caches
Rebuild all caches, including page and filename cache, headline and headline id cache, page and references cache. It may takes seconds to build all, please be patient.
v1.0: Auto update link references at the bottom of page buffer.v2.0: Use overlay to hide and show gkroam brackets accordingly and fix some bugs.v2.0.1: Fix ‘hide and show brackets’ problems in some main occasion. Such as newline, etc.v2.0.2: Fixgkroam-publish-current-file, automatically convert gkroam link to org link and convert it back after published (use ‘undo’, not reliable) . But it has problem with publishing the whole project.v2.0.3: Fixgkroam-publish-siteandgkroam-preview. Now you can publish and preview the whole roam site.v2.0.4: Many bugs fixed and code improvement.v2.1.0: A more powerful linked references system.v2.1.1: Change package name to ‘gkroam’.v2.2.0: Implementgkroam-edit.v2.3.0: Implement headline references, add a new minor modegkroam-dynamic-modeand renamegkroam-edittogkroam-capture.v2.3.1: A more reasonable way to insert links. Press “C-p RET” or “C-M-j” directly to skip headline completion for ivy user or just press “RET” for vanilla user.v2.3.2: Beautify page: unify org list bullet and beautify org checkbox. Better to turn it off when editing the page. Function `gkroam-toggle-beautify’.v2.3.3: Make page filename customizable, delete index file and show index in buffer.v2.3.4: Delete ‘gkroam-dynamic-brackets-mode’ and addgkroam-toggle-dynamicfunction.v2.3.5: Optimize gkroam page prettification, change ‘gkroam-toggle-beautify’ to `gkroam-toggle-prettify’.v2.3.6: Implement a perfect linked references workflow. When a link is the item of org plain list, the whole list structure will be shown. The same as any source block, verse block, etc.v2.3.7: Add headline id only when you insert a gkroam link. Use `gkroam-rebuild-caches’ command to rebuild headline and id caches.v2.4.0- Delete
gkroam-toggle-dynamiccommand - Set gkroam-mode as a minor mode, instead of a major mode derived from org-mode
- Use text properties to render gkroam links.
- More caches and a big improvement in performance.
- Cache gkroam pages and their filenames.
- Cache gkroam pages and their references. Upadte references only when there’re changes in references.
- Prettify and enhance linked references
- Change backlink format to “{{page::line-number}{alias}}”
- Show list item’s parent items above it and shadow them.
- Highlight each reference region.
- Jump back to the specific line when click backlink.
- Delete
v2.4.1- Implement a Roam Research like index buffer.
- Add new command
gkroam-delete. - Rename ‘gkroam-smart-new’ to
gkroam-dwim.
v2.4.2: Implement ‘unlinked references’.- Use command `gkroam-show-unlinked’ to show pages’ unlinked references in a side window.
- Click link in unlinked references to link it to reference.
v2.4.3: Change backlink format to org-link format and delete ‘gkroam-capture’.
Recently, I have been watching videos about Roam Research. From these, I have gotten lots of ideas on how to improve gkroam. The ideas are as follows:
- [X] Simply insert linked references at the bottom of page.
- [X] Add “gkroam-daily” function to open a ‘daily notes’ page.
- [X] Custom link notation: “{[page-title]}” for page link, “#{[page-title]}” for hashtag.
- [X] Do auto completion after input brackets and hash symbol.
- [X] Automatically hide and show brackets when move to a line including gkroam links.
- [X] Convert gkroam link to org file link before publish and convert back when published.
- [X] A more reasonable linked references form.
- [X] Implement roam research like sidebar, named ‘gkroam-edit’ function.
- [X] Implement org headline references, add a new minor mode
gkroam-dynamic-mode. - [X] Beautify gkroam page: set window margin, unify bullet style and so on.
- [X] Make page filename customizable.
- [X] Generate headline id only when you insert a gkroam link.
- [X] Implement ‘unlinked references’.
- [ ] Support the original format of org-link with gkroam link.
- [ ] Implement ‘linked references’ filter function.
- [ ] Implement ‘block reference’ and ‘block embed’.
More in future!