*readme.txt* VimDevIcons – Add Icons to Your Plugins =============================================================================== Contents ~ 1. Introduction |readme-introduction| 2. Image: vim-devicons (see reference [1]) |readme-image-vim-devicons| 1. Image: vim-devicons overall screenshot (see reference [17]) |readme-image-vim-devicons-overall-screenshot| 1. Features |readme-features| 2. Quick Links |readme-quick-links| 3. Table of Contents |readme-table-of-contents| 4. Installation |readme-installation| 1. Step 1 'Nerd Font' |Nerd-Font| 2. Step 2 'VimDevIcons Plugin' |VimDevIcons-Plugin| 1. Pathogen [26] |readme-pathogen-26| 2. NeoBundle [27] |readme-neobundle-27| 3. Vundle [28] |readme-vundle-28| 4. Manual |readme-manual| 3. Step 3 'Configure Vim' |Configure-Vim| 1. Set VimDevIcons to load _before_ these plugins! |readme-set-vimdevicons-to-load-_before_-these-plugins| 2. Set encoding to UTF-8 to show glyphs |readme-set-encoding-to-utf-8-to-show-glyphs| 3. Set Vim font to a Nerd Font |readme-set-vim-font-to-nerd-font| 4. If you use vim-airline you need this |readme-if-you-use-vim-airline-you-need-this| 5. vimrc examples |readme-vimrc-examples| 4. That's it! You're done. ✅ |readme-thats-it-youre-done.| 5. Usage |readme-usage| 1. Lightline Setup |readme-lightline-setup| 2. Powerline Setup |readme-powerline-setup| 6. Detailed Features |readme-detailed-features| 7. Extra Configuration |readme-extra-configuration| 1. Character Mappings |readme-character-mappings| 8. Public Methods |readme-public-methods| 9. Developer |readme-developer| 1. API |readme-api| 1. API Examples |readme-api-examples| 10. Todo |readme-todo| 11. License |readme-license| 12. FAQ / Troubleshooting |readme-faq-troubleshooting| 13. Screenshots |readme-screenshots| 14. Contributing |readme-contributing| 1. Promotion |readme-promotion| 2. Source code |readme-source-code| 15. Rationale |readme-rationale| 16. Inspiration and special thanks |readme-inspiration-special-thanks| 17. License 3. References |readme-references| =============================================================================== *readme-introduction* Introduction ~ =============================================================================== *readme-image-vim-devicons* Image: vim-devicons (see reference [1]) ~ Image: GitHub version [2] Image: Join the chat at https://gitter.im/ryanoasis /vim-devicons [4] Image: Flattr this git repo [6] **VimDevIcons** adds filetype glyphs (icons) to other plugins such as NERDTree [8], vim-airline [9], CtrlP [10], powerline [11], unite [12], lightline.vim [13], vim-startify [14], vimfiler [15], and flagship [16]. ------------------------------------------------------------------------------- *readme-image-vim-devicons-overall-screenshot* Image: vim-devicons overall screenshot (see reference [17]) ~ ------------------------------------------------------------------------------- *readme-features* Features ~ **VimDevIcons integrates with these plugins and more:** NERDTree [8] | vim-airline [9] | CtrlP [10] | powerline [11] | unite [12] | lightline.vim [13] | vim-startify [14] | vimfiler [15] | flagship [16] - Customizable and extendable glyphs (icons) settings - ability to override defaults and use your own characters or glyphs - Supports a wide range of file type extensions _(» More details... «)_ - Supports full filename matches _(» More details... «)_ - Supports library pattern matches _(» More details... «)_ - Works with patched fonts, especially Nerd Fonts [18] ------------------------------------------------------------------------------- *readme-quick-links* Quick Links ~ | **Screenshots**| **API** | **Fonts ➶ [19]** | **Patcher ➶ [18]** | |--------- -----------------------|-----------------|------------------------------|------ -----------------------| | Image: screenshots | Image: api | Image: patcher- logo-small [19] | Image: patcher-logo-small [18] | ------------------------------------------------------------------------------- *readme-table-of-contents* Table of Contents ~ **TL;DR Installation** **Installation** **Usage** _**Lightline Setup**_ **Powerline Setup** _**Extra Configuration**_ **Character Mappings** **Features** **Screenshots** **Methods** **Developer** _**API**_ **Contributing** _**Inspiration and special thanks**_ **Todo** * **License** **FAQ / Troubleshooting** **Rationale** Quick Installation (TL;DR) 1. Download and install a patched **Nerd Font [18]** (or patch your own) _(» More details... «) [18]_ 2. Install the plugin per your usual method _(» More details... «)_ 3. Configure Vim _(» More details... «)_ 4. a. **vim**: Set your terminal emulator font 5. b. **gvim**: Set 'guifont' in your 'vimrc' ------------------------------------------------------------------------------- *readme-installation* Installation ~ ------------------------------------------------------------------------------- *Nerd-Font* Step 1 'Nerd Font' ~ Get a **Nerd Font!** [24] or patch your own. [25] Without this, things break ------------------------------------------------------------------------------- *VimDevIcons-Plugin* Step 2 'VimDevIcons Plugin' ~ Choose your favorite plugin manager ------------------------------------------------------------------------------- *readme-pathogen-26* Pathogen [26] ~ - 'git clone https://github.com/ryanoasis/vim-devicons ~/.vim/bundle/vim- devicons' ------------------------------------------------------------------------------- *readme-neobundle-27* NeoBundle [27] ~ - Add to vimrc: "vim NeoBundle 'ryanoasis/vim-devicons'" * And install it: 'vim :so ~/.vimrc :NeoBundleInstall' ------------------------------------------------------------------------------- *readme-vundle-28* Vundle [28] ~ - Add to vimrc: "vim Plugin 'ryanoasis/vim-devicons'" * And install it: 'vim :so ~/.vimrc :PluginInstall' ------------------------------------------------------------------------------- *readme-manual* Manual ~ - copy all of the files into your '~/.vim' directory ------------------------------------------------------------------------------- *Configure-Vim* Step 3 'Configure Vim' ~ Add the following in your '.vimrc' or '.gvimrc': ------------------------------------------------------------------------------- *readme-set-vimdevicons-to-load-_before_-these-plugins* Set VimDevIcons to load _before_ these plugins! ~ NERDTree [8] | vim-airline [9] | CtrlP [29] | powerline [11] | unite [12] | lightline.vim [13] | vim-startify [14] | vimfiler [15] | flagship [16] ------------------------------------------------------------------------------- *readme-set-encoding-to-utf-8-to-show-glyphs* Set encoding to UTF-8 to show glyphs ~ 'vim set encoding=utf8' ------------------------------------------------------------------------------- *readme-set-vim-font-to-nerd-font* Set Vim font to a Nerd Font ~ Linux 'vim set guifont= ' > set guifont=Droid\ Sans\ Mono\ for\ Powerline\ Plus\ Nerd\ File\ Types\ 11 < macOS (OS X) and Windows > set guifont=:h < > set guifont=Droid\ Sans\ Mono\ for\ Powerline\ Plus\ Nerd\ File\ Types:h11 < **Note:** if you don't set 'guifont' then you'll have to set your terminal's font, else things break! ------------------------------------------------------------------------------- *readme-if-you-use-vim-airline-you-need-this* If you use vim-airline you need this ~ 'vim let g:airline_powerline_fonts = 1' ------------------------------------------------------------------------------- *readme-vimrc-examples* vimrc examples ~ - Sample Windows vimrc configuration 1 [30] - Sample Linux vimrc configuration 1 [31] ------------------------------------------------------------------------------- *readme-thats-it-youre-done.* That's it! You're done. ✅ ~ ------------------------------------------------------------------------------- *readme-usage* Usage ~ If you installed and setup things correctly you should now see icons in the supported plugins! **Notes on include order:** _for support of these plugins: NERDTree [8], vim- airline [9], CtrlP [29], powerline [11], unite [12], vimfiler [15], flagship [16] you **must** configure vim to load those plugins__before_ vim-devicons loads. for better nerdtree-git-plugin [32] support, you _should_ configure vim to load nerdtree-git-plugin **_before_** VimDevIcons loads. Lightline Setup and Powerline Setup require some extra setup as shown below: ------------------------------------------------------------------------------- *readme-lightline-setup* Lightline Setup ~ To add the appropriate icon to lightline [13], call the function 'WebDevIconsGetFileTypeSymbol()' and/or 'WebDevIconsGetFileFormatSymbol()' in your '.vimrc'. For example, you could set your sections to: > let g:lightline = { \ 'component_function': { \ 'filetype': 'MyFiletype', \ 'fileformat': 'MyFileformat', \ } \ } function! MyFiletype() return winwidth(0) > 70 ? (strlen(&filetype) ? &filetype . ' ' . WebDevIconsGetFileTypeSymbol() : 'no ft') : '' endfunction function! MyFileformat() return winwidth(0) > 70 ? (&fileformat . ' ' . WebDevIconsGetFileFormatSymbol()) : '' endfunction < ------------------------------------------------------------------------------- *readme-powerline-setup* Powerline Setup ~ - _Note this is for the current Powerline [11] not the deprecated vim- powerline [33]_ To enable for Powerline [11] some 'vimrc' and powerline configuration changes are needed: 'vimrc' changes (only required if you don't already have powerline setup for vim): > set rtp+=$HOME/.local/lib/python2.7/site-packages/powerline/bindings/vim/ " Always show statusline set laststatus=2 " Use 256 colours (Use this setting only if your terminal supports 256 colours) set t_Co=256 < powerline configuration changes: file type segment > { "function": "vim_devicons.powerline.segments.webdevicons", "priority": 10, "draw_soft_divider": false, "after": " " } < file format segment > { "function": "vim_devicons.powerline.segments.webdevicons_file_format", "draw_soft_divider": false, "exclude_modes": ["nc"], "priority": 90 } < for full example see sample file [34] ------------------------------------------------------------------------------- *readme-detailed-features* Detailed Features ~ - Adds filetype glyphs (icons) to various vim plugins, currently supports: - NERDTree [8] - vim-airline [9] (statusline and tabline) - CtrlP [10] - Currently only MRU file mode supported - powerline [11] (statusline) - see: powerline setup - unite [12] - Currently supports 'file', 'file_rec', 'buffer', 'file_rec/async', and 'file_rec/neovim' - lightline.vim [13] (statusline) - see: lightline setup - vim-startify [14] - vimfiler [15] - flagship [16] - Support is **experimental** because the API may be changing [35] - Customizable and extendable glyphs (icons) settings - ability to override defaults and use your own characters or glyphs - Supports a wide range of file type extensions by default: - 'styl, scss, htm, html, slim, ejs, css, less, md, json, js, jsx, rb, php, py, pyc, pyd, pyo, coffee, mustache, hbs, conf, ini, yml, bat, jpg, jpeg, bmp, png, gif, twig, cpp, c++, cxx, cc, cp, c, hs, lhs, lua, java, sh, fish, diff, db, clj, cljs, edn, scala, go, dart, xul, sln, suo, pl, pm, t, rss, f#, fsscript, fsx, fs, fsi, rs, rlib, d, erl, hrl, vim, ai, psd, psb, ts, jl' - Supports a few full filename matches, by default: - 'gruntfile.coffee, gruntfile.js, gruntfile.ls, gulpfile.coffee, gulpfile.js, gulpfile.ls, dropbox, .ds_store, .gitconfig, .gitignore, .bashrc, .bashprofile, favicon.ico, license, node_modules, react.jsx, procfile' - Supports a few library pattern matches, by default: - 'jquery, angular, backbone, requirejs, materialize, mootools' - Works with patched fonts, especially Nerd Fonts [18] ------------------------------------------------------------------------------- *readme-extra-configuration* Extra Configuration ~ - These options can be defined in your 'vimrc' or 'gvimrc' - Most options are enabled **'1'** by default but can be disabled with **'0'** - You _should_**not** need to configure anything, however, the following options are provided for customizing or changing the defaults: > " loading the plugin let g:webdevicons_enable = 1 < > " adding the flags to NERDTree let g:webdevicons_enable_nerdtree = 1 < > " adding the custom source to unite let g:webdevicons_enable_unite = 1 < > " adding the column to vimfiler let g:webdevicons_enable_vimfiler = 1 < > " adding to vim-airline's tabline let g:webdevicons_enable_airline_tabline = 1 < > " adding to vim-airline's statusline let g:webdevicons_enable_airline_statusline = 1 < > " ctrlp MRU file mode glyphs let g:webdevicons_enable_ctrlp = 1 < > " adding to flagship's statusline let g:webdevicons_enable_flagship_statusline = 1 < > " turn on/off file node glyph decorations (not particularly useful) let g:WebDevIconsUnicodeDecorateFileNodes = 1 < > " use double-width(1) or single-width(0) glyphs " only manipulates padding, has no effect on terminal or set(guifont) font let g:WebDevIconsUnicodeGlyphDoubleWidth = 1 < > " whether or not to show the nerdtree brackets around flags let g:webdevicons_conceal_nerdtree_brackets = 1 < > " the amount of space to use after the glyph character (default ' ') let g:WebDevIconsNerdTreeAfterGlyphPadding = ' ' < > " Force extra padding in NERDTree so that the filetype icons line up vertically let g:WebDevIconsNerdTreeGitPluginForceVAlign = 1 < ------------------------------------------------------------------------------- *readme-character-mappings* Character Mappings ~ - 'ƛ' is used as an example below, substitute for the glyph you **actually** want to use > " change the default character when no match found let g:WebDevIconsUnicodeDecorateFileNodesDefaultSymbol = 'ƛ' < > " enable folder/directory glyph flag (disabled by default with 0) let g:WebDevIconsUnicodeDecorateFolderNodes = 1 < > " enable open and close folder/directory glyph flags (disabled by default with 0) let g:DevIconsEnableFoldersOpenClose = 1 < > " enable pattern matching glyphs on folder/directory (enabled by default with 1) let g:DevIconsEnableFolderPatternMatching = 1 < > " enable file extension pattern matching glyphs on folder/directory (disabled by default with 0) let g:DevIconsEnableFolderExtensionPatternMatching = 0 < > " enable custom folder/directory glyph exact matching " (enabled by default when g:WebDevIconsUnicodeDecorateFolderNodes is set to 1) let WebDevIconsUnicodeDecorateFolderNodesExactMatches = 1 < > " change the default folder/directory glyph/icon let g:WebDevIconsUnicodeDecorateFolderNodesDefaultSymbol = 'ƛ' < > " change the default open folder/directory glyph/icon (default is '') let g:DevIconsDefaultFolderOpenSymbol = 'ƛ' < > " change the default dictionary mappings for file extension matches let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols = {} " needed let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols['js'] = 'ƛ' < > " change the default dictionary mappings for exact file node matches let g:WebDevIconsUnicodeDecorateFileNodesExactSymbols = {} " needed let g:WebDevIconsUnicodeDecorateFileNodesExactSymbols['MyReallyCoolFile.okay'] = 'ƛ' < > " add or override individual additional filetypes let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols = {} " needed let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols['myext'] = 'ƛ' < > " add or override pattern matches for filetypes " these take precedence over the file extensions let g:WebDevIconsUnicodeDecorateFileNodesPatternSymbols = {} " needed let g:WebDevIconsUnicodeDecorateFileNodesPatternSymbols['.*jquery.*\.js$'] = 'ƛ' < specify OS to decide an icon for unix fileformat (_not_ defined by default) - this is useful for avoiding unnecessary 'system()' call. see #135 [36] for further details. > let g:WebDevIconsOS = 'Darwin' < ------------------------------------------------------------------------------- *readme-public-methods* Public Methods ~ > " Returns the current version of the plugin webdevicons#version() < > " Calls webdevicons#softRefresh() " basically a backwards compatibility convenience webdevicons#refresh() < > " Does a 'hard' refresh of NERDTree " resets vim-devicons syntax and closes and reopens NERDTree webdevicons#hardRefresh() < > " Does a 'soft' refresh of NERDTree " resets vim-devicons syntax and toggles NERDTree to the same state webdevicons#softRefresh() < ------------------------------------------------------------------------------- *readme-developer* Developer ~ ------------------------------------------------------------------------------- *readme-api* API ~ > " returns the font character that represents the icon " parameters: a:1 (filename), a:2 (isDirectory) " both parameters optional " by default without parameters uses buffer name WebDevIconsGetFileTypeSymbol(...) " returns the font character that represents " the file format as an icon (windows, linux, mac) WebDevIconsGetFileFormatSymbol() < ------------------------------------------------------------------------------- *readme-api-examples* API Examples ~ > let entry_format = "' ['. index .']'. repeat(' ', (3 - strlen(index)))" if exists('*WebDevIconsGetFileTypeSymbol') " support for vim-devicons let entry_format .= ". WebDevIconsGetFileTypeSymbol(entry_path) .' '. entry_path" else let entry_format .= '. entry_path' endif < source: vim-startify [14] > echo WebDevIconsGetFileFormatSymbol() < ------------------------------------------------------------------------------- *readme-todo* Todo ~ - [ ] more filetypes to support - [ ] customize filetype icon colors - [ ] more customization options in general - [ ] more specific FAQ and Troubleshooting help ------------------------------------------------------------------------------- *readme-license* License ~ See LICENSE ------------------------------------------------------------------------------- *readme-faq-troubleshooting* FAQ / Troubleshooting ~ See FAQ [37] ------------------------------------------------------------------------------- *readme-screenshots* Screenshots ~ See Screenshots [38] ------------------------------------------------------------------------------- *readme-contributing* Contributing ~ Best ways to contribute _Star it on GitHub - if you use it and like it please at least star it :)_ Promote _Open issues/tickets [39]_ Submit fixes and/or improvements with Pull Requests ------------------------------------------------------------------------------- *readme-promotion* Promotion ~ Like the project? Please support to ensure continued development going forward: _Star this repo on GitHub [40]_ Follow the repo on GitHub [40] _Vote for it on vim.org [41]_ Follow me * Twitter [42] * GitHub [43] ------------------------------------------------------------------------------- *readme-source-code* Source code ~ Contributions and Pull Requests are welcome. No real formal process has been setup - just stick to general good conventions for now. ------------------------------------------------------------------------------- *readme-rationale* Rationale ~ After seeing the awesome theme for Atom (seti-ui) and the awesome plugins work done for NERDTree and vim-airline and wanting something like this for Vim I decided to create my first plugin. ------------------------------------------------------------------------------- *readme-inspiration-special-thanks* Inspiration and special thanks ~ - vim-airline [9] - nerdtree [8] - nerdtree-git-plugin [32] - seti-ui [44] - devicons by Theodore Vorillas [45] - benatespina development.svg.icons [46] - Steve Losh [47] - Also thanks to the many contributors [48] ------------------------------------------------------------------------------- License ~ See LICENSE =============================================================================== *readme-references* References ~ [1] https://github.com/ryanoasis/vim-devicons/wiki/screenshots/v0.8.x/branding-logo.png [2] http://badge.fury.io/gh/ryanoasis%2Fvim-devicons [3] https://badge.fury.io/gh/ryanoasis%2Fvim-devicons.svg [4] https://gitter.im/ryanoasis/vim-devicons?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge [5] https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat [6] https://flattr.com/submit/auto?user_id=ryanoasis&url=https://github.com/ryanoasis/vim-devicons&title=vim-devicons&language=viml&tags=github&category=software [7] https://img.shields.io/badge/donate-flattr%20this!-8DB65B.svg?style=flat [8] https://github.com/scrooloose/nerdtree [9] https://github.com/bling/vim-airline [10] https://github.com/ctrlpvim/ctrlp.vim [11] https://github.com/powerline/powerline [12] https://github.com/Shougo/unite.vim [13] https://github.com/itchyny/lightline.vim [14] https://github.com/mhinz/vim-startify [15] https://github.com/Shougo/vimfiler.vim [16] https://github.com/tpope/vim-flagship [17] https://github.com/ryanoasis/vim-devicons/wiki/screenshots/v0.8.x/overall-screenshot.png [18] https://github.com/ryanoasis/nerd-fonts [19] https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts [20] https://github.com/ryanoasis/vim-devicons/wiki/screenshots/v1.0.0/branding-logo-screenshots-sm.png [21] https://github.com/ryanoasis/vim-devicons/wiki/screenshots/v1.0.0/branding-logo-api-sm.png [22] https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/images/nerd-fonts-character-logo-md.png [23] https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/images/nerd-fonts-patcher-logo-md.png [24] https://github.com/ryanoasis/nerd-fonts#font-installation [25] https://github.com/ryanoasis/nerd-fonts#font-patcher [26] https://github.com/tpope/vim-pathogen [27] https://github.com/Shougo/neobundle.vim [28] https://github.com/gmarik/vundle [29] https://github.com/kien/ctrlp.vim [30] https://github.com/ryanoasis/vim-devicons/wiki/samples/v0.8.x/.vimrc-windows-1 [31] https://github.com/ryanoasis/vim-devicons/wiki/samples/v0.8.x/.vimrc-linux-1 [32] https://github.com/Xuyuanp/nerdtree-git-plugin [33] https://github.com/Lokaltog/vim-powerline [34] https://github.com/ryanoasis/vim-devicons/wiki/samples/v0.8.x/powerline/themes/vim/default.json [35] https://github.com/tpope/vim-flagship/issues/6#issuecomment-116121220 [36] https://github.com/ryanoasis/vim-devicons/pull/135 [37] https://github.com/ryanoasis/vim-devicons/wiki/FAQ [38] https://github.com/ryanoasis/vim-devicons/wiki/Screenshots [39] https://github.com/ryanoasis/vim-devicons/issues [40] https://github.com/ryanoasis/vim-devicons [41] http://www.vim.org/scripts/script.php?script_id=5114 [42] http://twitter.com/ryanlmcintyre [43] https://github.com/ryanoasis [44] https://atom.io/themes/seti-ui [45] http://vorillaz.github.io/devicons [46] https://github.com/benatespina/development.svg.icons [47] http://learnvimscriptthehardway.stevelosh.com/ [48] https://github.com/ryanoasis/vim-devicons/graphs/contributors vim: ft=help