A complete environment to create Markdown files with a syntax highlight that doesn't suck!
- Strong support for the Markdown flavor implemented by Github: what you see in Vim is what you get on Github
- Complete syntax implementation: supports 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)
- 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>e
opens a temporary buffer with the right file type - Then select a range in visual mode and with
<Leader>e
opens a temporary buffer with file typemarkdown
I call it Focus Mode because you can edit a portion of a Markdown file in isolation - At last, on an empty line, with
<Leader>e
asks 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
Tabular
plugin) - 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 +'PluginInstall! vim-markdown' +qall
You can update to the latest version with the following command in your shell:
$ vim +PluginUpdate
If you use NeoBundle, add the following line to your ~/.vimrc
:
NeoBundle 'gabrielelana/vim-markdown'
And then execute the following command in your shell:
$ vim +NeoBundleInstall +qall
You can update to the latest version with the following command in your shell:
$ vim +NeoBundleInstall! +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 = 0
to disable support for Jekyll files (enabled by default with:1
)let g:markdown_enable_folding = 1
to enable the fold expressionmarkdown#FoldLevelOfLine
to fold markdown files, this is disabled by default because it's a huge performance hit even when folding is disabled withnofoldenable
option (disabled by default with:0
)let g:markdown_enable_mappings = 0
to disable default mappings (enabled by default with:1
)let g:markdown_enable_insert_mode_mappings = 0
to disable insert mode mappings (enabled by default with:1
)let g:markdown_enable_insert_mode_leader_mappings = 1
to enable insert mode leader mappings (disabled by default with:0
)
let g:markdown_enable_spell_checking = 0
to disable spell checking (enabled by default with:1
)let g:markdown_enable_input_abbreviations = 0
to disable abbreviations for punctuations and emoticons (enabled by default with:1
)
mappings are local to markdown buffers
<Space>
(NORMAL_MODE
) switch status of things:- Cases
- A list item
* item
becomes a check list item* [ ] item
- A check list item
* [ ] item
becomes a checked list item* [x] item
- A checked list item
* [x] item
becomes a list item* item
- A list item
- Can be changed with
g:markdown_mapping_switch_status = '<Leader>s
- Cases
<Leader>ft
(NORMAL_MODE
) format the current table<Leader>e
(NORMAL_MODE
,VISUAL_MODE
):MarkdownEditCodeBlock
edit 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 possible to guess (you are not in a recognizable code block like a fenced code block) then the default ismarkdown
. If it's not possible 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
.
mappings are local to markdown buffers
<Leader>ft
(INSERT_MODE
) same asNORMAL_MODE
<Leader>ft
with an additional mapping forINSERT_MODE
<Leader>e
(INSERT_MODE
) same asNORMAL_MODE
andVISUAL_MODE
<leader>e
with an additional mapping forINSERT_MODE
]]
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
formatlistpat
doesn't work for ordered listsformatoptions
thinks that*
in horizontal rules are list items