├── .gitignore ├── bin ├── help.txt └── vim-helpfile ├── doc └── markdown-helpfile.txt ├── lib ├── main.js └── tmpl.mustache ├── package.json ├── plugin └── markdown-helpfile.vim └── readme.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .netrwhist 3 | doc/tags 4 | -------------------------------------------------------------------------------- /bin/help.txt: -------------------------------------------------------------------------------- 1 | Usage: 2 | 3 | vim-helpfile [options] [file] 4 | 5 | If no [file] is provided, data is collected from stdin 6 | 7 | cat readme | vim-helpfile [options] 8 | 9 | Options: 10 | 11 | -n, --name Plugin name, if not set read from first very 12 | first heading 13 | -d, --description Plugin description, if not set read from very 14 | first text token (paragraph most likely) 15 | -v, --version Display package version 16 | -h, --help Show this help text 17 | 18 | -------------------------------------------------------------------------------- /bin/vim-helpfile: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | var fs = require('fs'), 4 | join = require('path').join, 5 | HelpFile = require('../'); 6 | 7 | var opts = require('nopt')({ 8 | help: Boolean, version: Boolean 9 | }); 10 | 11 | if(opts.help) return fs.createReadStream(join(__dirname, 'help.txt')).pipe(process.stdout); 12 | 13 | if(opts.version) return console.log(require('../package.json').version); 14 | 15 | var file = opts.argv.remain[0]; 16 | 17 | // if file is not provided, assume input stream and open stdin. 18 | var input = file ? fs.createReadStream(file) : process.openStdin(); 19 | 20 | input 21 | .pipe(new HelpFile(opts)) 22 | .pipe(process.stdout); 23 | 24 | -------------------------------------------------------------------------------- /doc/markdown-helpfile.txt: -------------------------------------------------------------------------------- 1 | *markdown-helpfile.txt* Generate vim helpfiles from markdown 2 | 3 | |markdown-helpfile-intro| markdown-helpfile 4 | |markdown-helpfile-Synopsis| Synopsis 5 | |markdown-helpfile-vim-plugin| vim plugin 6 | 7 | markdown-helpfile *markdown-helpfile-intro* 8 | 9 | Generate vim helpfiles from markdown 10 | 11 | `:h help-writing` -> http://vimdoc.sourceforge.net/htmldoc/helphelp.html#help-writing 12 | 13 | 14 | Synopsis *markdown-helpfile-Synopsis* 15 | 16 | The `bin/vim-helpfile` script is a simple script parsing streaming 17 | markdown to output the according vim helpfile. 18 | 19 | You may `npm link` repo or install the tarball with `-g` option. 20 | 21 | > 22 | $ cat readme.md | markdown-helpfile 23 | < 24 | 25 | Or maybe 26 | 27 | > 28 | $ cat readme.md | markdown-helpfile > doc/myplugin.txt 29 | $ vim doc/myplugin.txt 30 | < 31 | 32 | 33 | vim plugin *markdown-helpfile-vim-plugin* 34 | 35 | This tool can also be used as a vim plugin. The plugin itself is a basic 36 | wrapper to the node script previously described. 37 | 38 | **Using pathogen** 39 | 40 | > 41 | $ cd ~/.vim/bundle 42 | $ git clone git://github.com/mklabs/vim-markdown-helpfile.git 43 | $ cd vim-markdown-helpfile && npm install 44 | < 45 | 46 | It provides a single command `:MarkdownToHelpfile`, only on `markdown` buffer type. 47 | 48 | What it does: 49 | 50 | convert the whole markdown document as vim helpfile 51 | 52 | change filetype from markdown to `help` (`set ft=help`) 53 | 54 | The command also accepts a range, so you may convert only a small part of your 55 | markdown file. To see how it goes. Should it be useful. 56 | 57 | That's pretty much all it does.. 58 | 59 | 60 | 61 | vim:tw=78:ts=8:ft=help:norl: 62 | -------------------------------------------------------------------------------- /lib/main.js: -------------------------------------------------------------------------------- 1 | 2 | // Module dependencies 3 | 4 | var fs = require('fs'), 5 | path = require('path'), 6 | util = require('util'), 7 | hogan = require('hogan.js'), 8 | stream = require('stream'), 9 | marked = require('marked'); 10 | 11 | marked.setOptions({ 12 | gfm: true 13 | }); 14 | 15 | module.exports = HelpFile; 16 | HelpFile.template = hogan.compile(fs.readFileSync(path.join(__dirname, 'tmpl.mustache'), 'utf8')); 17 | 18 | // 19 | // Basic markdown to vim helpfile generator. 20 | // 21 | 22 | function HelpFile(opts) { 23 | this.readable = true; 24 | this.writable = true; 25 | this.chunks = []; 26 | this.opts = opts || {}; 27 | stream.Stream.call(this); 28 | } 29 | 30 | util.inherits(HelpFile, stream.Stream); 31 | 32 | HelpFile.prototype.write = function(chunk) { 33 | this.chunks = this.chunks.concat(chunk); 34 | }; 35 | 36 | HelpFile.prototype.end = function() { 37 | // parse streaming markdown 38 | var data = this.parse(this.chunks.join('')); 39 | 40 | // render template 41 | var content = HelpFile.template.render(data); 42 | 43 | this.emit('data', content); 44 | this.emit('end'); 45 | }; 46 | 47 | HelpFile.prototype.parse = function(body) { 48 | var tokens = marked.lexer(body); 49 | 50 | // name is the first heading element found 51 | // description is the first non heading element found (say a

) 52 | // sections are divided each time a

