Support Google Fonts Icons (#1681)

MarkBind does not support the inclusion of Google's Material icons
using the two-colon syntax (e.g., `:icon-name:`).

Users who want to use icons from that library would need to include
`link` HTML elements per MarkBind project and write lengthy `span` HTML
elements per icon, which can be inconvenient if done frequently.

Let's extend MarkBind's existing two-colon icon syntax to support
Google's Material icons.

Using the two-colon syntax would make the usage of Google's Material
icons much easier, as it does not require the users to manually use
HTML to include said icons.

docs/userGuide/syntax/icons.mbdf

@@ -1,6 +1,6 @@
 ## Icons
 
-<small>%%Acknowledgement: Font Awesome icons are provided by [Font Awesome](https://fontawesome.com/) under their [free license](https://fontawesome.com/license), Glyphicons are provided by [Glyphicons](https://glyphicons.com/) via [Bootstrap 3](https://getbootstrap.com/docs/3.3/), and [Octicons](https://octicons.github.com) are copyright of GitHub.%%</small>
+<small>%%Acknowledgement: Font Awesome icons are provided by [Font Awesome](https://fontawesome.com/) under their [free license](https://fontawesome.com/license), Glyphicons are provided by [Glyphicons](https://glyphicons.com/) via [Bootstrap 3](https://getbootstrap.com/docs/3.3/), [Octicons](https://octicons.github.com) are copyright of GitHub, and Material icons are provided by [Google Fonts](https://fonts.google.com/icons) via [`material-icons` by Ravindra Marella](https://www.npmjs.com/package/material-icons) under the [Apache license 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).%%</small>
 
 MarkBind supports using Font Icons provided by Font Awesome, Glyphicons and GitHub's Octicons.
 
@@ -54,3 +54,17 @@ Please use the new `:prefix-name:` syntax instead.
   `Merge a **pull request** :octicon-git-pull-request:` → Merge a **pull request** :octicon-git-pull-request:
 1. You may also append `~class-name` to the end of the octicon name to add `class="class-name"` property to your Octicon (e.g. `:octicon-git-pull-request~icon-large-red:` will generate an Octicon of class *icon-large-red*). You may then add corresponding CSS to `{root}/_markbind/layouts/{layout-name}/styles.css` to customize the style of your Octicon.
 1. If your background is dark, you may use `:octiconlight-*:` to render the icon as white. 
+
+###### Using Material Icons
+
+1. Decide which icon you want to use from [list of available icons](https://fonts.google.com/icons).
+1. Construct the MarkBind name for the selected icon by writing the icon name in _lowercase letters only_, replacing any spaces between the words in the name with _dashes_ (`-`), then adding the _type prefix_.
+   Note: Google has five different styles for their Material icons, each with their own type prefix. Here is an example from each type:
+   * _Filled_ (prefix: `mif-`) e.g. :mif-perm-media: (actual name `Perm Media`, MarkBind name `mif-perm-media`)
+   * _Outlined_ (prefix: `mio-`) e.g., :mio-perm-media: (actual name `Perm Media`, MarkBind name `mio-perm-media`)
+   * _Rounded_ (prefix: `mir-`): e.g., :mir-perm-media: (actual name `Perm Media`, MarkBind name `mir-perm-media`)
+   * _Sharp_ (prefix: `mis-`): e.g., :mis-perm-media: (actual name `Perm Media`, MarkBind name `mis-perm-media`)
+   * _Two tone_ (prefix: `mit-`): e.g., :mit-perm-media: (actual name `Perm Media`, MarkBind name `mit-perm-media`)
+
+1. Insert the name for the icon enclosed within colons to get the icon in your page.<br>
+  `Download from Cloud :mio-cloud-download:` → Download from Cloud :mio-cloud-download:

packages/cli/test/functional/test_site/expected/bugs/index.html

@@ -16,6 +16,7 @@
   <link rel="stylesheet" href="../markbind/fontawesome/css/all.min.css">
   <link rel="stylesheet" href="../markbind/glyphicons/css/bootstrap-glyphicons.min.css">
   <link rel="stylesheet" href="../markbind/css/octicons.css">
+  <link rel="stylesheet" href="../markbind/material-icons/material-icons.css">
   <link rel="stylesheet" href="../markbind/css/codeblock-dark.min.css">
   <link rel="stylesheet" href="../markbind/css/markbind.min.css">
   <script src="../markbind/js/polyfill.min.js"></script>

packages/cli/test/functional/test_site/expected/index.html

@@ -16,6 +16,7 @@
   <link rel="stylesheet" href="markbind/fontawesome/css/all.min.css">
   <link rel="stylesheet" href="markbind/glyphicons/css/bootstrap-glyphicons.min.css">
   <link rel="stylesheet" href="markbind/css/octicons.css">
+  <link rel="stylesheet" href="markbind/material-icons/material-icons.css">
   <link rel="stylesheet" href="markbind/css/codeblock-dark.min.css">
   <link rel="stylesheet" href="markbind/css/markbind.min.css">
   <script src="markbind/js/polyfill.min.js"></script>

packages/cli/test/functional/test_site/expected/markbind/material-icons/_mixins.scss

@@ -0,0 +1,55 @@
+// @see https://github.com/twbs/bootstrap/blob/main/scss/_functions.scss
+@function material-icons-str-replace($string, $search, $replace: '') {
+  $index: str-index($string, $search);
+  @if $index {
+    @return str-slice($string, 1, $index - 1) + $replace +
+      material-icons-str-replace(
+        str-slice($string, $index + str-length($search)),
+        $search,
+        $replace
+      );
+  }
+  @return $string;
+}
+
+@mixin material-icons-font-class($font-family) {
+  font-family: $font-family;
+  font-weight: normal;
+  font-style: normal;
+  font-size: $material-icons-font-size;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  display: inline-block;
+  white-space: nowrap;
+  word-wrap: normal;
+  direction: ltr;
+  -webkit-font-smoothing: antialiased; // Support for all WebKit browsers
+  -moz-osx-font-smoothing: grayscale; // Support for Firefox
+  text-rendering: optimizeLegibility; // Support for Safari and Chrome
+  font-feature-settings: 'liga'; // Support for IE
+}
+
+@mixin material-icons-font($font-family) {
+  $class-name: to-lower-case($font-family);
+  $class-name: material-icons-str-replace($class-name, ' ', '-');
+  $font-file: $material-icons-font-path + $class-name;
+
+  @font-face {
+    font-family: $font-family;
+    font-style: normal;
+    font-weight: 400;
+    font-display: $material-icons-font-display;
+    src: url('#{$font-file}.woff2') format('woff2'),
+      url('#{$font-file}.woff') format('woff');
+  }
+
+  .#{$class-name} {
+    @include material-icons-font-class($font-family);
+  }
+}
+
+@mixin material-icons() {
+  @warn "material-icons() Sass mixin has been deprecated as of 1.0. Use '@extend .material-icons;' instead of '@include material-icons();'.";
+  @include material-icons-font-class('Material Icons');
+}

packages/cli/test/functional/test_site/expected/markbind/material-icons/_variables.scss

@@ -0,0 +1,3 @@
+$material-icons-font-path: './' !default;
+$material-icons-font-size: 24px !default;
+$material-icons-font-display: block !default;

packages/cli/test/functional/test_site/expected/markbind/material-icons/filled.css

@@ -0,0 +1,24 @@
+@font-face {
+  font-family: "Material Icons";
+  font-style: normal;
+  font-weight: 400;
+  font-display: block;
+  src: url("./material-icons.woff2") format("woff2"), url("./material-icons.woff") format("woff");
+}
+.material-icons {
+  font-family: "Material Icons";
+  font-weight: normal;
+  font-style: normal;
+  font-size: 24px;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  display: inline-block;
+  white-space: nowrap;
+  word-wrap: normal;
+  direction: ltr;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  font-feature-settings: "liga";
+}

packages/cli/test/functional/test_site/expected/markbind/material-icons/filled.scss

@@ -0,0 +1,4 @@
+@import 'variables';
+@import 'mixins';
+
+@include material-icons-font('Material Icons');