Table of Contents

• Introduction
• Demos
• Installation
• Dependencies
• Important Tips
• Usage
  • Link format
  • Main functions
• ChangeLog
• TodoList
• Credits

Introduction

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”.

Demos

• Youtube
• Bilibili

More demo pictures see here.

Installation

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))))

Dependencies

• 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.

Important Tips

• 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-caches to 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-all before using other functions.

Usage

Link format

• page link: {[<title>]}
• page link with alias: {[<title>][<alias>]}
• headline link: {[<title> » <headline>]}
• headline link with alias: {[<title> » <headline>][<alias>]}

Main functions

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.

ChangeLog

• 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: Fix gkroam-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: Fix gkroam-publish-site and gkroam-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: Implement gkroam-edit .
• v2.3.0: Implement headline references, add a new minor mode gkroam-dynamic-mode and rename gkroam-edit to gkroam-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 add gkroam-toggle-dynamic function.
• 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-dynamic command
  • 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.
• 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’.

TodoList

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!

Credits

The original idea of Gkroam comes from casouri’s bklink.el.