diff --git a/content/docs/ports/tmux/configuration/font-rendering-patched-font-disabled.png b/content/docs/ports/tmux/configuration/font-rendering-patched-font-disabled.png new file mode 100644 index 00000000..b9451853 Binary files /dev/null and b/content/docs/ports/tmux/configuration/font-rendering-patched-font-disabled.png differ diff --git a/content/docs/ports/tmux/configuration/font-rendering-patched-font.png b/content/docs/ports/tmux/configuration/font-rendering-patched-font.png new file mode 100644 index 00000000..efc87901 Binary files /dev/null and b/content/docs/ports/tmux/configuration/font-rendering-patched-font.png differ diff --git a/content/docs/ports/tmux/configuration/index.mdx b/content/docs/ports/tmux/configuration/index.mdx new file mode 100644 index 00000000..51409565 --- /dev/null +++ b/content/docs/ports/tmux/configuration/index.mdx @@ -0,0 +1,113 @@ +import Link from "atoms/core/Link"; +import { Banner, Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { Code } from "atoms/core/html-elements"; +import { ReactComponent as WindowConfiguration } from "assets/images/illustrations/window-configuration.svg"; +import { ROUTE_DOCS_PORTS_TMUX_INSTALLATION } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Configuration", + subline: "From UI elements to font rendering — configure the theme to match your personal preferences" +}; + + + + + + + + + + + + + +Nord tmux is designed to provide a good UX out-of-the-box, but there is a reason why principles like „themes“ exist at all: Everyone has different preferences and that's a good thing! + +To ensure Nord tmux fits your needs it comes with configurations for UI elements and font rendering to make the theme as flexible as possible while still providing sane defaults. + +All theme configuration variables must be added to either tmux's user-level, by default located in your [home directory][wiki-home_dir], or system-wide configuration file(s) that are referred to as `.tmux.conf` in this documentation. The location of the files and more details can be found in [tmux's `.tmux.conf` manual documentation][tmux-man-tmux.conf]. + + + All configuration variables should be set before tpm's @plugin{" "} + installation definition line! + + } +> + This ensures the configurations are applied correctly when the scheme file gets loaded, otherwise the theme might be + loaded without taking these configurations into account. + + +## UI Elements + +### Default Status Bar Content + +By default, this theme provides status bar content including patched „powerline“ styled characters like separator arrows. + +Screenshot showing the status bar with default content. + Default status bar content. + + +The status bar content can be disabled in order to use customized content by setting the `@nord_tmux_show_status_content` configuration variable in the `.tmux.conf` file: + +```sh +set -g @nord_tmux_show_status_content "0" +``` + +## Font Rendering + + + Disable specific font rendering theme configurations when facing rendering problems with incompatible terminals or + fonts! + + } + variant="warn" +> + Special font rendering styles like the usage of special characters (patched „powerline“ arrows) require support from + the side of the used terminal and font family in order to work properly. Please check if your used terminal and font + supports any of the theme styles in this section, otherwise there might be unexpected rendering issues or the + configuration won't have any effect at all. + + +### Patched Font Characters + +The provided default status bar content makes use of patched „powerline“ styled characters like the separator arrows for a more modern UI and fluidly merged appearance with other applications like the status bars of Vim or Emacs. + +Screenshot showing the tmux status bar with patched font elements + The status bar with patched font elements. + + +To disable the usage of patched „powerline“ styled font characters, using normal _Unicode_ characters instead that should be compatible with all terminals and fonts, set the `@nord_tmux_no_patched_font` configuration variable in your `.tmux.conf` file: + +```sh +set -g @nord_tmux_no_patched_font "1" +``` + +Screenshot showing the tmux status bar without patched font elements + The status bar without patched font elements. + + + + +[tmux-man-tmux.conf]: http://man.openbsd.org/OpenBSD-current/man1/tmux.1#FILES +[wiki-home_dir]: https://en.wikipedia.org/wiki/Home_directory diff --git a/content/docs/ports/tmux/configuration/ui-default-status-bar-content.png b/content/docs/ports/tmux/configuration/ui-default-status-bar-content.png new file mode 100644 index 00000000..3396a9f3 Binary files /dev/null and b/content/docs/ports/tmux/configuration/ui-default-status-bar-content.png differ diff --git a/content/docs/ports/tmux/installation/github-clone.png b/content/docs/ports/tmux/installation/github-clone.png new file mode 100644 index 00000000..a603447a Binary files /dev/null and b/content/docs/ports/tmux/installation/github-clone.png differ diff --git a/content/docs/ports/tmux/installation/index.mdx b/content/docs/ports/tmux/installation/index.mdx new file mode 100644 index 00000000..35c3743d --- /dev/null +++ b/content/docs/ports/tmux/installation/index.mdx @@ -0,0 +1,114 @@ +import Link from "atoms/core/Link"; +import { Banner, Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { Code, Kbd } from "atoms/core/html-elements"; +import { ReactComponent as WindowCode } from "assets/images/illustrations/window-code.svg"; +import { ROUTE_DOCS_COLOR_AND_PALETTES, ROUTE_PORTS } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Installation & Activation", + subline: "Get up and running in a few lines of code with your favorite plugin manager or manual setup" +}; + + + + + + + + + + + + + + + tmux must be used with a Nord terminal emulator theme in order to work properly! + + } +> + Make sure to install one of the currently supported terminal emulator port projects before installing Nord tmux. + +tmux in terminal mode uses the 16 color codes provided by the terminal emulator. +**When used with another color theme** than the one provided by one of Nord's terminal emulator ports, the colors in tmux won't use the Nord color palettes! +This will result in different styles than those defined by Nord tmux and could make it appear that there is a problem with the Nord tmux theme while the actual problem are missing Nord colors. + +Read the GitHub Gist about [terminal colors][gh-gist-terminal-colors] for more information about terminal color specifications. + + + +Thanks to existing plugin managers for tmux, Nord tmux can be installed for all platforms in a uniform way within a few lines of codes. The recommended manager is [tpm][gh-tmux-plugins/tpm], but any other manager like [tundle][gh-javier-lopez/tundle] can also be used. + +To automatically download and activate Nord tmux, follow the install instructions for [tpm][gh-tmux-plugins/tpm] and + +1. add `set -g @plugin "arcticicestudio/nord-tmux"` to your [`tmux.conf`][tmux-man-tmux.conf], by default `.tmux.conf` located in your [home directory][wiki-home_dir] +2. press the default key binding `prefix` + I to fetch- and install the plugin + +Also see [_tpm's_ install instructions][gh-tpm-docs-install-plugins] for more details. + +Screenshot showing a minimal tmux.conf with installed Nord color scheme + + Minimal tmux.conf with installed Nord color scheme. + + + +By default, the [latest version][repo-rel-latest] will be installed. To use the [latest development state from the `develop` branch][repo-br-develop] instead, go to the installation path of Nord tmux and switch to the `develop` branch or [any other version tag][repo-tags] you like. + +###### Manual + +To install Nord tmux manually **using Git**, + +1. [clone the repository][repo] into any location, e.g. `~/.tmux/themes/nord-tmux` +2. source the downloaded theme by adding the path of the [`nord.tmux`][repo-tree-master-nord.tmux] file to the bottom of your `.tmux.conf`, located in your [home directory][wiki-home_dir]: + ```sh + run-shell "~/.tmux/themes/nord-tmux/nord.tmux" + ``` +3. reload your `.tmux.conf` file to source- and activate the theme: + ```sh + tmux source-file ~/.tmux.conf + ``` + +Screenshot showing the GitHub repository web UI to download the project repository + +To install the theme **without Git**, + +1. [download the latest version][repo-down-master] of the repository +2. extract the downloaded archive into any location, e.g. `~/.tmux/themes/nord-tmux` +3. copy the [`nord.tmux`][repo-tree-master-nord.tmux], [`nord-status-content.conf`][repo-tree-master-status-content.conf] and [`nord-status-content-no-patched-font.conf`][repo-tree-master-no-patched-font.conf] files to any location +4. source the downloaded theme by adding the path of the [`nord.tmux`][repo-tree-master-nord.tmux] file to the bottom of your `.tmux.conf`, located in your [home directory][wiki-home_dir]: + ```sh + run-shell "~/.tmux/themes/nord-tmux/nord.tmux" + ``` +5. reload your `.tmux.conf` file to source- and activate the theme: + ```sh + tmux source-file ~/.tmux.conf + ``` + + + +[gh-gist-terminal-colors]: https://gist.github.com/XVilka/8346728 +[gh-javier-lopez/tundle]: https://github.com/javier-lopez/tundle +[gh-tmux-plugins/tpm]: https://github.com/tmux-plugins/tpm +[gh-tpm-docs-install-plugins]: https://github.com/tmux-plugins/tpm#installing-plugins +[repo-br-develop]: https://github.com/arcticicestudio/nord-tmux/tree/develop +[repo-down-master]: https://github.com/arcticicestudio/nord-tmux/archive/master.zip +[repo-rel-latest]: https://github.com/arcticicestudio/nord-tmux/releases/latest +[repo-tags]: https://github.com/arcticicestudio/nord-tmux/tags +[repo-tree-master-no-patched-font.conf]: https://github.com/arcticicestudio/nord-tmux/blob/master/src/nord-status-content-no-patched-font.conf +[repo-tree-master-nord.tmux]: https://github.com/arcticicestudio/nord-tmux/blob/master/nord.tmux +[repo-tree-master-status-content.conf]: https://github.com/arcticicestudio/nord-tmux/blob/master/src/nord-status-content.conf +[repo]: https://github.com/arcticicestudio/nord-tmux +[tmux-man-tmux.conf]: http://man.openbsd.org/OpenBSD-current/man1/tmux.1#FILES +[wiki-home_dir]: https://en.wikipedia.org/wiki/Home_directory diff --git a/content/docs/ports/tmux/installation/tpm.png b/content/docs/ports/tmux/installation/tpm.png new file mode 100644 index 00000000..64b012d4 Binary files /dev/null and b/content/docs/ports/tmux/installation/tpm.png differ diff --git a/content/docs/ports/tmux/plugin-support/index.mdx b/content/docs/ports/tmux/plugin-support/index.mdx new file mode 100644 index 00000000..a2570775 --- /dev/null +++ b/content/docs/ports/tmux/plugin-support/index.mdx @@ -0,0 +1,59 @@ +import Link from "atoms/core/Link"; +import { Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { ReactComponent as Plugin } from "assets/images/illustrations/plugin.svg"; +import { ROUTE_DOCS_PORTS_TMUX_CONFIGURATION } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Plugin Support", + subline: "Use your favorite plugins with a fluid and unobtrusive user interface transition." +}; + + + + + + + + + + + + + +The theme comes with styles for popular [official][gh-tmux-plugins]- and third-party UI plugins allowing a unobtrusive and visually matching integration. + +## tmux-prefix-highlight + +[tmux-prefix-highlight][gh-tmux-plugins/tmux-prefix-highlight] highlights when pressing the tmux prefix key that allows to quickly see the current usage mode. +Nord tmux supports the _prefix_ and _copy-mode_ status indicator. + +Screenshot showing the status bar with multiple tmux-prefix-highlight mode indicators. + + The status bar with multiple tmux-prefix-highlight mode indicators. + + + +The plugin is also supported when using Nord tmux without patched font characters. + +Screenshot showing the status bar with disabled patched font characters and multiple tmux-prefix-highlight mode indicators. + + The status bar with disabled patched font characters and multiple tmux-prefix-highlight mode indicators. + + + + + +[gh-tmux-plugins]: https://github.com/tmux-plugins +[gh-tmux-plugins/tmux-prefix-highlight]: https://github.com/tmux-plugins/tmux-prefix-highlight diff --git a/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight-no-patched-font.png b/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight-no-patched-font.png new file mode 100644 index 00000000..8e4923c1 Binary files /dev/null and b/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight-no-patched-font.png differ diff --git a/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight.png b/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight.png new file mode 100644 index 00000000..0572d84b Binary files /dev/null and b/content/docs/ports/tmux/plugin-support/tmux-prefix-highlight.png differ