A complete environment to create Markdown files with a syntax highlight that don't sucks!
- Strong support for the Markdown flavor implemented by Github: what you see in Vim is what you get on Github
- Complete syntax implementation: supports even proper nesting of all elements in list items, this is the only plugin that is able to do that (and I believe it since it took me a while to make it right)
- A simple example rendered with this plugin. Headers and the fenced code block in list items are correctly highlighted
- The same example rendered with the most popular Markdown plugins for Vim
- A simple example rendered with this plugin. Headers and the fenced code block in list items are correctly highlighted
- Code blocks and pieces of Markdown of the current file could be edited in a separate buffer and synchronized back when you finished
- Inside a ruby fenced code block with
<Leader>eopens a temporary buffer with the right file type - Then select a range in visual mode and with
<Leader>eopens a temporary buffer with file typemarkdownI call it Focus Mode because you can edit a portion of a Markdown file in isolation - At last, on an empty line, with
<Leader>easks for a file type and then opens a temporary buffer with that file type - You see that when you leave the temporary buffer the content syncs back to the main file
- Inside a ruby fenced code block with
- Folding for: headers, code blocks, html blocks and lists
- Format tables automatically (require
Tabularplugin) - Automatically detects Jekyll files and adds support for Liquid template engine
- This is a work in progress, more goodies and improvements are coming (see TODO), stay tuned
I wanted a strong support for the Markdown flavor implemented by Github, I wanted a syntax highlight that would mirror the result I would find later on Github, I wanted a syntax highlight that would not break easily, I wanted a syntax highlight that I could rely on (aka rapid feedback), I wanted something more that a mere syntax highlight. The Markdown Syntax unfortunately it's so loosely defined that there are flavors of Markdown that are subtly incompatible from each other, the Markdown supported by Github is one of them.
If you use Vundle, add the following line to your ~/.vimrc:
Bundle 'gabrielelana/vim-markdown'
And then execute the following command in your shell:
$ vim +'BundleInstall! vim-markdown' +qall
If you use Pathogen, execute the following in your shell:
$ cd ~/.vim/bundle
$ git clone https://github.com/gabrielelana/vim-markdown.git
If you are not using any package manager, download the tarball and do this:
$ cp vim-markdown-master.tar.gz ~/.vim
$ cd ~/.vim
$ tar --strip-components=1 --overwrite -zxf vim-markdown-master.tar.gz
$ rm vim-markdown-master.tar.gz
If you like this plugin, then consider to:
I would use this section until I have a proper documentation
let g:markdown_include_jekyll_support = 1to load support to Jekyll files (default: 1)let g:markdown_enable_folding = 1to use the fold expressionmarkdown#FoldLevelOfLineto fold markdown files, this is disabled by default because it's a huge performance hit even when folding is disabled withnofoldenableoption (default: 0)let g:markdown_enable_mappings = 1to load default leader mappings (default: 1)let g:markdown_enable_insert_mode_mappings = 1to load also insert mode leader mappings (default: 0)
All default mappings are local to markdown buffers
<Space>(NORMAL_MODE) switch status of things:- A list item
* itembecomes a check list item* [ ] item - A check list item
* [ ] itembecomes a checked list item* [x] item - A checked list item
* [x] itembecomes a list item* item
- A list item
<Leader>ft(NORMAL_MODE,INSERT_MODE) format the current table<Leader>e(NORMAL_MODE,VISUAL_MODE,INSERT_MODE):MarkdownEditCodeBlockedit the current code block in another buffer with a guessed file type. The guess is based on the start of the range forVISUAL_MODE. If it's not possibile to guess (you are not in a recognizable code block like a fenced code block) then the default ismarkdown. If it's not possibile to guess and the current range is a single line and the line is empty then a new code block is created. It's asked to the user the file type of the new code block. The default file type ismarkdown.
]]start of the next header[[start of the previous header
|in a table triggers the format command<Tab>/<S-Tab>on a list item it will indent/unindent the item<Tab>/<S-Tab>on a blockquote it will increase/decrease the quote level<Enter>on a list item with no text in it (freshly created) it will delete everything till the column 0
Testing syntax highlight could be tricky, here I use the golden master patter to at least avoid regressions, this is how it works: in ./rspec/features you will find a bunch of *.md files, one for each syntactic element supported, for each of those files there's an html file, this file is created with the :TOhtml command and it's the reference (aka golden master) of the syntax highlight of the original file. Running rspec you are comparing the current syntax highlight of all the feature's file with the reference syntax highlight. If looking at some of the feature's file you see something wrong you can fix it and after regenerate the golden master files with GENERATE_GOLDEN_MASTER=1 rspec
formatlistpatdoesn't work for ordered listsformatoptionsthinks that*in horizontal rules are list items