README.org

Table of Contents

• Introduction
• Demos
• Installation
• Dependency
• Usage
• ChangeLog
• TodoList
• Acknowledgements

Introduction

Gkroam is a light-weight roam 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 many aspects. More useful functionality will be implemented in future.

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.

(use-package gkroam
  :load-path "~/iCloud/hack/gkroam/"
  :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 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.el is used for html preview, install it in emacs.
• undo-tree.el is used to restore gkroam formatted link after publishing.
• ripgrep(rg) is used for search reference link, install it through os package manager and ensure that the command rg is in exec-path variable.

Usage

Shortcut keys:

Main functions:

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

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

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.
• [ ] Implement roam research like sidebar, named ‘gkroam-side-edit’ function.
• [ ] Implement the slash magics, after input slash, do completion for commands.
• [ ] 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.