Transition: Nord Emacs (#158)

Transition: Nord Emacs

content/docs/ports/emacs/configuration/index.mdx

@@ -0,0 +1,130 @@
+import Link from "atoms/core/Link";
+import { Banner, Image, ShrinkedWidth, SpaceBox, Video } 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_COLOR_AND_PALETTES, ROUTE_DOCS_PORTS_EMACS_INSTALLATION } from "config/routes/mappings";
+
+import WIPNotice from "../../../../shared/docs/wip-notice";
+
+export const frontmatter = {
+  title: "Configuration",
+  subline: "From UI elements to syntax highlighting — configure the theme to match your personal preferences"
+};
+
+<ShrinkedWidth value={25}>
+
+<SpaceBox mTop={4} mBottom={4}>
+  <WindowConfiguration />
+</SpaceBox>
+
+</ShrinkedWidth>
+
+<ShrinkedWidth value={80}>
+
+<WIPNotice />
+
+Nord Emacs is designed to provide a good UX out-of-the-box, but there is a reason why principles like _themes_ exist a all: Everyone has different preferences and that's a good thing!
+
+To ensure Nord Emacs fit your needs it comes with configurations for UI elements and the code syntax highlighting to make the theme as flexible as possible while still providing sane defaults.
+
+All theme configuration variables must be loaded by your [init file][emacs-man-init_file] that are referred to as `init.el` in this documentation. The location of the file and more details can be found in [Emacs official documentation][emacs-man-init_file].
+
+<Banner
+  title={
+    <>
+      All configuration variables must be set <strong>before</strong> the <Code>load-theme</Code>{" "}
+      <Link to={`${ROUTE_DOCS_PORTS_VIM_INSTALLATION}#activation`}>activation</Link> command!
+    </>
+  }
+>
+  This ensures the configurations are applied correctly when the theme file gets loaded, otherwise it will be loaded
+  without taking these configurations into account.
+</Banner>
+
+## UI Elements
+
+### Uniform Mode Lines
+
+Enables uniform activate- and inactive mode lines using nord3 as background.
+
+By default, only the mode line of the active buffer uses `nord3` as background color while inactive buffers are dimmed using `nord1`.
+
+<Image
+  alt="Screenshot showing Emacs with default mode lines styles"
+  fluid={props.images["uniform-mode-lines-disabled.png"]}
+  dropShadow
+  rounded
+>
+  <span>Default mode lines style.</span>
+</Image>
+
+This can be changed to use `nord3` as background color highlighting for both active and inactive mode lines by enabling the theme configuration variable `nord-uniform-mode-lines`:
+
+```lisp
+(setq nord-uniform-mode-lines t)
+```
+
+<Image
+  alt="Screenshot showing Emacs with enabled uniform mode lines style configuration"
+  fluid={props.images["uniform-mode-lines-enabled.png"]}
+  dropShadow
+  rounded
+>
+  <span>Emacs with enabled uniform mode lines style configuration.</span>
+</Image>
+
+## Syntax Highlighting
+
+### Region Highlight Style
+
+By default, Nord Emacs uses `nord2` as background color for selected text in the editor to provide a sane default style.
+
+<Video
+  dropShadow
+  loop
+  poster={props.images["editor-selection-highlight.mp4.png"]}
+  rounded
+  sources={[props.videos["editor-selection-highlight.mp4"]]}
+>
+  <span>Default editor code selection highlighting.</span>
+</Video>
+
+To use a more colorful highlighting for region selections, Nord Emacs provides the `nord-region-highlight` configuration that can be set to either `snowstorm` or `frost` to use `nord4` or `nord8` colors from Nord's <Link to={`${ROUTE_DOCS_COLOR_AND_PALETTES}#frost`}>Frost</Link> and <Link to={`${ROUTE_DOCS_COLOR_AND_PALETTES}#snow-storm`}>Snow Storm</Link> palettes.
+
+```lisp
+;; Use `nord8` from Nord's "Frost" palette as background color.
+(setq nord-region-highlight "frost")
+
+;; Use `nord4` from Nord's "Snow Storm" palette as background color.
+(setq nord-region-highlight "snowstorm")
+```
+
+<Video
+  dropShadow
+  loop
+  poster={props.images["editor-selection-highlight-frost.mp4.png"]}
+  rounded
+  sources={[props.videos["editor-selection-highlight-frost.mp4"]]}
+>
+  <span>
+    Selection in the editor with enabled <Code>frost</Code> <em>region highlight style</em> configuration.
+  </span>
+</Video>
+
+<Video
+  dropShadow
+  loop
+  poster={props.images["editor-selection-highlight-snowstorm.mp4.png"]}
+  rounded
+  sources={[props.videos["editor-selection-highlight-snowstorm.mp4"]]}
+>
+  <span>
+    Selection in the editor with enabled <Code>snowstorm</Code> <em>region highlight style</em> configuration.
+  </span>
+</Video>
+
+The foreground color is <Link to={`${ROUTE_DOCS_COLOR_AND_PALETTES}#snow-storm`}><Code>nord0</Code></Link> for both options.
+
+</ShrinkedWidth>
+
+[emacs-man-init_file]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html

