When the file or directory being converted has an ancestor directory with a ourbigbook.json file, then your current working directory does not have any effect on OurBigBook output. For example if we have:
then all of the following conversions produce the same output:
  • directory conversion:
    • cd /project && ourbigbook .
    • cd / && ourbigbook project
    • cd project/subdir && ourbigbook ..
  • file conversion:
    • cd /project && ourbigbook README.bigb
    • cd / && ourbigbook project/README.bigb
    • cd project/subdir && ourbigbook ../README.bigb
When there isn't a ourbigbook.json, everything happens as though there were an empty ourbigbook.json file in the current working directory. So for example:
  • outputs that would be placed relative to inputs are still placed in that place, e.g. README.bigb -> index.html always stay together
  • outputs that would be placed next to the ourbigbook.json are put in the current working directory, e.g. the out directory
Internally, the general philosophy is that the JavaScript API in index.js works exclusively with paths relative to the project toplevel directory. It is then up to callers such as ourbigbook to ensure that filesystem specifics handle the relative paths correctly.


  1. The toplevel index file
  2. Project toplevel directory
  3. Index file
  4. OurBigBook CLI
  5. OurBigBook Project