Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/AloisJanicek/org-roam-server-light

compatible org-roam-server written in python for better performance with large network graphs
https://github.com/AloisJanicek/org-roam-server-light

elisp emacs mind-mapping note-taking org-mode org-roam second-brain visualization

Last synced: 2 months ago
JSON representation

compatible org-roam-server written in python for better performance with large network graphs

Awesome Lists containing this project

README 

        
#+TITLE: Readme



* org-roam-server-light

** Org-roam v2

For the =org-roam v2= use [[https://github.com/org-roam/org-roam-ui][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 [[https://www.orgroam.com/][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:

1. to make this little experiment easier to find

2. to make the purpose of this project clear



=org-roam-server-light= attempts to move [[https://github.com/org-roam/org-roam-server][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 [[https://github.com/org-roam/org-roam-server][org-roam-server]],

python code copied and expanded from [[https://github.com/aklatzke/python-webserver-part-2][aklatzke/python-webserver-part-2]]



** Prerequisites

File-preview functionality requires [[https://pandoc.org/][pandoc]] being available in your PATH



** Installation

#+BEGIN_EXAMPLE

git clone https://github.com/AloisJanicek/org-roam-server-light.git

#+END_EXAMPLE



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



#+BEGIN_SRC emacs-lisp

;; .doom.d/packages.el



(package! org-roam-server-light

  :recipe (:host github :repo "AloisJanicek/org-roam-server-light"

           :files ("*")))

#+END_SRC



#+BEGIN_SRC emacs-lisp

;; .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\"  }]"

   )

  )

#+END_SRC



if you are using other emacs with use-package



#+BEGIN_SRC emacs-lisp

;; .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\"  }]"

   )

  )

#+END_SRC



or in other emacs



#+BEGIN_SRC emacs-lisp

;; .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"))

  )

#+END_SRC



** Usage

Running =org-roam-server-light-mode= will start org-roam-server-light server on http://localhost:8080



** TODO 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 [[https://github.com/aklatzke/python-webserver-part-2][aklatzke/python-webserver-part-2]], which is where the python code originates.



For Javascript and CSS libraries please refer to;



- https://github.com/jquery/jquery/blob/master/LICENSE.txt

- https://github.com/visjs/vis-network

- https://github.com/twbs/bootstrap/blob/master/LICENSE

- https://github.com/gongzhitaao/orgcss

- https://github.com/select2/select2

- https://github.com/minhur/bootstrap-toggle/blob/master/LICENSE