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

@@ -206,18 +206,11 @@ code {
   }
 }
 
-// The following css rule adds an icon to external links in the docs area.
+// The following css rule adds an icon to external links in the docs area, based on the classes that are applied to the
-// The following `folder-*` classes are applied to the `doc-viewer`component when it is displaying docs for these areas of the documentation.
+// `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`).
+// 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
+// For more info see PR #36601.
-
+@include docs-pages {
-.folder-api,
-.folder-cli,
-.folder-docs,
-.folder-errors,
-.folder-guide,
-.folder-start,
-.folder-tutorial {
   aio-doc-viewer{
     a {
       &[href^="http:"]::after,

aio/src/styles/1-layouts/_top-menu.scss

@@ -39,13 +39,7 @@ mat-toolbar.app-toolbar {
   }
 
   // DOCS PAGES OVERRIDE: HAMBURGER
-  aio-shell.folder-api &,
+  @include docs-pages($nestParentSelector: true) {
-  aio-shell.folder-cli &,
-  aio-shell.folder-docs &,
-  aio-shell.folder-guide &,
-  aio-shell.folder-errors &,
-  aio-shell.folder-start &,
-  aio-shell.folder-tutorial & {
     @media (min-width: $showTopMenuWidth) {
       .hamburger {
         // Hamburger shown on non-marketing pages even on large screens.

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;
+    }
+  }
+}