This is my first Vim plugin and is intended to assist with adding, and editing, MarkDown headings. Features include changing the heading depth, auto-update heading reference links, and adding link title (on hover) text. Currently everything seems to function as designed, however, as this the first Vim script project that I've published, I'm certain that there is room for improvement.
Questions
- Are there any features for modification/customization that need to be added?
Or in other-words, should I offer leader/command key customization, and if so what are the best practices for achieving that?
- Is there a way to throw error codes, and if so what are the correct error codes to throw within this plugin?
Examples would be super helpful for both myself and future readers.
- Have I made any mistakes?
Requirements
This plugin is tested on Linux based operating systems, but suggestions on how to make it OS agnostic are certainly welcomed; regardless Vim should be installed prior to using this plugin, eg...
sudo apt-get install vim Setup
Source code is maintained on GitHub, as are the documentation files and README.md. Included within this question are the TLDR and source .vim script code files.
mkdir -vp ~/git/hub/vim-utilities cd ~/git/hub/vim-utilities git clone [email protected]:vim-utilities/markdown-headings.git If not utilizing some form of Vim plugin manager, then the linked-install.sh script may be run on most 'nix devices...
./linked-install.sh ... which will symbolically link plugin scripts and documentation, and update Vim doc. tags.
Usage
Features of this plugin automatically activate if detected filetype is markdown
Example Usage
- Write a line of text...
Heading line to be - Use Vim leader sequence to convert line into level
2MarkDown heading...
<Leader>h2 - Example results...
## Heading line to be - Use Vim command to build Heading Link with title text...
:Hl Text about heading - Example results...
## Heading line to be [heading__heading_line_to_be]: #heading-line-to-be "Text about heading" - Edit text of heading...
## Edited heading line [heading__heading_line_to_be]: #heading-line-to-be "Text about heading" - Use Vim leader sequence to update Heading Link...
<Leader>hl - Example results...
## Edited heading line [heading__edited_heading_line]: #edited-heading-line "Text about heading" ... Note, either :Hl or <Leader>hl will update any references to the heading within the document too!
For example for a table of contents similar to...
- [Link to Some Heading][heading__heading_line_to_be] ... would be updated to...
- [Link to Some Heading][heading__edited_heading_line] - Convert the level two heading to a level three heading...
<Leader>h3 ... example results...
### Edited heading line Source Code
plugin/markdown-heading-link.vim
#!/usr/bin/env vim autocmd FileType markdown call s:Register_Leader() autocmd FileType markdown call s:Register_Commands() "" " Registers Normal mode leader sequences function! s:Register_Leader() nnoremap <Leader>hl :call MarkDown_Headings_Make_Link()<cr> endfunction "" " Registers Ex mode commands function! s:Register_Commands() command! -nargs=* Hl call MarkDown_Headings_Make_Link(<f-args>) endfunction "" " Returns lower-cased string, replacing spaces with dashes and striping non-alpha/numeric characters " @param {string} heading_text - Word to sluggify " @return {string} " @author S0AndS0 " @license AGPL-3.0 " @example " echo s:Sluggify('## Spam Flavored Ham') " #> spam-flavored-ham function! s:Sluggify(heading_text) let l:trimmed_line = substitute(a:heading_text, '^#* ', '', '') let l:lowered_line = tolower(l:trimmed_line) let l:sanitized_line = substitute(l:lowered_line, '[^a-z0-9 ]', '', 'g') let l:dashed_line = substitute(l:sanitized_line, ' ', '-', 'g') let l:slugged_line = substitute(l:dashed_line, '--*', '-', 'g') return l:slugged_line endfunction "" " Returns heading ref/tag for linking within document " @param {string} slugged_line - Slugged string to transmute into heading tag " @return {string} " @author S0AndS0 " @license AGPL-3.0 " @example " echo s:Taggify_Slug('spam-flavored-ham') " #> heading__spam_flavored_ham function! s:Taggify_Slug(slugged_line) return 'heading__' . substitute(a:slugged_line, '-', '_', 'g') endfunction "" " Updates heading link references for entire document " @param {string} old_reference - Heading reference to search document for " @param {string} new_reference - Replacement heading reference " @author S0AndS0 " @license AGPL-3.0 " @throws Error codes that are **not** E486 " @example " s:Update_Refs('heading__spam_flavored_ham]', 'heading__raspberry_jam]') function! s:Update_Refs(old_reference, new_reference) try execute ':%s/\[' . a:old_reference . '/\[' . a:new_reference . '/g' catch if v:exception !~ '^Vim\%((\a\+)\)\=:E486' throw v:exception endif endtry endfunction "" " Adds or updates reference link for heading under cursor postilion " @param {string[]|number[]} ... - List of words and/or numbers " @author S0AndS0 " @license AGPL-3.0 " @throws {string} 'Did not detect MarkDown heading!' function! MarkDown_Headings_Make_Link(...) let l:current_line = getline('.') if match(l:current_line, '#') < 0 throw 'Did not detect MarkDown heading!' endif let l:cursor_position = getpos('.') let l:slugged_line = s:Sluggify(l:current_line) let l:tag_line = s:Taggify_Slug(slugged_line) let l:next_line = getline(l:cursor_position[1] + 1) let l:regex_link_without_title = "\[[a-z0-9_]*\]: #[a-z0-9\-]*" let l:regex_link_with_title = l:regex_link_without_title . " \"[[:print:]]*\"" let l:heading_tag = '[' . l:tag_line . ']' let l:heading_title = join(a:000) let l:heading_link_text = l:heading_tag . ': #' . l:slugged_line if len(l:heading_title) > 0 let l:heading_link_text .= ' "' . l:heading_title . '"' elseif match(l:next_line, l:regex_link_with_title) >= 0 let l:heading_title = split(l:next_line, '"')[-1] if len(l:heading_title) > 0 let l:heading_link_text .= ' "' . l:heading_title . '"' endif endif if match(l:next_line, l:regex_link_without_title) < 0 execute "normal! A\n" . l:heading_link_text else let l:old_heading_tag = l:next_line[0:match(l:next_line, ']')] execute "normal! j0c$" . l:heading_link_text let l:tag_find = l:old_heading_tag[1:len(l:old_heading_tag)] let l:tag_replace = l:heading_tag[1:len(l:heading_tag)] call s:Update_Refs(l:tag_find, l:tag_replace) endif call setpos('.', cursor_position) if len(l:heading_title) == 0 execute "normal! jA" . ' ""' :startinsert endif endfunction plugin/markdown-heading-transform.vim
#!/usr/bin/env vim autocmd FileType markdown call s:Register_Leader() autocmd FileType markdown call s:Register_Commands() "" " Registers Normal mode leader sequences function! s:Register_Leader() nnoremap <Leader>h0 :call MarkDown_Heading_Transform(0)<cr> nnoremap <Leader>h1 :call MarkDown_Heading_Transform(1)<cr> nnoremap <Leader>h2 :call MarkDown_Heading_Transform(2)<cr> nnoremap <Leader>h3 :call MarkDown_Heading_Transform(3)<cr> nnoremap <Leader>h4 :call MarkDown_Heading_Transform(4)<cr> endfunction "" " Registers Ex mode commands function! s:Register_Commands() command! -nargs=1 H call MarkDown_Heading_Transform(<f-args>) endfunction "" " Transforms current line to MarkDown heading of defined depth " @param {number} depth - Heading depth, eg. `0`, or `1`, or `-1`, etc " @author S0AndS0 " @license AGPL-3.0 " @example text " foo bar " @example input " \h3 " @example output " ### foo bar function! MarkDown_Heading_Transform(depth) let l:cursor_position = getpos('.') let l:current_line = getline('.') let l:trimmed_line = substitute(l:current_line, '^#* ', '', '') let l:current_depth = len(substitute(l:current_line, '[^#*].*', '', '')) if a:depth == l:current_depth return elseif a:depth > l:current_depth && l:current_depth == 0 let l:cursor_x_offset = a:depth + 1 - l:current_depth elseif a:depth < l:current_depth && a:depth == 0 let l:cursor_x_offset = a:depth - 1 - l:current_depth else let l:cursor_x_offset = a:depth - l:current_depth endif if a:depth > 0 let l:headings = repeat('#', a:depth) let l:heading_line = join([l:headings, ' ', l:trimmed_line], '') let l:cursor_position[2] += l:cursor_x_offset elseif a:depth == 0 let l:heading_line = l:trimmed_line if l:cursor_position[2] > 0 let l:cursor_position[2] += l:cursor_x_offset else let l:cursor_position[2] = 0 endif else let l:new_depth = len(repeat('#', l:current_depth + a:depth)) if l:new_depth > 0 call MarkDown_Heading_Transform(l:new_depth) else call MarkDown_Heading_Transform(0) endif return endif execute 'normal! 0d$0i' . l:heading_line call setpos('.', l:cursor_position) endfunction Side note, I'm not sure what's going on with syntax highlighting here, but as of latest revisions these scripts seem to function without error.
