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.db for 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-filters org-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;