#+TITLE: nerd-icons.el - A Library for Nerd Font icons
#+AUTHOR: Hongyu Ding
#+LANGUAGE: en

[[https://melpa.org/#/nerd-icons][file:https://melpa.org/packages/nerd-icons-badge.svg]]

Nerd-icons.el is a library for easily using [[https://github.com/ryanoasis/nerd-fonts][Nerd Font]] icons inside Emacs, an alternative to [[https://github.com/domtronn/all-the-icons.el][all-the-icons]].

It works on both GUI and terminal! You only need a [[https://www.nerdfonts.com/#home][Nerd Font]] installed on your system.

It is inspired by [[https://github.com/domtronn/all-the-icons.el][all-the-icons]], [[https://github.com/seagle0128/icons-in-terminal.el][icons-in-terminal]], [[https://github.com/ryanoasis/vim-devicons][vim-devicons]], and [[https://github.com/nvim-tree/nvim-web-devicons][nvim-web-devicons]].

in GUI:
[[file:screenshots/demo.png]]

in terminal:
[[file:screenshots/demo-terminal.png]]

* Installing Fonts
Please go to [[https://www.nerdfonts.com/][Nerd Fonts website]] and get a Nerd font. After installing the font on your machine, you need to set ~nerd-icons-font-family~ to match its font name so that the font can be properly used under GUI. If you want Nerd Fonts to work under a terminal, please change your terminal's font to a Nerd font.

If the Nerd Font you installed does not display correctly (e.g. appear cut off), it is recommended to use =Symbols Nerd Font Mono= (Symbols Nerd Font). You can use ~M-x nerd-icons-install-fonts~ to install ~Symbols Nerd Font Mono~ for you. Note that for *Windows* you'll need to manually install the font after you used this function.

To automatically install =Symbols Nerd Font Mono=, you can use this elisp in your ~init.el~. On macOS, Linux and BSDs, this will download and install the font directly for you. On Windows, you can specify the folder to download the font to, but you will still have to manually install it after.

#+BEGIN_SRC emacs-lisp
;; Linux/macOS/BSDs
(when (member system-type '(gnu gnu/linux gnu/kfreebsd darwin))
  (unless (find-font (font-spec :name "Symbols Nerd Font Mono"))
    (nerd-icons-install-fonts t)))

;; Windows
(when (string-equal system-type 'windows-nt)
  (unless (find-font (font-spec :name "Symbols Nerd Font Mono"))
    (nerd-icons-install-fonts "c:/Users/username/Desktop/")))

;; All-in-one
;; This will install in the default fonts folder for Linux/macOS/BSDs
;; (same as “t”), but for Windows this will download to the specified
;; folder
(unless (find-font (font-spec :name "Symbols Nerd Font Mono"))
  (nerd-icons-install-fonts "c:/Users/username/Desktop/"))
#+END_SRC

* Usage
~nerd-icons~ is on [[https://melpa.org/#/nerd-icons-completion][Melpa]]. You can install it with built-in ~M-x package-install~
#+begin_src emacs-lisp
  (require 'nerd-icons)
#+end_src

or using ~use-package~
#+BEGIN_SRC emacs-lisp
  (use-package nerd-icons
    ;; :custom
    ;; The Nerd Font you want to use in GUI
    ;; "Symbols Nerd Font Mono" is the default and is recommended
    ;; but you can use any other Nerd Font if you want
    ;; (nerd-icons-font-family "Symbols Nerd Font Mono")
    )
#+END_SRC
** insert icons
+ use icon based on category
  - ~nerd-icons-icon-for-dir~
  - ~nerd-icons-icon-for-file~
  - ~nerd-icons-icon-for-extension~
  - ~nerd-icons-icon-for-mode~
  - ~nerd-icons-icon-for-url~
  - ~nerd-icons-icon-for-buffer~

  example:
  #+BEGIN_SRC emacs-lisp
    (insert (nerd-icons-icon-for-file "init.el"))
    ;; Inserts an icon for Emacs Lisp
  #+END_SRC
+ use icon directly
  - ~nerd-icons-ipsicon~
  - ~nerd-icons-octicon~
  - ~nerd-icons-pomicon~
  - ~nerd-icons-powerline~
  - ~nerd-icons-faicon~
  - ~nerd-icons-wicon~
  - ~nerd-icons-sucicon~
  - ~nerd-icons-devicon~
  - ~nerd-icons-codicon~
  - ~nerd-icons-flicon~
  - ~nerd-icons-mdicon~

  example:
  #+BEGIN_SRC emacs-lisp
    (insert (nerd-icons-faicon "nf-fa-gitlab"))
    ;; Inserts a Gitlab icon
#+END_SRC
+ insert icon interactively (~M-x~ functions)
  - ~nerd-icons-insert~
  - ~nerd-icons-insert-ipsicon~
  - ~nerd-icons-insert-octicon~
  - ~nerd-icons-insert-pomicon~
  - ~nerd-icons-insert-powerline~
  - ~nerd-icons-insert-faicon~
  - ~nerd-icons-insert-wicon~
  - ~nerd-icons-insert-sucicon~
  - ~nerd-icons-insert-devicon~
  - ~nerd-icons-insert-codicon~
  - ~nerd-icons-insert-flicon~
  - ~nerd-icons-insert-mdicon~

** customize icons
You can customize the icons via ~nerd-icons-extension-icon-alist~, ~nerd-icons-regexp-icon-alist~ and ~nerd-icons-mode-icon-alist~, etc.

For example,
#+begin_src emacs-lisp
(add-to-list 'nerd-icons-extension-icon-alist '("epub" nerd-icons-faicon "nf-fa-book" :face nerd-icons-green))
#+end_src

* Glyph Sets
| Glyph Set               | prefix               | Point Range                          | insert function      |
|-------------------------+----------------------+--------------------------------------+----------------------|
| Seti-UI + Custom        | ~nf-seti-~, ~nf-custom-~ | ~e5fa~ - ~e6bb~                          | ~nerd-icons-sucicon~   |
| Devicons                | ~nf-dev-~              | ~e700~ - ~e958~                          | ~nerd-icons-devicon~   |
| Font Awesome            | ~nf-fa-~               | ~f000~ - ~f2e0~                          | ~nerd-icons-faicon~    |
| Font Awesome Extension  | ~nf-fae-~              | ~e200~ - ~e2a9~                          | ~nerd-icons-faicon~    |
| Material Design Icons   | ~nf-md-~               | ~f500~ - ~fd46~                          | ~nerd-icons-mdicon~    |
| Weather                 | ~nf-weather-~          | ~e300~ - ~e3eb~                          | ~nerd-icons-wicon~     |
| Octicons                | ~nf-oct-~              | ~f400~ - ~f4a9~, ~2665~, ~26A1~              | ~nerd-icons-octicon~   |
| Powerline Symbols       | ~nf-pl-~               | ~e0a0~ - ~e0a2~, ~e0b0~ - ~e0b3~             | ~nerd-icons-powerline~ |
| Powerline Extra Symbols | ~nf-ple-~              | ~e0a3~, ~e0b4~ - ~e0c8~, ~e0ca~, ~e0cc~ - ~e0d4~ | ~nerd-icons-powerline~ |
| IEC Power Symbols       | ~nf-iec-~              | ~23fb~ - ~23fe~, ~2b58~                    | ~nerd-icons-ipsicon~   |
| Font Logos              | ~nf-linux-~            | ~f300~ - ~f385~                          | ~nerd-icons-flicon~    |
| Pomicons                | ~nf-pom-~              | ~e000~ - ~e00a~                          | ~nerd-icons-pomicon~   |
| Codicons                | ~nf-cod-~              | ~ea60~ - ~ec84~                          | ~nerd-icons-codicon~   |

Please check [[https://github.com/ryanoasis/nerd-fonts/wiki/Glyph-Sets-and-Code-Points][Nerd Fonts Glyph Sets and Code Points]] for more information.

* Related Packages
+ [[https://github.com/rainstormstudio/nerd-icons-dired][nerd-icons-dired]]
+ [[https://github.com/abougouffa/nerd-icons-multimodal][nerd-icons-multimodal]]
+ [[https://github.com/rainstormstudio/treemacs-nerd-icons][treemacs-nerd-icons]]
+ [[https://github.com/seagle0128/nerd-icons-ivy-rich][nerd-icons-ivy-rich]]
+ [[https://github.com/seagle0128/nerd-icons-ibuffer][nerd-icons-ibuffer]]
+ [[https://github.com/rainstormstudio/nerd-icons-completion][nerd-icons-completion]]
+ [[https://github.com/LuigiPiucco/nerd-icons-corfu][nerd-icons-corfu]]
+ [[https://github.com/alexluigit/dirvish][dirvish]]
+ [[https://github.com/seagle0128/doom-modeline][doom-modeline]]
+ [[https://github.com/grolongo/nerd-icons-mode-line][nerd-icons-mode-line]]
+ [[https://github.com/lucius-martius/tab-line-nerd-icons][tab-line-nerd-icons]]

** use nerd-icons with dirvish
sample configuration:
#+BEGIN_SRC emacs-lisp
(use-package dirvish
  :init
  (dirvish-override-dired-mode)
  :config
  (setq dirvish-mode-line-format
        '(:left (sort symlink) :right (omit yank index)))
  (setq dirvish-mode-line-height 10)
  (setq dirvish-attributes
        '(nerd-icons file-time file-size collapse subtree-state vc-state git-msg))
  (setq dirvish-subtree-state-style 'nerd)
  (setq delete-by-moving-to-trash t)
  (setq dirvish-path-separators (list
                                 (format "  %s " (nerd-icons-codicon "nf-cod-home"))
                                 (format "  %s " (nerd-icons-codicon "nf-cod-root_folder"))
                                 (format " %s " (nerd-icons-faicon "nf-fa-angle_right"))))
  (setq dired-listing-switches
        "-l --almost-all --human-readable --group-directories-first --no-group")
  (dirvish-peek-mode) ; Preview files in minibuffer
  (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode'
)
#+END_SRC