Vimdown

TOC

• Install
• Overview
• Usage
  • Basic
  • Advanced
• Examples
  • Viming-With-Buttars
• Changes

---

Install

The easiest way to install is to use pip

pip install vimdown

Or you can chose an install download from GitHub

Overview

Vimdown transforms .vim files into markdown documents.
Vimdown was born out of an itch to make my .vimrc look nice as the README.mkd file for my GitHub repository that holds my .vim directory.
This README was written as a vim file and rendered to markdown with vimdown.

Vimdown is a very simple parser. All it does is seperate a Vim file into blocks of text that either contiguous comments or contiguous non-comments. Blocks of comments are stripped of their comment marks, '"', from the begining of the line and considered to be in markdown syntax. Non-comment blocks are considered code blocks and are inserted into the resulting markdown document as explicit vim codeblocks. Only lines with the comment mark, '"', as the first or second character of the line are considered comments. If the comment mark starts later in the line it will be considered code with a comment in the code block.

Usage

Vimdown has built in help output

> vimdown --help 

Basic

Simply give the vimdown command a file or files to process and it will print out the result to stdout:

> vimdown infile > outfile

You can specify an output file:

> vimdown -o outfile infile

If your using vimdown to create a GitHub README use the -g option:

> vimdown -g -o outfile infile

Using multiple input files:

> vimdown infile infile2 infile3 -o outfile

Advanced

Markdown2 code blocks

You can have markdown2 style code blocks with -c :

> vimdown -c -o outfile infile

That will create code blocks in the markdown in the style of:

    :::vim
    code is here

GitHub code fencing

You can have GitHub code fencing with -g :

> vimdown -g -o outfile infile

That will create code blocks in the style of:

```vim
code is here
another line of code is here
```

Render to HTML

If you have markdown2 installed you can ask vimdown to render the markdown to HTML for you with the -t option.

This will render a basic markdown document as HTML into the outfile

> vimdown -t -o outfile infile

This will render a markdown document with markdown2 codeblocks as HTML into the outfile

> vimdown -c -t -o outfile infile

Pygments Styles

If you have both Markdown2 and Pygments installed you can have vimdown render the output as an HTML document with the code markup styled for Pygments. Use the -p option:

> vimdown -p -o outfile infile

Examples

To see real world usage of vimdown, checkout the README for the Viming-With-Buttars project.

Everything you've seen in the document so far is an example of how vimdown renders comments in a vim file.

Comment blocks must have the '"' comment mark in the first or second character position of the line.

The comment block:

" # comment 
" _comment_ 
" comment 

will render as:

comment

comment
comment

Another comment block, the comment starts in an extra space:

 " [comment](http://google.com)
 " comment 
 " __comment__

renders as:
comment
comment
comment

This will be considered a code block:

    " [comment](http://google.com) 
    " # comment 
    " comment 

rendered as:

  " [comment](http://google.com)
  " # comment
  " comment

The following examples are how it will render code blocks.

if variable < 10
    let g:variable = 0
endif

A code block with comments

if filereadable( tstr )
    " make sure our big ass bsd tags file
    " is used in subdirs as well.
    set tags+=tstr " comment at end of line
endif

Changes

• 1.1.0 Added the -g option to enable GitHub style code fencing. This makes code render with hilighting on GitHub.
• 1.1.1 Vimdown now removes leading and trailing empty lines from code blocks.
• 1.2.0 (In progress) New lexer and parser. The new lexer is based on the lexer from http://www.evanfosmark.com/2009/02/sexy-lexing-with-python/ . Broke the lexer and parser into their own modules. Added better logging control. If vimdown is run from the source directory DEBUG logging is automatically enabled.