docs: improve instructions and apply style

Author: hasecilu

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,44 +92,47 @@ 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`
 
 ## Documentation
 
 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]: <https://www.conventionalcommits.org/en/v1.0.0>

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/) <sup>[1]</sup> 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/) <sup>[1]</sup> icons (glyphs) f
 
 A `lua` fork of [vim-devicons](https://github.com/ryanoasis/vim-devicons).
 
-<sup>[1]</sup> 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.