Skip to content

Commit

Permalink
docs: improve instructions and apply style
Browse files Browse the repository at this point in the history
  • Loading branch information
@hasecilu
hasecilu committed Dec 26, 2024
1 parent ec5fa0f commit c5e49f5
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 50 deletions.
94 changes: 55 additions & 39 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -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 = "",
Expand All @@ -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`

Expand All @@ -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.

Expand All @@ -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>
34 changes: 23 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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()`.

Expand All @@ -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 = {
Expand Down Expand Up @@ -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.

Expand All @@ -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()
```
Expand All @@ -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 == "")
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit c5e49f5

Please sign in to comment.