README.org

Table of Contents

• Introduction
• Demos
• Installation
• Dependencies
• Tips (important)
• Usage
  • Link format
  • Main functions
• ChangeLog
• TodoList
• Acknowledgements

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. Gkroam imitates roam research in as many aspects as possible.

Demos

Beautify page

have changed the way (above) to insert page link:

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
  :init
  (setq gkroam-root-dir "~/gkroam/org/")
  (setq gkroam-window-margin 4)
  (setq org-startup-folded nil)
  :bind
  (("C-c r I" . gkroam-index)
   ("C-c r d" . gkroam-daily)
   ("C-c r f" . gkroam-find)
   ("C-c r i" . gkroam-insert)
   ("C-c r c" . gkroam-capture)
   ("C-c r e" . gkroam-link-edit)
   ("C-c r n" . gkroam-smart-new)
   ("C-c r b" . gkroam-toggle-beautify)
   ("C-c r t" . gkroam-toggle-brackets)
   ("C-c r D" . gkroam-toggle-dynamic)
   ("C-c r g" . gkroam-update)
   ("C-c r G" . gkroam-update-all)))

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.

Tips (important)

• Install the command line search tool ripgrep(rg) first and make sure it is in the exec-path list.
• Do not set the company-idle-delay variable to zero, it will causes an error. See issue#455.
• Use gkroam-build-caches to generate all headlines ids and cache them in db manually when you put your org files in the gkroam directory the very first time.

Usage

Link format

• page link: {[<title>]}
• headline link: {[<title> » <headline>]}
• page link with alias: {[<title>][<alias>]}
• 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-capture
Capture many pages in a side window and save changes by pressing C-c C-c, abort changes by pressing C-c C-k.

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

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

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

gkroam-toggle-beautify
Whether to beautify gkroam page.

gkroam-toggle-dynamic
Whether to show gkroam page in dynamic mode.

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. Finally, insert a file link at point or in region.

gkroam-index
Show gkroam index buffer. Well, it’s just a simple site map because I have not yet had a better idea about this yet. Feel free to contribute by opening an issue or PR.

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

gkroam-update-all
Update all files’ references.

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.

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.
• [ ] Implement linked references filter function.
• [ ] Implement ‘block reference’ and ‘block embed’.

More in future!

Acknowledgements

Thanks to the cool guys from emacs-china.org who answered some key questions. Also special thanks to casouri, his bklink.el gave me a lot of ideas.