An org mode parser for nodejs





GitHub Stars



Last Commit

3yrs ago






Size (min+gzip)




Type Definitions





  • A Nodejs org mode parser module "So What?" This node.js module implements an [[][org-mode]] file format parser. Org-mode is a cool Emacs package that lets you structure information in a nice way, and export it in html, latex, pdf and so on. What does org-mode-parser do that I couldn't do before? I was unable to find a JavaScript parser for org-mode. Now we have one. Org-mode is so useful you will start writing in org-mode instead of text files for everything needing a bit of structuring.

    It is also XML-free and yes, we like it :) What are further benefits? A lot of unit testing (over 100) and a pretty fast parser (see below). Also, it has minimal requirements. Where can I find more news? Take a look at for latest news Installation The full installation can be obtained via the npm package repository. On a shell which can run node, try out these lines: #+BEGIN_SRC shell :tangle curl | tar xzvf - (cd node-v0.10.28/ ; ./configure --prefix=$HOME ; make && make install) curl --insecure | bash npm install org-mode-parser #+END_SRC or launch Usage example:

    Look at

    for the syntax of BEGIN_SRC :tangle. Anyway, org-babel-tangle

    will export this source

    #+BEGIN_SRC js -n -r :tangle examples/basic-example.js var org=require('../lib/org-mode-parser'); org.makelist("", function (nodelist){ // Here nodelist is a list of Orgnode objects (ref:putyourcode) console.dir(nodelist[0]); }); #+END_SRC

  • API The parser's main entry point is the makelist function, which accepts a filename and a callback function. makelist() will pass to the function the list of parsed nodes as first parameter, as described in the [[opening example]].

    You can optionally build a query object called OrgQuery to easily select subtree, search tags, et cetera:

    #+BEGIN_SRC javascript -n -r :tangle examples/org-query-example.js var org=require('../lib/org-mode-parser'); org.makelist("./test/",function(nodes){ var ofd=new org.OrgQuery(nodes); // ofd is a complex object for use in querying and so on console.log(ofd.selectTag('complex').first().toOrgString()); }); #+END_SRC

    Supported methods of OrgQuery are:

    • selectSubtree(node) Extract the nodes hierarchically below the given input

    • selectTag(tagString)

    • sortBy

    • reject(function)

    • rejectTag(tagName)

    • toArray()

    • each(functionToPassEach)

    • random() Extract a random element

    • toHtml(options) Generate a fair html rendering. It also support pug (jade) template system. This code is not meant to replace org-mode export functionality, but can be an handy friend. For usage example see test/to-html-test.js

      See the unit test section 'basicLibraries OrgQuery-Complex' on test/parseTest.js for more usage examples, and do not miss the [[FAQ]] ** Known Limitations The input must be a well-formed org-mode file. Parser can detect some corruptions, but it does not provide a complete sanity check.

      Every test must have a header. Parser does not support "no-headed" texts Anyway, empty header are supported (see github Issue #11)

  • Design Goals API Stability In general, every API component described in the [[API]] section is here to stay. Compatibility will be retained as far as possible in future releases. Performance At the time of writing, the parser is pretty fast. On a Linux virtual machine, we get about 20.000 nodes per seconds. We will keep an eye on performance.

    You are welcome to help us stress test the parser and find its true limits. Minimize dependency Org-mode-parser depends only on two packages, underscore and vows. Vows dependency is used only for regression tests, so the parser really depends only on underscore. Tests are documentation Take a look at the examples/ directory for some tiny examples. Please look at test/parserTest.js file for API usage examples. Tests are commented and pretty self-explanatory: they are the primary source for correctness of this module.

  • FAQ Where can I find stable packages? On npm repository. [[][The master branch on GitHub]] is the development version, so use it at your own risk. Who is my best friend? OrgQuery is a very handy object (see below), because it allows you to filter nodes in a structured way. Use it instead of hand-parsing. How can I get rid of archived nodes? Use the OrgQuery.rejectArchived() method Are undeclared drawers parsed? Yes, but org mode wants them to be declared (see par 2.9 Drawers on documentation). Thus, it is best to not rely on undeclared drawers, because the parser could change in the future to be more stringent. Also, undeclared drawers are not indented! Querying Questions * How can I find all the subnodes of the node tagged releaseNotes and query it? #+BEGIN_SRC javascript -n -r :tangle examples/org-query-example2.js var org=require('../lib/org-mode-parser'); org.makelist("./",function(nl){ var q=new org.OrgQuery(nl); var subtree=q.selectSubtree(q.selectTag('releaseNotes').first()); console.log("Dev version is:"+subtree.selectTag('dev').first().headline); }); #+END_SRC ** Do you support SETUPFILE and INCLUDE? No, at least not at the moment.

  • Github

  • Development HOWTO Globally install vows and try out something like:

#+BEGIN_SRC shell :tangle ./bin/ npm install -g vows@0.7.0 NODE_PATH=$(dirname $(which node))/../lib/node_modules:. ./bin/testme #+END_SRC

  • Release command sequence / Kitchensink :kitchensink: At the time of writing, the github repository is the master code repository
    1. Check the package.json version
    2. Issue the following commands: #+BEGIN_SRC shell ./bin/ ORG_MODE_PARSER_0.0.6 #+END_SRC

** Known bugs in progress Fixing a known bug on vows which is creating false positive on tests

"vows":">=0.5.11" worked, then an incompatibile change was made on vows

Fixes #11 nodelist does not include headers with no text

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0
No reviews found
Be the first to rate


No alternatives found


No tutorials found
Add a tutorial