Need help with gkroam?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

178 Stars 10 Forks GNU General Public License v3.0 303 Commits 3 Opened issues


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

Services available


Need anything else?

Contributors list

[[][file:]] [[][file:]]

  • Table of Contents :TOC_3:
    • [[#introduction][Introduction]]
    • [[#demos][Demos]]
    • [[#installation][Installation]]
    • [[#dependencies][Dependencies]]
    • [[#important-tips][Important Tips]]
    • [[#usage][Usage]]
    • [[#link-format][Link format]]
    • [[#main-functions][Main functions]]
    • [[#changelog][ChangeLog]]
    • [[#todolist][TodoList]]
    • [[#credits][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=.

#+BEGINSRC emacs-lisp (use-package gkroam :ensure t :hook (after-init . gkroam-mode) :init (setq gkroam-root-dir "~/gkroam/org/") (setq gkroam-prettify-page-p t gkroam-show-brackets-p 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)))) #+ENDSRC

** 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: ={[]}=
- page link with alias: ={[<title>][<alias>]}=

<li>headline link: ={[<title> » <headline>]}=</li>
<li>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/.

=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

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.