diff --git a/doc/_static/nerd-fonts/bad.png b/doc/_static/nerd-fonts/bad.png new file mode 100644 index 00000000..5e433030 Binary files /dev/null and b/doc/_static/nerd-fonts/bad.png differ diff --git a/doc/_static/nerd-fonts/good.png b/doc/_static/nerd-fonts/good.png new file mode 100644 index 00000000..d70f1a32 Binary files /dev/null and b/doc/_static/nerd-fonts/good.png differ diff --git a/doc/index.rst b/doc/index.rst index 2ccbb077..60f5d32a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,6 +15,7 @@ Welcome to the official polybar documentation. user/actions user/ipc user/modules/index + user/fonts/index user/default-config migration/index diff --git a/doc/user/fonts/index.rst b/doc/user/fonts/index.rst new file mode 100644 index 00000000..c9773f88 --- /dev/null +++ b/doc/user/fonts/index.rst @@ -0,0 +1,8 @@ +Fonts +===== + +.. toctree:: + :maxdepth: 1 + + Wiki + Nerd Fonts diff --git a/doc/user/fonts/nerd-fonts.rst b/doc/user/fonts/nerd-fonts.rst new file mode 100644 index 00000000..c8c0dd12 --- /dev/null +++ b/doc/user/fonts/nerd-fonts.rst @@ -0,0 +1,54 @@ +Nerd Fonts +========== + +`Nerd Fonts `_ (`GitHub +`_) is a project that patches +together a textual font with font icons (or glyphs) from other projects (e.g. +`Font Awesome `_, `Material Design +Icons `_, etc.) into a single +font. + +In polybar, just using nerd fonts can lead to some issues: + +* Cut-off Characters +* Overlapping +* No Spacing + +These look something like this: + +.. image:: /_static/nerd-fonts/bad.png + :alt: Showcase of the three issues listed above. + +This behavior is intrinsic to Nerd Fonts and is described in more detail `here +`_. +Also see :issue:`991` for more information. + +**To resolve these issues, we recommend using Nerd Fonts like this:** + +The monospaced variants of the different Nerd Fonts (all characters have the +same width) don't have this issue. +However, then you often have the problem that the icons are too small and that +their size cannot be set independently of the text. + +Due to that, we recommend using ``Symbols Nerd Font Mono`` (available for +`download `_ as +``NerdFontsSymbolsOnly.zip``). +This font only contains the nerd font icons and no text. +For the text, simply use any non-Nerd Font: + +.. code-block:: ini + + font-0 = "Liberation Mono:size=20" + font-1 = "Symbols Nerd Font Mono:size=26" + +Now the icon sizes can be adjusted separately to get the best experience. +This solves all three problems shown above: + +.. image:: /_static/nerd-fonts/good.png + :alt: The same config as in the previous screenshot but using ``Symbols Nerd + Font Mono`` for the font icons + +.. note:: + + In the overlap example, there is no space between the icon and text, that's + why they're so close together.