Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Table of Contents


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)
  (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)
  (: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.

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.


Link format

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

Main functions

Find a gkroam file and open it. If it does not exist, create a new one. Just like ido-find-file.

Insert a page bracket link at point.

Delete one or more gkroam pages.

Create or open ‘daily notes’ page.

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.

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.

Edit link in minibuffer. This function is very useful when brackets are hidden.

Show page’ unlinked references in a side window. Click link in unlinked references to link it to reference.

Hide and show brackets of link and hashtag.

Whether to prettify gkroam page.

Update current buffer’s references. Actually, references are updated automatically.

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: 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’.


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!


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


A lightweight roam replica on top of emacs org-mode.






Sponsor this project


No packages published