content/docs/ports/emacs/installation/index.mdx

@@ -0,0 +1,106 @@
+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 with one command through the builtin package manager or manual setup"
+};
+
+<ShrinkedWidth value={25}>
+
+<SpaceBox mTop={4} mBottom={4}>
+  <WindowCode />
+</SpaceBox>
+
+</ShrinkedWidth>
+
+<ShrinkedWidth value={80}>
+
+<WIPNotice />
+
+<Banner
+  title={
+    <>
+      Emacs in terminal mode <strong>must</strong> be used with a <Link to={ROUTE_PORTS}>Nord terminal emulator theme</Link> in order to work properly!
+    </>
+  }
+>
+  Make sure to install one of the currently supported <Link to={ROUTE_PORTS}>terminal emulator port projects</Link> <strong>before</strong> installing Nord Emacs.
+
+Emacs in terminal mode uses the 16 color codes provided by the terminal emulator.
+**When used with another color theme** than one of Nord's terminal emulator ports, Emacs won't use the color of <Link to={ROUTE_DOCS_COLOR_AND_PALETTES}>Nord's color palettes</Link>!
+This will result in different styles than those defined by Nord Emacs making it appear that there is a problem with Nord Emacs while the actual problem are missing Nord terminal color definitions.
+
+Read the GitHub Gist about [terminal colors][gh-gist-terminal-colors] for more information about terminal color specifications.
+
+</Banner>
+
+## Installation
+
+Thanks to the builtin Emacs package manager, Nord Emacs can be installed for all platforms and the various variants/forks of Emacs in a uniform way with one command.
+
+To install or update Nord Emacs
+
+1. press <Kbd>M-x</Kbd>
+2. run the `package-install` command
+3. type `nord-theme` and confirm with <Kbd>↲</Kbd>
+
+<Image
+  alt="Screenshot showing Emacs package listing and installation command to setup and update Nord through the builtin package manager"
+  dropShadow
+  fluid={props.images["package-manager.png"]}
+  rounded
+>
+  <span>
+    Emacs package listing and installation command to setup and update Nord through the builtin package manager.
+  </span>
+</Image>
+
+See Emacs [official package install documentations][emacs-man-pack_inst] for more details how to use the builtin package management.
+
+###### Manual
+
+To install Nord Emacs manually, [download the latest version][repo-down-master] or [clone the repository][repo].
+Afterwards copy the [`nord-theme.el`][repo-tree-master-nord-theme.el] file into the [`.emacs.d/themes` folder][emacs-man-custom_themes] located in your [home directory][wiki-home_dir].
+
+<Image
+  alt="Screenshot showing the GitHub repository web UI to download the project repository"
+  fillSize={60}
+  fluid={props.images["github-clone.png"]}
+/>
+
+## Activation
+
+Make sure the [`~/.emacs.d/themes` directory][emacs-man-custom_themes] has been added to Emacs _load path_ by adding it to the list in your [init file][emacs-man-init_file] (`.init.el`):
+
+```lisp
+(add-to-list 'custom-theme-load-path (expand-file-name "~/.emacs.d/themes/"))
+```
+
+To activate and use Nord Emacs as your default color theme load it in your init file:
+
+```lisp
+(load-theme 'nord t)
+```
+
+To switch to the theme on-the-fly
+
+1. press <Kbd>M-x</Kbd>
+2. run the `load-theme` command
+3. type `nord` and confirm with <Kbd>↲</Kbd>
+
+</ShrinkedWidth>
+
+[emacs-man-custom_themes]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Custom-Themes.html
+[emacs-man-init_file]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html
+[emacs-man-pack_inst]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html#Package-Installation
+[gh-gist-terminal-colors]: https://gist.github.com/XVilka/8346728
+[repo-down-master]: https://github.com/arcticicestudio/nord-emacs/archive/master.zip
+[repo-tree-master-nord-theme.el]: https://github.com/arcticicestudio/nord-emacs/blob/master/nord-theme.el
+[repo]: https://github.com/arcticicestudio/nord-emacs
+[wiki-home_dir]: https://en.wikipedia.org/wiki/Home_directory

