Orger converts your data into a hierarchical Org-mode representation to allow for quick access and search.

I write in detail about usecases and motivation for it here, this readme is mostly the setup manual!

Installing

• simplest: install from PyPi: pip3 install --user orger

  After that you should be able to run orger modules via python3 -m:

  python3 -m orger.modules.instapaper --help
      

• editable install

  This will allow you to quickly prototype and debug, the local changes to the code will be reflected immiedately.

  • clone: https://github.com/karlicoss/orger /path/to/orger
  • cd /path/to/orger
  • pip3 install --user .
  • after that you can use python3 -m orger.modules.modulename, same way as the previous section, or run modules/modulename.py directly
• NOTE: most Orger modules are relying on HPI module for input data

  Please refer to the HPI install guide/documentation and make sure the corresponding data providers work (e.g. via hpi doctor command).

• [optional]: install pandoc, it might give you better org-mode outputs for some modules

  If you do have pandoc installed, but don’t want the module to use it, pass --disable-pandoc flag to it.

Usage and examples

I usually run Orger modules overnight via cron.

• see modules for all available modules
• Most modules are using HPI package for accessing the data. You can learn about setting it up and using here.
• several examples here
• demonstration of Roam Research module, including a screencast
• pocket_demo: documented literate demo
• and a short short demo:

  from orger import Mirror
  from orger.inorganic import node, link
  from orger.common import dt_heading
  
  import my.coding.github as github_data
  
  class Github(Mirror):
    def get_items(self):
      for event in github_data.get_events():
        yield node(dt_heading(event.dt, event.summary))
  
  Github.main()
      

  That ten line program, when run (./modules/github.py), results in a file Github.org:

  # AUTOGENERATED BY /code/orger/github.py
  
  * [2016-10-30 Sun 10:29] opened PR Add __enter__ and __exit__ to Pool stub
  * [2016-11-10 Thu 09:29] opened PR Update gradle to 2.14.1 and gradle plugin to 2.1.1
  * [2016-11-16 Wed 20:20] commented on issue Linker error makes it impossible to use a stack-provided ghc
  * [2016-12-30 Fri 11:57] commented on issue Fix performance in the rare case of hashCode evaluating to zero
  * [2019-09-21 Sat 16:51] commented on issue Tags containing letters outside of a-zA-Z
  ....
      

types of modules

• Mirror

  Mirror (old name StaticView): mirrors all data from a source, and generated from scratch every time, hence read only.

  You can run such module with

  ./orger_module.py --to /path/to/output.org
        

• Queue

  Queue (old name InteractiveView): works as a queue, only previously unseen items from the data source are added to the output org-mode file.

  To keep track of previously seen iteems, it’s using a separate JSON state file.

  A typical usecase is a todo list, or a content processing queue. You can use such a module as you use any other org-mode file: schedule/refile/comment/set priorities, etc.

  Typically you’d want to use these as a source of tasks for your todo list. See ip2org as an example.

  You can run such a module as:

  ./orger_module.py --to /path/to/output.org
        

  This will keep the state file in your user config dir (e.g. ~/.config/orger/).

  Alternatively, you can pass the state file explicitly:

  ./orger_module.py --to /path/to/output.org --state /path/to/state.json
        

FAQ

• Why are the files output by some modules read only?

  Mirror type modules output read only files, so you don’t modify them by accident, they are overwritten every time.

  If you want to temporary lift this restriction (e.g. to experiment with the format), you can use chmod +w, or M-x toggle-read-only in Emacs.

• How is it different from Memacs?

  The main reason Orger exists is because I discovered Memacs after I wrote Orger! One day we might merge them, or at least reuse org-mode formatting routines.

  That said there are some differences at the moment:

  • Memacs is more of a lifelogging utility, generating a linear output with the intent to be used with your org agenda
  • Orger’s Mirror modules are meant to be more of a full local reflection of a data source, preserving the hierarchy as much as possible
  • Orger’s Queue module: I believe they don’t have Memacs analogue (but please correct me if I’m wrong)
  • Orger modules are slim and relying on HPI to encapsulate data access. But you can also use HPI with Memacs, please ping me if you set up such an integration!
• I want active timestamps for org-agenda integration

  Pass the --timestamp argument to the module, for example:

  modules/polar.py --timestamps active
      

Similar projects

• Memacs by novoid