[[https://melpa.org/#/gkroam][file:https://melpa.org/packages/gkroam-badge.svg]] [[https://stable.melpa.org/#/gkroam][file:https://stable.melpa.org/packages/gkroam-badge.svg]]
** Introduction Gkroam is a lightweight [[https://roamresearch.com][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. The principle of Gkroam is "Be faithful to Roam Research".
** Demos
[[https://www.bilibili.com/video/BV1cz4y1o7BY/][Bilibili]]
More demo pictures see [[./Demos.org][here]].
** 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 :hook (after-init . gkroam-mode) :init (setq gkroam-root-dir "~/gkroam/org/") (setq gkroam-prettify-page-flag t gkroam-show-brackets-flag nil gkroam-use-default-filename t gkroam-window-margin 4) :bind (:map gkroam-mode-map (("C-c r I" . gkroam-index) ("C-c r d" . gkroam-daily) ("C-c r D" . gkroam-delete) ("C-c r f" . gkroam-find) ("C-c r i" . gkroam-insert) ("C-c r n" . gkroam-dwim) ("C-c r e" . gkroam-link-edit) ("C-c r u" . gkroam-show-unlinked) ("C-c r p" . gkroam-toggle-prettify) ("C-c r t" . gkroam-toggle-brackets) ("C-c r R" . gkroam-rebuild-caches) ("C-c r g" . gkroam-update))))
** Dependencies
** Important Tips
** Usage *** Link format
- page link: ={[<title>]}=
- page link with alias: ={[<title>][<alias>]}=
- headline link: ={[<title> » <headline>]}=
- 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-insert=\\
Insert a page bracket link at point.
=gkroam-delete=\\
Delete one or more gkroam pages.
=gkroam-daily=\\
Create or open 'daily notes' page.
=gkroam-dwim=\\
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. Index buffer includes all gkroam pages' title, word counts, mentions, updated time and created time. You can click mentions number to see all references in a side window.
=gkroam-link-edit=\\
Edit link in minibuffer. This function is very useful when brackets are hidden.
=gkroam-show-unlinked=\\
Show page' unlinked references in a side window. Click link in unlinked references to link it to reference.
=gkroam-toggle-brackets=\\
Hide and show brackets of link and hashtag.
=gkroam-toggle-prettify=\\
Whether to prettify gkroam page.
=gkroam-update=\\
Update current buffer's references. Actually, references are updated automatically.
=gkroam-rebuild-caches=\\
Rebuild all caches, including page and filename cache, headline and headline id cache, page and references cache. It may takes seconds to build all, please be patient.** 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.
=v2.3.5=: Optimize gkroam page prettification, change 'gkroam-toggle-beautify' to `gkroam-toggle-prettify'.
=v2.3.6=: Implement a perfect linked references workflow. When a link is the item of org plain list, the whole list structure will be shown. The same as any source block, verse block, etc.
=v2.3.7=: Add headline id only when you insert a gkroam link. Use `gkroam-rebuild-caches' command to rebuild headline and id caches.
=v2.4.0=
=v2.4.1=
=v2.4.2=: Implement 'unlinked references'.
=v2.4.3=: Change backlink format to org-link format and delete 'gkroam-capture'.
** TodoList
Recently, I have been watching [[https://www.youtube.com/playlist?list=PLwXSqDdn_CpE934BjXMgmzHnlwXMy41TC][videos]] about Roam Research. From these, I have gotten lots of ideas on how to improve gkroam. The ideas are as follows:
[ ] Implement 'block reference' and 'block embed'.
More in future!
** Credits The original idea of Gkroam comes from [[https://github.com/casouri][casouri]]'s [[https://github.com/casouri/lunarymacs/blob/master/site-lisp/bklink.el][bklink.el]].