src/components/organisms/page/docs/ports/emacs/SectionContents/SectionContents.jsx

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <development@arcticicestudio.com>
+ * Copyright (C) 2018-present Sven Greb <development@svengreb.de>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+import React from "react";
+
+import { WaveFooter } from "atoms/core/vectors/divider";
+import Section, { Content } from "containers/core/Section";
+import { BookOpen, Zap } from "atoms/core/vectors/icons";
+import { ROUTE_DOCS_PORTS_EMACS } from "config/routes/mappings";
+import { topicsGettingStarted, topicsReferences } from "data/components/organisms/page/docs/ports/emacs/topics";
+import { sectionIdFor } from "utils";
+import { colors } from "styles/theme";
+
+import { ContentsCard, CardGrid } from "../../../shared";
+
+const SECTION_ID = sectionIdFor(ROUTE_DOCS_PORTS_EMACS, 1);
+
+/**
+ * The component that represents the contents section of the docs page for the "Nord Emacs" port project.
+ *
+ * @author Arctic Ice Studio <development@arcticicestudio.com>
+ * @author Sven Greb <development@svengreb.de>
+ * @since 0.17.0
+ */
+const SectionContents = () => (
+  <Section id={SECTION_ID} variant="tertiary">
+    <Content centered>
+      <CardGrid>
+        <ContentsCard
+          accentColor={colors.nord8}
+          logoComponent={Zap}
+          svgType="stroke"
+          title="Getting Started"
+          topics={topicsGettingStarted}
+        >
+          Learn how to install, activate, configure and customize the theme.
+        </ContentsCard>
+        <ContentsCard accentColor={colors.nord10} logoComponent={BookOpen} title="References" topics={topicsReferences}>
+          Learn about supported languages, packages and how to deal with occurring problems.
+        </ContentsCard>
+      </CardGrid>
+    </Content>
+    <WaveFooter />
+  </Section>
+);
+
+export default SectionContents;

src/components/organisms/page/docs/ports/emacs/SectionContents/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <development@arcticicestudio.com>
+ * Copyright (C) 2018-present Sven Greb <development@svengreb.de>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+export { default } from "./SectionContents";

src/components/organisms/page/docs/ports/emacs/SectionHero/SectionHero.jsx

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <development@arcticicestudio.com>
+ * Copyright (C) 2018-present Sven Greb <development@svengreb.de>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+import React from "react";
+
+import Section, { Content } from "containers/core/Section";
+import { ROUTE_DOCS_PORTS_EMACS } from "config/routes/mappings";
+import { sectionIdFor } from "utils";
+
+import { Headline, Subline } from "../../../shared";
+
+const SECTION_ID = sectionIdFor(ROUTE_DOCS_PORTS_EMACS, 0);
+
+/**
+ * The component that represents the hero section of the docs page for the "Nord Emacs" port project.
+ *
+ * @author Arctic Ice Studio <development@arcticicestudio.com>
+ * @author Sven Greb <development@svengreb.de>
+ * @since 0.17.0
+ */
+const SectionHero = () => (
+  <Section id={SECTION_ID} variant="tertiary">
+    <Content centered>
+      <Headline>Nord Emacs</Headline>
+      <Subline>
+        Documentations to get to know the theme, supported features, how to use the package, customize it to fit your
+        needs and find solutions for possible problems.
+      </Subline>
+    </Content>
+  </Section>
+);
+
+export default SectionHero;

src/components/organisms/page/docs/ports/emacs/SectionHero/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <development@arcticicestudio.com>
+ * Copyright (C) 2018-present Sven Greb <development@svengreb.de>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+export { default } from "./SectionHero";

src/components/organisms/page/docs/ports/emacs/index.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <development@arcticicestudio.com>
+ * Copyright (C) 2018-present Sven Greb <development@svengreb.de>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+import SectionContents from "./SectionContents";
+import SectionHero from "./SectionHero";
+
+export { SectionContents, SectionHero };