diff --git a/content/docs/ports/dircolors/installation/github-clone.png b/content/docs/ports/dircolors/installation/github-clone.png new file mode 100644 index 00000000..a603447a Binary files /dev/null and b/content/docs/ports/dircolors/installation/github-clone.png differ diff --git a/content/docs/ports/dircolors/installation/index.mdx b/content/docs/ports/dircolors/installation/index.mdx new file mode 100644 index 00000000..3bc1abb8 --- /dev/null +++ b/content/docs/ports/dircolors/installation/index.mdx @@ -0,0 +1,86 @@ +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 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 one line of code for your favorite shell" +}; + + + + + + + + + + + + + + + The theme 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 dircolors. + +[`dircolors`][gnu-docs-dircolors] 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 for dircolors won't use Nord's color palettes! +This will result in different styles than those defined by Nord dircolors and could make it appear that there is a problem with the 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. + + + +## Installation + +Nord dircolors can be installed for all application that respect the `LS_COLORS` environment variable like GNU core utils [`ls`][wiki-ls], [`tree`][wiki-tree] or modern projects like [`fd`][gh-sharkdp/fd]. + +To automatically load Nord dircolors for every shell session, download the [`dir_colors`][gh-tree-dir_colors] file and place it as `~/.dir_colors` in your [home directory][wiki-home_dir]. + +### Latest Development State + +To always use the latest development state of Nord dircolors, [clone the repository][repo] and create a [symbolic link][wiki-symlink] of the `src/dir_colors` file to `~/.dir_colors` in your [home directory][wiki-home_dir] afterwards: + +```sh +ln -sr "$PWD/src/dir_colors" "~/.dir_colors" +``` + +## Activation + +To activate and use Nord dircolors as your default color theme for all sessions, load the theme with `dircolors` by adding the following snippet to the configuration file of your shell (`~/.bashrc`, `~/.zshrc`, …): + +```sh +test -r "~/.dir_colors" && eval $(dircolors ~/.dir_colors) +``` + +Screenshot showing an example of a shell configuration file to load Nord through dircolors + + Oneliner for a shell configuration to automatically load the theme. + + + + + +[gh-gist-terminal-colors]: https://gist.github.com/XVilka/8346728 +[gh-sharkdp/fd]: https://github.com/sharkdp/fd +[gh-tree-dir_colors]: https://github.com/arcticicestudio/nord-dircolors/blob/develop/src/dir_colors +[gnu-docs-dircolors]: https://www.gnu.org/software/coreutils/manual/html_node/dircolors-invocation.html +[repo]: https://github.com/arcticicestudio/nord-dircolors +[wiki-home_dir]: https://en.wikipedia.org/wiki/Home_directory +[wiki-ls]: https://en.wikipedia.org/wiki/Ls +[wiki-symlink]: https://en.wikipedia.org/wiki/Symbolic_link +[wiki-tree]: https://en.wikipedia.org/wiki/Tree_(command) diff --git a/content/docs/ports/dircolors/installation/shell-rc.png b/content/docs/ports/dircolors/installation/shell-rc.png new file mode 100644 index 00000000..d5ee3d33 Binary files /dev/null and b/content/docs/ports/dircolors/installation/shell-rc.png differ diff --git a/content/docs/ports/dircolors/type-support/blocks-and-sockets.png b/content/docs/ports/dircolors/type-support/blocks-and-sockets.png new file mode 100644 index 00000000..d051a573 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/blocks-and-sockets.png differ diff --git a/content/docs/ports/dircolors/type-support/capabilities.png b/content/docs/ports/dircolors/type-support/capabilities.png new file mode 100644 index 00000000..8bd023a7 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/capabilities.png differ diff --git a/content/docs/ports/dircolors/type-support/executables.png b/content/docs/ports/dircolors/type-support/executables.png new file mode 100644 index 00000000..e2cabea6 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/executables.png differ diff --git a/content/docs/ports/dircolors/type-support/extension-pattern-ignore.png b/content/docs/ports/dircolors/type-support/extension-pattern-ignore.png new file mode 100644 index 00000000..b5d42237 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/extension-pattern-ignore.png differ diff --git a/content/docs/ports/dircolors/type-support/extension-pattern-media.png b/content/docs/ports/dircolors/type-support/extension-pattern-media.png new file mode 100644 index 00000000..3c409b08 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/extension-pattern-media.png differ diff --git a/content/docs/ports/dircolors/type-support/index.mdx b/content/docs/ports/dircolors/type-support/index.mdx new file mode 100644 index 00000000..e747b0c8 --- /dev/null +++ b/content/docs/ports/dircolors/type-support/index.mdx @@ -0,0 +1,197 @@ +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 DataNodesSSD } from "assets/images/illustrations/data-nodes-ssd.svg"; +import { ROUTE_DOCS_PORTS_DIRCOLORS_INSTALLATION } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Type Support", + subline: + "Learn about the wide range of supported data and node types — From symbolic links, executables up to file system permissions." +}; + + + + + + + + + + + + + + + This theme is only compatible for GNU ls and will have no effect with commands from other distributions like BSD (macOS) or Slackware! + + } + variant="warn" +> + +[dircolors][gnu-docs-dircolors] is a utility that sets the `LS_COLORS` environment variable respected by [GNU `ls`][wiki-ls] when used with the `--color` option. It converts the _color database file_ provided by this theme (`dir_colors`), converts it into the parsable format for the GNU `ls` command and stores it in the `LS_COLOR` environment variable. + +Other distributions/platforms/operating systems like [macOS][wiki-macos] are based on [BSD][wiki-bsd] and using a different implementation of the `ls` command that uses a different format for color definitions stored in the `LSCOLOR` environment variable (no underscore). + +The `dircolors` utility only supports GNU `ls` and therefore this theme is also only compatible with the GNU `ls` command. It has no effect when used with different implementations. + +Please read the [manual pages of the `dircolors(1)` utility][linux-man-dircolors] and it's [configuration file `dir_colors(5)`][linux-man-dir_colors] for more information about supported terminal codes/sequences and platforms. + + + +Nord dircolors provides highlighting for a lot of different data types, their attributes and file system permissions. This document contains a general overview of these types including descriptions about their applied Nord styles. + +Screenshot showing an overview of various file and node types colorized by Nord + Overview of various file and node types colorized by Nord. + + +## Global Defaults + +The following styles are applied globally to essential data and node types as well as their file system permissions. + +### Permissions + +The styles are applied for files and directories with different [file system permissions][wiki-fs_perm]. + +Directories using `nord9` as foreground color and a `bold` font style. +If the `t` permission flag is set the background color is `nord9` instead while `nord4` is used as foreground color using the `underline` font style. Also if the `o+w` permission flags are set too the font uses the `bold` style instead. + +For directories with the `777` permission value both the `bold` and `underline` font styles are used. + +Screenshot showing directories with different file system permissions + + Directories with different{" "} + file system permissions. + + + +### Links + +The styles are applied for [symbolic][wiki-symlink] and [hard][wiki-hardlink] links using `nord8` as foreground color. Hard links additionally have a `underline` font style. + +The foreground color of invalid symbolic links are colored by `nord11` while non-existent link targets using `nord11` as background color and `nord4` foreground with `bold` font styles. + +Screenshot showing symbolic and hard links + + Different link types like symbolic and{" "} + hard links. + + + +### Executables + +The styles are applied for [executables][wiki-exec] using `nord7` as foreground color with a `bold` font style. + +Screenshot showing executable files + + Executables are recognizable at a glance. + + + +### Blocks and Sockets + +The styles are applied for [Unix file types][wiki-unix_ft] like [device files][wiki-dev_file] and [domain sockets][wiki-unix_sock]. + +Character device files are using `nord13` as foreground while block devices additionally having the `bold` font style. Sockets are also colored by `nord13` with a the `underline` font style. + +Screenshot showing various Unix file types + Various Unix file types like{" "} + device files and{" "} + domain sockets. + + +### Capabilities + +The styles are applied for files with different [capabilities][wiki-setuid]. + +The GID `g+s` and UID `u+s` capability flags are colored by `nord4` with the `bold` and `underline` font styles. + +Screenshot showing files with different capabilities + Capabilities are also styled to be more prominent. + + +### Named Pipe (FIFO) + +The styles are applied for [named pipe][wiki-named_pipe], also known as FIFO, using `nord7` as foreground color with the `underline` font style. + +Screenshot showing a named pipe also know as FIFO + A named pipe also know as FIFO. + + +## Extension Pattern + +The following styles are for files with specific file extensions. + +### Media + +Extension for media based types like images, audio, videos and documents are colored by `nord14` while archive- and compression types additionally using the `bold` font style. + +Screenshot showing file extensions for multimedia files + Common file extensions like multimedia files. + + +### Ignore Pattern + +Extensions for common [VCS][wiki-vcs] ignore pattern using the `dim` terminal effect applied to `nord4`. + +Screenshot showing ignore pattern files + Common VSC ignore pattern files. + + + + +[gnu-docs-dircolors]: https://www.gnu.org/software/coreutils/manual/html_node/dircolors-invocation.html +[linux-man-dir_colors]: https://linux.die.net/man/5/dir_colors +[linux-man-dircolors]: https://linux.die.net/man/1/dircolors +[wiki-bsd]: https://en.wikipedia.org/wiki/Berkeley_Software_Distribution +[wiki-ls]: https://en.wikipedia.org/wiki/Ls +[wiki-macos]: https://en.wikipedia.org/wiki/MacOS +[wiki-symlink]: https://en.wikipedia.org/wiki/Symbolic_link +[wiki-hardlink]: https://en.wikipedia.org/wiki/Hard_link +[wiki-fs_perm]: https://en.wikipedia.org/wiki/File_system_permissions +[wiki-exec]: https://en.wikipedia.org/wiki/Executable +[wiki-unix_ft]: https://en.wikipedia.org/wiki/Unix_file_types +[wiki-dev_file]: https://en.wikipedia.org/wiki/Device_file +[wiki-unix_sock]: https://en.wikipedia.org/wiki/Unix_domain_socket +[wiki-setuid]: https://en.wikipedia.org/wiki/Setuid +[wiki-named_pipe]: https://en.wikipedia.org/wiki/Named_pipe +[wiki-vcs]: https://en.wikipedia.org/wiki/Version_control diff --git a/content/docs/ports/dircolors/type-support/links.png b/content/docs/ports/dircolors/type-support/links.png new file mode 100644 index 00000000..e347f5a9 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/links.png differ diff --git a/content/docs/ports/dircolors/type-support/named_pipes.png b/content/docs/ports/dircolors/type-support/named_pipes.png new file mode 100644 index 00000000..a58659e9 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/named_pipes.png differ diff --git a/content/docs/ports/dircolors/type-support/overview.png b/content/docs/ports/dircolors/type-support/overview.png new file mode 100644 index 00000000..45c7a9f9 Binary files /dev/null and b/content/docs/ports/dircolors/type-support/overview.png differ diff --git a/content/docs/ports/dircolors/type-support/permissions.png b/content/docs/ports/dircolors/type-support/permissions.png new file mode 100644 index 00000000..44f7f9ca Binary files /dev/null and b/content/docs/ports/dircolors/type-support/permissions.png differ diff --git a/src/assets/images/illustrations/data-nodes-ssd.svg b/src/assets/images/illustrations/data-nodes-ssd.svg new file mode 100755 index 00000000..e0658ade --- /dev/null +++ b/src/assets/images/illustrations/data-nodes-ssd.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + +