Table of Contents

• Introduction
• Demos
• Installation
• Dependency
• Tips (important!)
• Usage
• ChangeLog
• TodoList
• Acknowledgements

Introduction

Gkroam is a lightweight Roam Research replica, built on top of emacs org-mode. It uses ‘ripgrep’ to search pages’ links and insert references at the bottom of org pages automatically. Almostly, gkroam imitates roam research in as many aspects as possible.

Demos

Installation

Clone this repo and add gkroam to your emacs load-path. My configurations are as follows. Feel free to modify them as you like.

Now, you can also install gkroam from Melpa with package-install.

(use-package gkroam
  :ensure t
  :init
  (setq gkroam-root-dir "~/gkroam/org/"
        gkroam-pub-dir "~/gkroam/site/")
  :bind
  (("C-c r G" . gkroam-update-all)
   ("C-c r g" . gkroam-update)
   ("C-c r d" . gkroam-daily)
   ("C-c r f" . gkroam-find)
   ("C-c r e" . gkroam-edit)
   ("C-c r n" . gkroam-smart-new)
   ("C-c r i" . gkroam-insert)
   ("C-c r I" . gkroam-index)
   ("C-c r p" . gkroam-preview)
   ("C-c r v" . gkroam-preview-current)
   ("C-c r t" . gkroam-toggle-brackets)))

Dependency

• simple-httpd is used to preview html.
• company is used to complete double brackets link and hashtags.
• undo-tree is used to restore gkroam formatted link after publishing.
• ripgrep(rg) is used to search reference link.

Tips (important!)

• Install ripgrep(rg) command line firstly and make sure it is in exec-path list.
• Please set gkroam-root-dir and gkroam-pub-dir variables properly and create the directories manually before calling gkroam commands.
• Set gkroam-page-template variable to custom your own org file meta in header.
• If you want to use your custom publish css, set gkroam-pub-css variable.
• Do not set company-idle-delay variable to zero, it will causes an error. see issue#455.
• When double brackets were hidden, it needs double click to follow a page link. This is a known issue and will be solved recently.

Usage

Shortcut keys:

shortcut	function
{[]}	complete page link at point
#	complete hashtag at point

Main functions:

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

gkroam-edit
Edit many pages in a side window and save changes by pressing C-c C-c, abort changes by pressing C-c C-k.

gkroam-daily
Create or open ‘daily notes’ page.

gkroam-toggle-brackets
Hide and show brackets of link and hashtag.

gkroam-insert
Insert a page bracket link at point.

gkroam-smart-new
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. At last, insert a file link at point or in region.

gkroam-index
Show gkroam index page. Well, it’s just a simple site map because I have not get good ideas about it. Feel free to give me an issue or PR.

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

gkroam-update-all
Update all files’ references.

gkroam-publish-current-file
Publish current file to html.

gkroam-preview-current
Preview current file in browser.

gkroam-publish-site
Publish the whole gkroam site.

gkroam-preview
Preview gkroam site’s index page.

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 and bump version to 2.2.0.

TodoList

Recently, I have been watching videos about Roam Research. From it, I have got lots of ideas 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.
• [ ] Implement org headline linked references.
• [ ] Implement ‘block reference’ and ‘block embeds’.

More in future!

Acknowledgements

Thanks to cool guys in emacs-china.org who answered some key questions. Specially thanks to casouri, his bklink.el gives me lots of ideas.