From 71ccb545c60220acbc4e9f374630c26fb86f887f Mon Sep 17 00:00:00 2001
From: George Kalpakas <kalpakas.g@gmail.com>
Date: Thu, 18 Feb 2021 18:42:48 +0200
Subject: [PATCH] refactor(docs-infra): create mixin for styling docs pages
 (#40881)

Previously, in order to apply some styles to docs (i.e. non-marketing)
pages, we listed the various `.folder-*` classes that corresponded to
docs pages. This meant that adding/removing a docs area required updates
in several places, which is error-prone.

This commit avoids this by using a Sass mixin for applying styles to
docs pages.

PR Close #40881
---
 aio/src/styles/0-base/_typography.scss  | 17 +++-----
 aio/src/styles/1-layouts/_top-menu.scss |  8 +---
 aio/src/styles/_mixins.scss             | 52 +++++++++++++++++++++++++
 3 files changed, 58 insertions(+), 19 deletions(-)

diff --git a/aio/src/styles/0-base/_typography.scss b/aio/src/styles/0-base/_typography.scss
index e9503a7cd2..2f0107bb5d 100755
--- a/aio/src/styles/0-base/_typography.scss
+++ b/aio/src/styles/0-base/_typography.scss
@@ -206,18 +206,11 @@ code {
   }
 }
 
-// The following css rule adds an icon to external links in the docs area.
-// The following `folder-*` classes are applied to the `doc-viewer`component when it is displaying docs for these areas of the documentation.
-// We add the icon to all external links which are identified as absolute links (those that start with `http` or https`).
-// For more info see PR #36601
-
-.folder-api,
-.folder-cli,
-.folder-docs,
-.folder-errors,
-.folder-guide,
-.folder-start,
-.folder-tutorial {
+// The following css rule adds an icon to external links in the docs area, based on the classes that are applied to the
+// `doc-viewer` component when it is displaying docs for the different areas of the documentation.
+// We add the icon to all external links which are identified as absolute links (those that start with `http:` or https:`).
+// For more info see PR #36601.
+@include docs-pages {
   aio-doc-viewer{
     a {
       &[href^="http:"]::after,
diff --git a/aio/src/styles/1-layouts/_top-menu.scss b/aio/src/styles/1-layouts/_top-menu.scss
index 8bfeb8b292..a41601e466 100644
--- a/aio/src/styles/1-layouts/_top-menu.scss
+++ b/aio/src/styles/1-layouts/_top-menu.scss
@@ -39,13 +39,7 @@ mat-toolbar.app-toolbar {
   }
 
   // DOCS PAGES OVERRIDE: HAMBURGER
-  aio-shell.folder-api &,
-  aio-shell.folder-cli &,
-  aio-shell.folder-docs &,
-  aio-shell.folder-guide &,
-  aio-shell.folder-errors &,
-  aio-shell.folder-start &,
-  aio-shell.folder-tutorial & {
+  @include docs-pages($nestParentSelector: true) {
     @media (min-width: $showTopMenuWidth) {
       .hamburger {
         // Hamburger shown on non-marketing pages even on large screens.
diff --git a/aio/src/styles/_mixins.scss b/aio/src/styles/_mixins.scss
index 1bfb279940..5a736390b1 100644
--- a/aio/src/styles/_mixins.scss
+++ b/aio/src/styles/_mixins.scss
@@ -125,3 +125,55 @@
     }
   }
 }
+
+/// Define some styles for docs (i.e. non-marketing) pages.
+///
+/// @example scss - Example SCSS:
+///   .foo {
+///     @include docs-pages {
+///       .bar {
+///         color: orange;
+///       }
+///     }
+///   }
+///
+///   .baz {
+///     @include docs-pages($nestParentSelector: true) {
+///       .qux {
+///         color: orange;
+///       }
+///     }
+///   }
+///
+/// @example css - Output CSS:
+///   .foo .folder-api .bar, .foo .folder-cli .bar, ... {
+///     color: orange;
+///   }
+///
+///   .folder-api .baz .qux, .folder-cli .baz .qux, ... {
+///     color: orange;
+///   }
+///
+/// @param {boolean} $nestParentSelector
+///   If true, the parent selector (`&`) is nested inside the docs pages selectors.
+@mixin docs-pages($nestParentSelector: false) {
+  $selectors: (
+    '.folder-api',
+    '.folder-cli',
+    '.folder-docs',
+    '.folder-errors',
+    '.folder-guide',
+    '.folder-start',
+    '.folder-tutorial',
+  );
+
+  @if $nestParentSelector and & {
+    @at-root #{selector-nest(#{$selectors}, &)} {
+      @content;
+    }
+  } @else {
+    #{$selectors} {
+      @content;
+    }
+  }
+}