/gkroam.el

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

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

https://melpa.org/packages/gkroam-badge.svg https://stable.melpa.org/packages/gkroam-badge.svg

Table of Contents

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

./demos/page-beautify.gif

./demos/headline-reference.gif

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

./demos/better-headline-insert.gif

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/")
  (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 healines’ id and cache them in db manually.

Usage

Link format

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

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 https://github.com/Kinneyzhang/gkroam.el/issues or https://github.com/Kinneyzhang/gkroam.el/pulls.

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