You can install the support with Vundle with:
set nocompatible
filetype off
set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()
Plugin 'gmarik/vundle'
let g:snipMate = {}
let g:snipMate.snippet_version = 1
Plugin 'MarcWeber/vim-addon-mw-utils'
Plugin 'tomtom/tlib_vim'
Plugin 'garbas/vim-snipmate'
Plugin 'ourbigbook/ourbigbook', {'rtp': 'vim'}
or by directly dropping the files named below under your ~/.vim/, e.g. vim/syntax/ourbigbook.vim
The following support is provided:
  • vim/syntax/ourbigbook.vim: syntax highlighting.
    As for other programming languages, this cannot be perfect without actually parsing, which would be slow for larger files.
    But even the imperfect approximation already covers a lot of the most cases.
    Notably it turns off spelling from parts of the document like URLs and code which would otherwise contain many false positive spelling errors.
  • vim/snippets/ourbigbook.snippets: snippets for github.com/honza/vim-snippets, which you also have to install first for them to work.
    For example, with those snippets installed, you can easily create links to headers. Suppose you have:
    = My long header
    To create an cross reference to it you can:
    and it will automatically expand to:
    This provides a reasonable alternative for ID calculation, until a ctags-like setup gets implemented (never/browser editor with preview-only? ;-))
    Similarly for \H parent argument you can do:
    would expand to:
    Syntax highlighting can likely never be perfect without a full parser (which is slow), but even the imperfect approximate setup (as provided for most other languages) is already a huge usability improvement.
    We will attempt to err on the side of "misses some stuff but does not destroy the entire page below" whenever possible.
  • mappings:
    • <leader>f, which usually means ,f (comma then F): start searching for a header in the current file. Does a regular / search without opening any windows, to is it very ligthweight. Mnemonic: "Find".
    • <leader>h (requires Fugitive to be installed): sets up the ObbGitGrep command, which searches for header across all git tracked files in the current Git repository. After ,g you are left in the prompt with:
      so if you complete that by:
      ObbGitGrep animal kingdom
      it will match headers that start with animal kingdoom case insentively, e.g.:
      = Animal kingdom tree
      = Animal kingdom book
      Vim regular expressions are accepted, e.g. if you don't want it to start with the search pattern:
      ObbGitGrep .*animal kingdom
      The command opens a new tab (technically a "Vim error window") containing all matches, where you can click Enter to open one of them.
      Mnemonic: "Header search".


  1. Editor support
  2. Tooling
  3. OurBigBook Project