Readme
org-roam-server-light
Org-roam v2
For the org-roam v2 use org-roam-ui instead.
org-roam-server-light only works with org-roam v1 and will not be actively maintained.
This project is NOT part of official Org-roam project. This project started as personal experiment, proof-of-concept and doesn’t aspire to become something more then that. It however uses “org-roam(-server)” name but does it out of good intentions:
- to make this little experiment easier to find
- to make the purpose of this project clear
org-roam-server-light attempts to move org-roam-server functionality from emacs into external python server process due to subjective poor elisp / emacs performance when computing graph data for larger amount of org-roam files and serving them to web browser.
Credits
Client side code, assets and some elisp copied as they are from org-roam-server, python code copied and expanded from aklatzke/python-webserver-part-2
Prerequisites
File-preview functionality requires pandoc being available in your PATH
Installation
git clone https://github.com/AloisJanicek/org-roam-server-light.git
Depending on your emacs use one of the following snippets to install and configure org-roam-server-light.
Elisp code
if you are using doom emacs
;; .doom.d/packages.el
(package! org-roam-server-light
:recipe (:host github :repo "AloisJanicek/org-roam-server-light"
:files ("*")));; .doom.d/config.el
(use-package! org-roam-server-light
:after org-roam
:commands org-roam-server-light-mode
:config
;; OPTIONAL example settings, `org-roam-server-light' will work without them
(setq
;; enable arrows
org-roam-server-light-network-vis-options "{ \"edges\": { \"arrows\": { \"to\": { \"enabled\": true,\"scaleFactor\": 1.15 } } } }"
;; change background color of web application
org-roam-server-light-style "body.darkmode { background-color: #121212!important; }"
;; set default set of excluded or included tags
;; customize only the value of id, in this case "test" and "journal"
org-roam-server-light-default-include-filters "[{ \"id\": \"test\", \"parent\" : \"tags\" }]"
org-roam-server-light-default-exclude-filters "[{ \"id\": \"journal\", \"parent\" : \"tags\" }]"
)
)if you are using other emacs with use-package
;; .emacs.d/init.el
(use-package org-roam-server-light
;; MANDATORY: path to your local copy of this repository
:load-path "/home/john/where-i-cloned-this"
:after org-roam
:commands org-roam-server-light-mode
:config
;; OPTIONAL example settings, `org-roam-server-light' will work without them
(setq
;; enable arrows
org-roam-server-light-network-vis-options "{ \"edges\": { \"arrows\": { \"to\": { \"enabled\": true,\"scaleFactor\": 1.15 } } } }"
;; change background color of web application
org-roam-server-light-style "body.darkmode { background-color: #121212!important; }"
;; set default set of excluded or included tags
;; customize only the value of id, in this case "test" and "journal"
org-roam-server-light-default-include-filters "[{ \"id\": \"test\", \"parent\" : \"tags\" }]"
org-roam-server-light-default-exclude-filters "[{ \"id\": \"journal\", \"parent\" : \"tags\" }]"
)
)or in other emacs
;; .emacs.d/init.el
(eval-after-load 'org-roam
;; OPTIONAL: customize some settings or leave them to their defaults
;; enable arrows
(setq org-roam-server-light-network-vis-options "{ \"edges\": { \"arrows\": { \"to\": { \"enabled\": true,\"scaleFactor\": 1.5 } } } }"
;; OPTIONAL example: change background color of web application
org-roam-server-light-style "body.darkmode { background-color: #121212!important; }"
;; OPTIONAL example: set default set of excluded or included tags
;; customize only the value of id, in this case "test" and "journal"
org-roam-server-light-default-include-filters "[{ \"id\": \"test\", \"parent\" : \"tags\" }]"
org-roam-server-light-default-exclude-filters "[{ \"id\": \"journal\", \"parent\" : \"tags\" }]"
)
;; finally load the main `org-roam-server-light' elisp file
(load (expand-file-name "org-roam-server-light.el" "/home/john/where-i-cloned-this"))
)Usage
Running org-roam-server-light-mode will start org-roam-server-light server on http://localhost:8080
Roadmap and functionality overview [8/19]
- [X] start/stop python web-server when enable/disable major mode in emacs
- [X] build and serve JSON data based on
org-roam.dbfor vis.Network - [X] org-roam-buffer sidepane (basic)
- [ ] improve org-roam-buffer sidepane
- add total count of backlinks
- [X] keep track of current buffer
- [X] file previews (basic)
- [ ] improve file previews
- add CREATED timestamp (?)
- [ ] serve (certain) files linked from exported files
- [ ] serve inline images
- [ ] mark last captured file as current buffer
- [ ] handle citation backlinks in org-roam-buffer sidepane
- [X] serve custom JSON config for vis.Network
org-roam-server-light-network-vis-options - [ ] ability to customize server url/port via elisp variable
- [X] ability to customize CSS for web app via elisp variable
- [ ] ability to customize CSS for exported files via elisp-variable
- [X] filter items by org-roam tag in web app and ability to set default whitelist/blacklist
org-roam-server-light-default-include-filtersorg-roam-server-light-default-exclude-filters - [ ] review path handling in python code
- [ ] review exported files encoding issues on Windows (cp-1252 vs utf-8 weirdness)
- [ ] review mechanism of sharing data between emacs and python web-server currently emacs writes data as text to plain-text files for python web-server to read it
Licence
org-roam-server-light is licensed under the MIT License.
Licence of python part of the code is unclear because there is no licence specified in aklatzke/python-webserver-part-2, which is where the python code originates.
For Javascript and CSS libraries please refer to;