element is found. 53 | return new Tokens(tokens, this.opts).data; 54 | }; 55 | 56 | function Tokens(tokens, opts) { 57 | this.tokens = tokens; 58 | this.data = { 59 | name: opts.name || '', 60 | desc: opts.desc || '', 61 | sections: [] 62 | }; 63 | 64 | this.init(); 65 | } 66 | 67 | // parse tokens, build data 68 | Tokens.prototype.init = function() { 69 | var data = this.data, 70 | self = this; 71 | 72 | this.tokens.forEach(function(t) { 73 | // p node handled by text handler 74 | var type = t.type === 'paragraph' ? 'text' : t.type; 75 | if(!self[type]) return; 76 | self[type](t); 77 | }); 78 | }; 79 | 80 | Tokens.prototype.heading = function(t) { 81 | t.text = t.text.trim(); 82 | 83 | // set name if not def 84 | var name = this.data.name = this.data.name || t.text; 85 | 86 | var id = name === t.text ? '-intro' : '-' + t.text.trim(); 87 | id = this.data.name.replace(/vim-?|the\s*/i, '') + id; 88 | 89 | // hmmm, a bit hacky all of this, will probably generate crap on some files 90 | id = id.replace(/[^\w]+/g, '-'); 91 | // clean trailing - 92 | id = id.replace(/-$/, ''); 93 | 94 | // build a new section 95 | var s = this.data.sections; 96 | this.last = s[s.length] = { 97 | title: t.text, 98 | section: t.text.toUpperCase(), 99 | id: id, 100 | parts: [] 101 | }; 102 | }; 103 | 104 | Tokens.prototype.text = function(t) { 105 | this.data.desc = this.data.desc || t.text.trim(); 106 | this.last && this.last.parts.push({ body: t.text.trim() }); 107 | }; 108 | 109 | Tokens.prototype.code = function(t) { 110 | var code = t.text.trim().split('\n').map(function(l) { 111 | if(!l) return l; 112 | return ' ' + l; 113 | }); 114 | 115 | t.text = ['>'].concat(code).concat('<').join('\n'); 116 | this.last.parts.push({ body: t.text }); 117 | }; 118 | 119 | -------------------------------------------------------------------------------- /lib/tmpl.mustache: -------------------------------------------------------------------------------- 1 | *{{name}}.txt* {{ desc }} 2 | 3 | {{#sections}} 4 | |{{ id }}| {{ title }} 5 | {{/sections}} 6 | 7 | {{#sections}} 8 | {{{ section }}} *{{ id }}* 9 | 10 | {{#parts}} 11 | {{{ body }}} 12 | 13 | {{/parts}} 14 | 15 | {{/sections}} 16 | 17 | vim:tw=78:ts=8:ft=help:norl: 18 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "author": "mklabs", 3 | "name": "markdown-helpfile", 4 | "description": "Simple script to generate vim helpfile from markdown", 5 | "version": "0.1.0", 6 | "repository": { 7 | "url": "git://github.com/mklabs/vim-markdown-helpfile" 8 | }, 9 | "engines": { 10 | "node": "~0.6.x" 11 | }, 12 | "dependencies": { 13 | "marked": "~0.2.4-1", 14 | "hogan.js": "~1.0.5-dev", 15 | "nopt": "~1.0.10" 16 | }, 17 | "devDependencies": {}, 18 | "main": "lib/main.js", 19 | "bin": { 20 | "vim-helpfile": "bin/vim-helpfile" 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /plugin/markdown-helpfile.vim: -------------------------------------------------------------------------------- 1 | " markdown-helpfile - Generate vim helpfile from markdown 2 | " Maintainer: mklabs 3 | 4 | if exists("g:loaded_markdown_helpfile") || v:version < 700 || &cp 5 | finish 6 | endif 7 | let g:loaded_markdown_helpfile = 1 8 | 9 | let s:dirname = expand(':p:h:h') 10 | let s:nodescr = join([s:dirname, 'bin', 'vim-helpfile'], '/') 11 | 12 | " main command handler 13 | function! s:MarkdownToHelp(first,last) 14 | let lines = s:HelpFile(a:first, a:last) 15 | call setline(a:first, lines) 16 | set ft=help 17 | endfunction 18 | 19 | function! s:HelpFile(first, last) 20 | " Detect range 21 | if a:first == a:last 22 | " Skip a possible shebang line, e.g. for node.js script. 23 | if getline(1)[0:1] == "#!" 24 | let b:firstline = 2 25 | else 26 | let b:firstline = 1 27 | endif 28 | let b:lastline = '$' 29 | else 30 | let b:firstline = a:first 31 | let b:lastline = a:last 32 | endif 33 | 34 | let lines = join(getline(b:firstline, b:lastline), "\n") 35 | 36 | let output = system('node ' . s:nodescr, lines) 37 | return split(output, '\n', 0) 38 | endfunction 39 | 40 | " wrapper function to define command only on md buffer 41 | function! s:LoadMarkdownHelp() 42 | command! -buffer -range=% -nargs=? MarkdownToHelp call s:MarkdownToHelp(,) 43 | endfunction 44 | 45 | 46 | autocmd! BufRead,BufNewFile *.{md,markdown,mdown,mkd,mkdn} call s:LoadMarkdownHelp() 47 | 48 | 49 | " vim:set sw=2 sts=2: 50 | 51 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | 2 | # markdown-helpfile 3 | 4 | Generate vim helpfiles from markdown 5 | 6 | `:h help-writing` -> http://vimdoc.sourceforge.net/htmldoc/helphelp.html#help-writing 7 | 8 | ## Synopsis 9 | 10 | The `bin/vim-helpfile` script is a simple script parsing streaming 11 | markdown to output the according vim helpfile. 12 | 13 | You may `npm link` repo or install the tarball with `-g` option. 14 | 15 | ```sh 16 | $ cat readme.md | markdown-helpfile 17 | 18 | *markdown-helpfile.txt* Generate vim helpfiles from markdown 19 | 20 | |markdown-helpfile| markdown-helpfile 21 | |markdown-helpfile-Synopsis| Synopsis 22 | 23 | markdown-helpfile *markdown-helpfile* 24 | 25 | Generate vim helpfiles from markdown 26 | 27 | 28 | Synopsis *markdown-helpfile-Synopsis* 29 | 30 | The `bin/vim-helpfile` script is a simple script parsing streaming 31 | markdown to output the according vim helpfile. 32 | 33 | > 34 | $ cat readme.md | markdown-helpfile 35 | < 36 | 37 | 38 | vim:tw=78:ts=8:ft=help:norl: 39 | ``` 40 | 41 | Or maybe 42 | 43 | ```sh 44 | $ cat readme.md | markdown-helpfile > doc/myplugin.txt 45 | $ vim doc/myplugin.txt 46 | ``` 47 | 48 | ## vim plugin 49 | 50 | This tool can also be used as a vim plugin. The plugin itself is a basic 51 | wrapper to the node script previously described. 52 | 53 | **Using pathogen** 54 | 55 | ```sh 56 | $ cd ~/.vim/bundle 57 | $ git clone git://github.com/mklabs/vim-markdown-helpfile.git 58 | $ cd vim-markdown-helpfile && npm install 59 | ``` 60 | 61 | It provides a single command `:MarkdownToHelpfile`, only on `markdown` buffer type. 62 | 63 | What it does: 64 | 65 | * convert the whole markdown document as vim helpfile 66 | * change filetype from markdown to `help` (`set ft=help`) 67 | 68 | The command also accepts a range, so you may convert only a small part of your 69 | markdown file. To see how it goes. Should it be useful. 70 | 71 | That's pretty much all it does.. 72 | 73 | --------------------------------------------------------------------------------