sponsor Vim development Vim logo Vim Book Ad

VOoM : Vim two-pane outliner

 script karma  Rating 321/102, Downloaded by 16268  Comments, bugs, improvements  Vim wiki

created by
Vlad Irnov
script type
VOoM (Vim Outliner of Markups) is a plugin for Vim that emulates a two-pane text outliner.

Home page: http://www.vim.org/scripts/script.php?script_id=2657
GitHub mirror: https://github.com/vim-voom/VOoM
Screenshots and an animation: https://vim-voom.github.io/
Bug reports, questions, requests: https://github.com/vim-voom/vim-voom.github.com/issues
Supplementary Materials: https://github.com/vim-voom/VOoM_extras

VOoM was originally written to work with start fold markers with level numbers, that is {{{1, {{{2, {{{3, etc. This is the most versatile outline markup -- it is suitable for organizing all kinds of files, including the source code, and it allows features not possible with other markups. (See :help fold-marker. Markers are specified by option 'foldmarker'. End fold markers with levels, }}}3, }}}2, etc. are not supported.)

VOoM can currently handle >20 markup formats that have headlines and support an outline structure, including popular lightweight markup languages such as reST, Markdown, Pandoc, AsciiDoc, Org-mode, Wiki, LaTeX, etc. (Headlines are also called headings, headers, section headers, titles.)
The following markup modes are available:
        * fmr (Default Mode)  -- Start fold markers with levels: {{{1, {{{2, {{{3, etc. Headline text is before the marker.
        * fmr1, fmr2, fmr3  -- Start fold markers with levels. Variations of the Default Mode.
        * wiki  -- MediaWiki, headlines are surrounded by '='.
        * vimwiki  -- Vimwiki plugin, vimscript #2226.
        * viki  -- Viki/Deplate plugin, vimscript #861.
        * cwiki  -- vimscript #2176.
        * org  -- Emacs Org-mode.
        * rest  -- reStructuredText section titles.
        * markdown  -- Markdown headers, both Setext-style and Atx-style.
        * pandoc  -- Pandoc Markdown. Headlines inside fenced code blocks are ignored, which makes this mode suitable for MultiMarkdown, GitHub Markdown, R Markdown, etc.
        * hashes  -- #, ##, ###, etc. Atx-style headers, a subset of Markdown format.
        * txt2tags  -- txt2tags titles and numbered titles.
        * asciidoc  -- AsciiDoc document and section titles, both styles.
        * latex  -- LaTeX sectioning and some other commands.
        * latexDtx  -- Same as LaTeX but for .dtx files (Documented LaTeX sources).
        * dokuwiki  -- DokuWiki.
        * inverseAtx -- Inverse Atx-style headers.
        * html  -- HTML heading tags, single line only.
        * thevimoutliner  -- The Vim Outliner plugin (vimscript #517).
        * vimoutliner  -- VimOutliner plugin (vimscript #3515).
        * taskpaper  -- TaskPaper (vimscript #2027).
        * python  -- Python code browser. Blocks between "class" and "def" are also nodes.
        * paragraphBlank, paragraphIndent, paragraphNoIndent  -- For working with paragraphs. Handy for sorting blocks of lines.

An outline of the current buffer is created by the command
        :Voom [MarkupMode]
where MarkupMode is one of the listed above. There is argument completion -- type ":Voom " and press <Tab> or <C-d>.
For Markdown file:
        :Voom markdown
For Pandoc Markdown:
        :Voom pandoc
For LaTeX file:
        :Voom latex
For Orgmode file:
        :Voom org
And so on.  To delete outline, press "q" while in the outline pane (Tree buffer).
NOTE that by default the command ":Voom" is equivalent to ":Voom fmr" -- outline is created from lines with {{{1, {{{2, {{{3, etc. (the marker is specified by Vim option 'fmr'). This can be customized, see help for g:voom_ft_modes and g:voom_default_mode. The name of the current markup mode is noted on the first line of the Tree buffer. The command ":Voominfo [all]" will show more details.

        + VOoM is a full-featured outliner. It has a complete set of commands for outline structure manipulation: move nodes up/down, promote/demote, copy/cut/paste, insert new node, sort in various ways, randomize.
        + There are many one-character mappings for efficient outline navigation which can be combined into complex commands, e.g., "UVD" selects all siblings of the current node.
        + VOoM is mice-friendly: outlines can be browsed with a mouse.
        + An outline can be searched (:Voomgrep). Boolean AND/NOT searches (OR is provided by Vim's \|). Hierarchical searches (tag inheritance).
        + Outline is updated automagically on entering the corresponding Tree buffer.
        + VOoM works with Vim buffers, not with files on disk as ctags-based tools.
        + VOoM is not a 'filetype' plugin. It has almost no side effects on the buffer being outlined.
        + VOoM is not tied to a particular outline format. It works with many popular light-weight markup languages.
        + VOoM is fast and efficient enough to handle MB-sized files with >1000 headlines. (Some markup modes are slower than other.)

There are four main Ex commands: Voom, Voomhelp, Voomexec, Voomlog.

:Voom {MarkupMode}
        Create outline of the current buffer. The current buffer is scanned for headlines. Headlines are displayed in the outline pane (Tree buffer). The format of headlines is specified by {MarkupMode}. See above for available markups. There is argument completion: type ":Voom " and press <Tab> or <C-d> to see all installed markup modes.
        The outline is displayed in a special buffer in a separate window which emulates the tree pane of a two-pane outliner. Such buffers are referred to as Tree buffers. The current buffer becomes a Body buffer. Each Tree line is associated with a region (node) of the corresponding source buffer (Body). Nodes can be navigated and manipulated in the Tree: moved up/down, promoted/demoted, copied/cut/pasted, sorted, etc.

        Use the default markup mode, which by default is "fmr" mode: headlines are lines with a start fold marker (specified by Vim option 'foldmarker') followed by level number, that is {{{1, {{{2, {{{3, etc. Headline's level is the number after the marker. Headline's text is the part before the marker.

        Open help file voom.txt as an outline in a new tabpage.

:Voomexec [vim|py]
        Execute the contents of the current node or fold as a Vim script or Python script. This is useful for testing code snippets and for organizing short scripts by segregating them into nodes or folds. This command can be used independently of the outlining functionality provided by the command :Voom.

        Create scratch buffer __PyLog__ and redirect Python's sys.stdout and sys.stderr to it. This is useful when developing Python scripts and when scripting Vim with Python. This feature is completely independent from the rest of the plugin.

(Commands :Voomexec and :Voomlog attempt to emulate similar features of Leo outlining editor. A Python file with code snippets organized via fold markers, plus the command :Voomexec, plus the PyLog buffer is an alternative to Python's interactive interpreter.)

For a quick introduction to VOoM outlining, see section "Quick Start" in the help file (|voom-quickstart|).
For a concise list of all VOoM commands (cheat sheet), see section "ALL MAPPINGS & COMMANDS" in the help file (|voom-map|).
install details
VOoM uses Python and requires Python-enabled Vim, that is Vim compiled with the Python interface. Both GUI Vim and terminal Vim are supported. Vim  version should be >=7.2. Normal or bigger feature set is required. Both Python 2 and Python 3 are supported.
To check if Vim has Python 2 support:
        :py print 2**0.5
        :py import sys; print sys.version
To check if Vim has Python 3 support:
        :py3 print(2**0.5)
        :py3 import sys; print(sys.version)

By default VOoM will use the first available Python version: Python 2 is tried first, Python 3 is tried next.
To always use Python 2, add to .vimrc:
        let g:voom_python_versions = [2]
To always use Python 3, add to .vimrc:
        let g:voom_python_versions = [3]
To first try Python 3, then Python 2, add to .vimrc:
        let g:voom_python_versions = [3,2]
To first try Python 2, then Pythons 3, then Python 4, then Python 5, then Pythons 6 to 666:
        let g:voom_python_versions = range(2,666)

To see which Python version is currently used by VOoM, execute command ":Voominfo [all]".

To install the VOoM plugin manually:
1) Move the contents of folders "autoload", "doc", "plugin" into the respective folders in your local Vim directory:
        $HOME/vimfiles/       (Windows)
        $HOME/.vim/           (Unix)
This should make commands :Voom, :Voomhelp, :Voomexec, :Voomlog available in all buffers. (Do ":echo $HOME" to find out what Vim sees as $HOME.)
2) Execute the :helptags command to update help tags:
        :helptags $HOME/vimfiles/doc       (Windows)
        :helptags $HOME/.vim/doc           (Unix)

To uninstall: all VOoM file and directory names start with "voom", so search for "voom" and delete, then update help tags.

Alternatively, use Pathogen (vimscript #2332) and install VOoM as a bundle, or use a Vim plugin manager.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
VOoM-5.3.zip 5.3 2017-03-05 7.0 Vlad Irnov Minor bug fixes.
VOoM-5.2.zip 5.2 2017-01-22 7.0 Vlad Irnov * Python 3 is now supported. New option g:voom_python_versions.
* New markup modes: latexDtx, fmr3, paragraphBlank, paragraphIndent, paragraphNoIndent.
* VOoM Python modules are now in directory ../autoload/voom/voom_vimplugin2657/ and are imported as a package. Custom markup modes must be placed there. Because directory structure has changed, previous VOoM version should be removed before installing this one.
* VoomSort: Option "u" was removed. Option "bytes" was added. Headlines are now always sorted as Python Unicode strings unless option "bytes" is given.
* Other small changes.
VOoM-5.1.zip 5.1 2014-06-22 7.0 Vlad Irnov * New markup mode: dokuwiki.
* Python markup mode: better handling of decorative comment lines (separators and pretty headers).
* :Voomgrep improvements.
* Some internal improvements.
VOoM-5.0.zip 5.0 2013-11-26 7.0 Vlad Irnov * The code and directory structure have been reorganized. Please remove the previous version before installing this one. Delete folder plugin/voom. If you use VOoM functions, calls to Voom_... need to be changed to voom#...
* The command :Voomgrep can now perform hierarchical searches (tag inheritance).
* New option g:voom_always_allow_move_left.
* New option g:voom_clipboard_register. Copy/Cut/Paste now use the "o register if Vim does not have clipboard support.
* New markup modes: pandoc, inverseAtx.
* Python markup mode: better handling of decorators.
* Markdown, AsciiDoc, reST modes: small improvements and bug fixes.
VOoM-4.7.zip 4.7 2013-01-29 7.0 Vlad Irnov * New markup mode: TaskPaper.
* Fixed problems with some external autocommands such as automatic write on BufLeave.
* License changed to CC0.
VOoM-4.6.zip 4.6 2012-12-03 7.0 Vlad Irnov * Warning message is no longer displayed when a markup mode is invoked.
* New command :Voominfo [all] prints information about the current outline and VOoM internals.
VOoM-4.5.zip 4.5 2012-11-13 7.0 Vlad Irnov * New Tree mapping: "I" jumps to the last line of the current node.
* Improved txt2tags mode.
* Fixed a bug in :Voomgrep search.
* Improved display of :Voomgrep results.
VOoM-4.4.zip 4.4 2012-06-04 7.0 Vlad Irnov * Added LaTeX mode: |voom_mode_latex|.
* Better mappings for Insert New Headline: "aa", "AA". <LocalLeader>i/I were changed to <LocalLeader>a/A.
* Other small improvements.
VOoM-4.3.zip 4.3 2012-05-07 7.0 Vlad Irnov * Fixed problems with file names containing %, #, spaces, etc.
* New markup mode: hashes (atx-style headers).
VOoM-4.2.zip 4.2 2012-04-04 7.0 Vlad Irnov * New commands for quitting and toggling outline window (|voom_quit|): "q", VoomToggle, Voomtoggle, Voomquit, VoomQuitAll.
* New Tree mappings ^^ (Move Up) and __ (Move Down) for symmetry with << and >>.
* Added support for "fmr" modes (|voom_mode_fmr|). Modes fmr, fmr1, fmr2.
* New options |g:voom_ft_modes|, |g:voom_default_mode| allow automatic selection of markup mode according to filetype of the source buffer.
* Improved asciidoc mode.
* :Voomexec now executes Python scripts via "exec" instead of execfile(). Temp file plugin/voom/_voomScript_.py is no longer created and should be deleted.
* Various internal code changes.
VOoM-4.1.zip 4.1 2011-11-28 7.0 Vlad Irnov Fix for Vim 7.3 versions: Tree mappings J/K did not accept a count.
VOoM-4.0.zip 4.0 2011-11-07 7.0 Vlad Irnov New markup modes: asciidoc, org, cwiki. Viki mode now ignores special regions.
New Tree mapping: "R" selects corresponding range in the source buffer.
VOoM-4.0b5.zip 4.0b5 2011-03-24 7.0 Vlad Irnov * New markup mode: txt2tags.
* Added support for sessions (:mksession).
* Fixed some bugs.
VOoM-4.0b4.zip 4.0b4 2011-01-31 7.0 Vlad Irnov * New Tree mappings for navigating outline:
    P (go to parent node),
    c (go to parent and contract it),
    C (contract siblings or everything in Visual selection),
    o (go to first child),
    O (expand siblings or everything in Visual selection),
    K/J/U/D (go to previous/next/uppermost/downmost sibling),
    s (show headline text), S (show UNL).
* Fixed some bugs.
VOoM-4.0b3.zip 4.0b3 2011-01-05 7.0 Vlad Irnov * Added mode for Markdown markup.
* Fixed severe bug in reST mode.
* Sorting can now be done for any range of sibling nodes.
VOoM-4.0b2.zip 4.0b2 2010-10-24 7.0 Vlad Irnov * Added support for the following markups: reStructuredText, Python code, The Vim Outliner, VimOutliner.
* BUG FIX: indiscriminate use of 'noautocmd' was screwing up some autocommands.
* Option g:voom_verify_oop is now enabled by default.
* Option g:voom_rstrip_chars (dictionary) has been removed. Instead there are options g:voom_rstrip_chars_{filetype} for each filetype of interest.
* See CHANGELOG for other changes.
VOoM-4.0b1.zip 4.0b1 2010-09-21 7.0 Vlad Irnov * Added support for headline markups other than start fold markers with levels. Available markup modes: wiki, vimwiki, viki, html.

* Changed plugin directory structure. All Python files are now located in folder plugin/voom. You should delete old files in plugin folder: plugin/voom.py, plugin/voom.pyc, plugin/voomScript.py.
VOoM-3.0.zip 3.0 2010-08-01 7.0 Vlad Irnov * New command :VoomSort [options] for sorting outline.

* Outline buffer (Tree) is no longer automatically wiped out when the source buffer (Body) is unloaded, deleted, or wiped out. Instead, outline is locked until the source buffer is loaded again. This change was necessary to eliminate crashes after :q, :q! and similar problems. This can also make working with outlines easier when buffers routinely get unloaded, as when 'hidden' or 'bufhidden' are not set.

* Option 'bufhidden' for Tree and PyLog buffers is set to "wipe" instead of "hide".

* Various glitches fixed. Memory usage reduced, especially when outlining large buffers.
VOoM-2.1.zip 2.1 2010-06-01 7.0 Vlad Irnov * It's now possible to customize how Tree headline text is constructed for individual filetypes:
- 'commentstring' and new user option g:voom_rstrip_chars control which characters are stripped from the right side of headlines when default procedure is used.
- The default procedure for Tree headline text construction can be replaced with user-defined functions via an add-on. Sample add-on is included.

* Fixed bug in PyLog buffer: original sys.stdout and sys.stderr could be lost after some actions.
VOoM-2.0.zip 2.0 2010-04-01 7.0 Vlad Irnov - This plugin was renamed from VOOF to VOoM. All commands start with "Voom" instead of "Voof", files were renamed, and so on. Please see Install section for instructions on how to upgrade from previous versions.
- Added rudimentary support for add-ons, a sample add-on. Fixed probable bug in mouse click mapping.
VOOF-1.92.zip 1.92 2010-03-03 7.0 Vlad Irnov Improved performance of several outline operations when working with very large outlines. Optimized some code.
VOOF-1.91.zip 1.91 2010-02-07 7.0 Vlad Irnov Voofgrep can perform boolean AND and NOT searches.
VOOF-1.9.zip 1.9 2009-12-19 7.0 Vlad Irnov It's now possible to save and restore Tree buffer folding.
Command "Voofrun" was renamed "Voofexec".
Several other small changes.
VOOF-1.8.zip 1.8 2009-09-18 7.0 Vlad Irnov Fixed bug in mappings.
Added highlighting for warnings and other messages.
Distribution now follows Vim directory structure: there are plugin and doc folders.
Changed license to WTFPL, version 2.
VOOF-1.7.zip 1.7 2009-08-31 7.0 Vlad Irnov more foolproofing
VOOF-1.6.zip 1.6 2009-08-23 7.0 Vlad Irnov Added defensive measures that prevent data corruption when outline update fails for any reason.
Fixed some bugs.
VOOF-1.5.zip 1.5 2009-08-15 7.0 Vlad Irnov New commands: Voofgrep, Voofunl.
Fixed bug in "Move Down" outline operation.
Various improvements.
VOOF_14.zip 1.4 2009-07-13 7.0 Vlad Irnov New Tree navigation commands: go to next/previous marked node. Various small changes and fixes.
VOOF_13.zip 1.3 2009-06-06 7.0 Vlad Irnov Added support for non-default start fold markers specified by 'foldmarker' option. Various other small improvements and fixes.
VOOF_12.zip 1.2 2009-05-30 7.0 Vlad Irnov Minor bug fixes and edits. See CHANGELOG node in voof.txt.
VOOF_11.zip 1.1 2009-05-27 7.0 Vlad Irnov Bug fix involving nomodifiable and readonly buffers.
VOOF.zip 1.0 2009-05-26 7.0 Vlad Irnov Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.