diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9cf5c9b..4945ab38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,22 +4,24 @@ Thank you for your contribution! ## Order -Please ensure `icons_by_filename`, `icons_by_file_extension` and `filetypes` are ordered alphabetically, to prevent merge conflicts. +Please ensure `icons_by_filename`, `icons_by_file_extension`, `icons_by_operating_system`, `icons_by_desktop_environment`, +`icons_by_window_manager` and `filetypes` are ordered alphabetically, to prevent merge conflicts. ## Prerequisites -Code is formatted using stylua and linted using luacheck. +Code is formatted using *stylua* and linted using *luacheck*. You can install these with: + ```sh cargo install stylua luarocks install luacheck ``` -or via your OS package manager e.g. Arch linux: +or via your OS package manager e.g. *Arch Linux*: + ```sh -pacman -S stylua -pacman -S luacheck +pacman -S stylua luacheck ``` ## Building @@ -31,13 +33,16 @@ make ``` This will: + 1. `git clone --depth 1 https://github.com/lifepillar/vim-colortemplate.git vim-colortemplate` if necessary -1. Generate cterm colors -2. Generate light color variants -3. Check style -4. Lint +2. Generate cterm colors +3. Generate light color variants +4. Check style +5. Lint +6. Find missing filetypes You can automatically fix any style issues via: + ```sh make style-fix ``` @@ -46,15 +51,20 @@ make style-fix Add or update icons in `lua/nvim-web-devicons/icons-default.lua` -There are two tables where icons can be added: -1. icons_by_filename -2. icons_by_file_extension +There are five tables where icons can be added: + +1. `icons_by_filename` +2. `icons_by_file_extension` +3. `icons_by_operating_system` +4. `icons_by_desktop_environment` +5. `icons_by_window_manager` + +Add the icon to table **1.** if the icon is for a file that is always named that way, for example `.gitconfig`. +Add the icon to table **2.** if the icon is for all files with an extension, for example `vim`. +Add the icon to table **3.**, **4.**, **5.** if the icon is from an OS, DE or WM. -Add the icon in table 1. if the icon is for a file that is always named that -way, for example `.gitconfig`. Add to table 2. if the icon is for all files -with an extension. +Each icon must have the following structure (this is an example): -Each icon must have the following (this is an example): ```lua [".gitconfig"] = { icon = "", @@ -63,15 +73,16 @@ Each icon must have the following (this is an example): name = "GitConfig", }, ``` -___Key/value pairs must appear in the same exact order!___ + +***Key/value pairs must appear in the same exact order!*** - `color` must contain a color in the html notation - `cterm_color` must be below `color`, and it must contain a number (any number) - the correct value for `cterm_color` will be generated by the script - `name` must only contain alphanumeric characters (don't use `/`, `-`, `_`) -Ensure your current working directory is the repo root. -Run `make`. This will: +Ensure your current working directory is the repo root. Run `make`. This will: + - Update `cterm_color` based on `color` - Generate `lua/nvim-web-devicons/icons-light.lua` @@ -81,7 +92,7 @@ Please commit both `lua/nvim-web-devicons/icons-default.lua` and `lua/nvim-web-d Run `:NvimWebDeviconsHiTest` to view the icons and their highlighting. -Start neovim with `TERM=xterm-256color nvim ...` to test cterm. +Start *Neovim* with `TERM=xterm-256color nvim ...` to test cterm. Check with `&background` `dark` and `light` @@ -89,36 +100,39 @@ Check with `&background` `dark` and `light` When modifying or adding API, please update [Usage](README.md#Usage) -# Pull Request +## Pull Request Please reference any issues in the description e.g. "resolves #1234", which will be closed upon merge. -Please check "allow edits by maintainers" to allow nvim-web-devicons maintainers to make small changes such as documentation tweaks. +Please check "allow edits by maintainers" to allow *nvim-web-devicons* maintainers to make small changes +such as documentation tweaks. ## Subject The merge commit message will be the subject of the PR. -A [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) subject will be validated by the Semantic Pull Request Subject CI job. Reference the issue to be used in the release notes e.g. +A [Conventional Commits] subject will be validated by the Semantic Pull Request Subject CI job. +Reference the issue to be used in the release notes e.g. -``` +```txt feat: add gradle icons fix: update rust icon feat(#192): :NvimWebDeviconsHiTest ``` Available types: -* feat: A new feature -* fix: A bug fix -* docs: Documentation only changes -* style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) -* refactor: A code change that neither fixes a bug nor adds a feature -* perf: A code change that improves performance -* test: Adding missing tests or correcting existing tests -* build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) -* ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) -* chore: Other changes that don't modify src or test files -* revert: Reverts a previous commit + +- feat: A new feature +- fix: A bug fix +- docs: Documentation only changes +- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- refactor: A code change that neither fixes a bug nor adds a feature +- perf: A code change that improves performance +- test: Adding missing tests or correcting existing tests +- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) +- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) +- chore: Other changes that don't modify src or test files +- revert: Reverts a previous commit If in doubt, look at previous commits. @@ -130,7 +144,9 @@ It is useful to see the actual glyphs in the pull request. That can be done by s Using firefox: -* Settings -> General -* Fonts -> Advanced -* Change Monospace to "Hack Nerd Font Mono" or similar -* Uncheck "Allow pages to choose their own fonts, instead of your selections above" +- Settings -> General +- Fonts -> Advanced +- Change Monospace to "Hack Nerd Font Mono" or similar +- Uncheck "Allow pages to choose their own fonts, instead of your selections above" + +[Conventional Commits]: diff --git a/README.md b/README.md index 1922f906..4719a4e8 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,7 @@ -# Notice -Nerd fonts moved some symbols with version 3.0. Version 2.3 is meant for transition, supporting both version 2 and version 3 icons. - -Nvim-web-devicons requires version 2.3 or above to work properly. If you are unable to update please use your plugin manager to pin version of nvim-web-dev icons to `nerd-v2-compat` tag. - # Nvim-web-devicons -Provides [Nerd Font](https://www.nerdfonts.com/) [1] icons (glyphs) for use by neovim plugins: +Provides [Nerd Font](https://www.nerdfonts.com/) [^1] icons (glyphs) for use by *Neovim* plugins: + - Icons by: - Extension - Full name @@ -15,7 +11,13 @@ Provides [Nerd Font](https://www.nerdfonts.com/) [1] icons (glyphs) f A `lua` fork of [vim-devicons](https://github.com/ryanoasis/vim-devicons). -[1] Not limited to Nerd Font icons: unicode and other fonts may be used. +> [!IMPORTANT] +> Nerd fonts moved some symbols with version 3.0. Version 2.3 is meant for transition, +> supporting both version 2 and version 3 icons. +> Nvim-web-devicons requires version 2.3 or above to work properly. If you are unable to update +> please use your plugin manager to pin version of nvim-web-dev icons to `nerd-v2-compat` tag. + +[^1]: Not limited to Nerd Font icons: unicode and other fonts may be used. ## Requirements @@ -30,10 +32,16 @@ Plug 'nvim-tree/nvim-web-devicons' or with [packer.nvim](https://github.com/wbthomason/packer.nvim) -``` +```lua use 'nvim-tree/nvim-web-devicons' ``` +or with [lazy.nvim](https://github.com/folke/lazy.nvim) + +```lua +{ "nvim-tree/nvim-web-devicons", opts = {} }, +``` + [![LuaRocks](https://img.shields.io/luarocks/v/nvim-tree/nvim-web-devicons?logo=lua&color=purple)](https://luarocks.org/modules/nvim-tree/nvim-web-devicons) ## Usage @@ -48,6 +56,7 @@ Light or dark color variants of the icons depend on `&background`. The variant can also be set manually in `setup` with the `variant` option. The variant is updated: + - on `OptionSet` event for `background`, or - after explicitly calling `require("nvim-web-devicons").refresh()`. @@ -68,7 +77,7 @@ if the color scheme changes ```lua require'nvim-web-devicons'.setup { - -- your personnal icons can go here (to override) + -- your personal icons can go here (to override) -- you can specify color or cterm_color instead of specifying both of them -- DevIcon will be appended to `name` override = { @@ -126,7 +135,7 @@ require'nvim-web-devicons'.setup { ### Get Icon -Get the icon for a given file by passing in the `name`, the `extension` and an _optional_ options `table`. +Get the icon for a given file by passing in the `name`, the `extension` and an *optional* options `table`. The name is passed in to check for an exact match e.g. `.bashrc` if there is no exact name match the extension is used. Calls `.setup()` if it hasn't already ran. @@ -146,6 +155,7 @@ require'nvim-web-devicons'.get_icon(filename, extension, { default = true }) ``` You can check if the setup function was already called with: + ```lua require'nvim-web-devicons'.has_loaded() ``` @@ -156,6 +166,7 @@ require'nvim-web-devicons'.has_loaded() `get_icon_cterm_color` returns cterm color instead of gui color `get_icon` returns icon and highlight name. If you want to get color code, you can use this function. + ```lua local icon, color = require'nvim-web-devicons'.get_icon_color("init.lua", "lua") assert(icon == "") @@ -220,7 +231,8 @@ or set the icon to use for a filetype with: require("nvim-web-devicons").set_icon_by_filetype { cpp = "c", pandoc = "md", } ``` -These functions are the same as their counterparts without the `_by_filetype` suffix, but they take a filetype instead of a name/extension. +These functions are the same as their counterparts without the `_by_filetype` suffix, +but they take a filetype instead of a name/extension. You can also use `get_icon_name_by_filetype(filetype)` to get the icon name associated with the filetype.