GitHub - Kinneyzhang/gk-roam.el: light-weight roam replica in emacs.

README.org

Gk-roam is a light-weight roam replica, built on top emacs OrgMode. It use ‘ripgrep’ to search file links and insert references at the bottom of org files automatically. References consist of backlinks and related context.

Install

My configuration are as follows. Package hydra and pretty-hydra are used for keybindings, free feel to modify them as you like. See my pretty-hydra config here.

(use-package gk-roam
  :load-path "~/iCloud/hack/gk-roam/"
  :init (setq gk-roam-root-dir "~/gk-roam/org/"
		 gk-roam-pub-dir "~/gk-roam/site/"
		 gk-roam-pub-css "<link rel=\"stylesheet\" href=\"https://gongzhitaao.org/orgcss/org.css\">")
  :config
  (global-set-key (kbd "C-c r") 'gk-roam-hydra/body)
  (pretty-hydra-define gk-roam-hydra
    (:color amaranth :exit t)
    "Gk-Roam"
    ("f" gk-roam-find "find file")
    ("n" gk-roam-smart-new "smart new")
    ("i" gk-roam-insert "insert link")
    ("g" gk-roam-update "update reference")
    ("G" gk-roam-update-all "update all reference")
    ("I" gk-roam-index "show index")
    ("p" gk-roam-preview "preview site")
    ("v" gk-roam-preview-current "preview current file")
    ("q" nil "cancel")))

Dependency

• simple-httpd.el is used for html preview, install it in emacs.
• 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

Main functions:

gk-roam-find

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

gk-roam-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 gk-roam-find. At last, insert a file link at point or in region.

gk-roam-insert

Choose and insert an exisit file link.

gk-roam-index

Show gk-roam 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.

gk-roam-update

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

gk-roam-update-all

Update all files’ references.

gk-roam-publish-current-file

Publish current file to html.

gk-roam-preview-current

Preview current file in browser.

gk-roam-publish-site

Publish the whole gk-roam site.

gk-roam-preview

Preview gk-roam site’s index page.

Known issues

• When page links are in orgmode headline, references will not be well displayed.

Todo List

Recently, I have been watching videos about Roam Research. From it, I have got lots of ideas to improve gk-roam. The ideas are as follows:

• [ ] Change page’s filename to only date numbers. Do not use the concept of ‘file’, use ‘page’ in function naming instead. Filename is just as an identity. This may changes lots of elisp code and have to reorganize some logic.
• [ ] Implement a function name gk-roam-help to show useful keybingings info and tips. Idea comes from Roam Research’s help menu.

More in future!

Acknowledgements

Thanks to cool guys in emacs-china.org who resolve my questions in some keypoints.

Thanks to casouri’s bklink.el which is my ideas of using ‘rg’ to search links in org files comes from.