chore: normalize default favicons and add docs (#96)

.dictionary

@@ -31,3 +31,5 @@ prebuilt
 (S|s)ubdirector(ies|y)
 (M|m)inify
 whitespace
+Theming
+Favicon[s]?

exampleSite/content/posts/features/theming.md

@@ -0,0 +1,53 @@
+---
+title: Theming
+date: 2021-05-23T20:00:00+01:00
+authors:
+  - john-doe
+tags:
+  - Documentation
+  - Features
+---
+
+Personalize the look of your site.
+
+<!--more-->
+
+{{< toc >}}
+
+## Favicons
+
+The Theme is shipped with a set of default Favicons in various formats generated by a [Favicon Generator](https://realfavicongenerator.net/). All files can be found in the `static/favicon` folder of the release tarball. To make the replacement of the default Favicons as simple as possible, the theme loads only a very small subset of the Favicon formats.
+
+<!-- prettier-ignore -->
+```tpl
+<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
+<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">
+```
+
+### Simple replacement
+
+The minimal steps to load a custom Favicon is to overwrite tree default Favicon files. Therefor place these files into your projects root folder:
+
+- `static/favicon/favicon.svg`
+- `static/favicon/favicon-32x32.png`
+- `static/favicon/favicon-16x16.png`
+
+### Full replacement
+
+If you want to add more Favicon formats you have to [overwrite](https://gohugo.io/templates/partials/#partial-template-lookup-order) the default partial that is used to load the files. In the next step you have to place the required files in the `static` folder of your project as well.
+
+**Example:**
+
+<!-- prettier-ignore -->
+```tpl
+<!-- layouts/partials/head/favicons.html -->
+<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
+<link rel="apple-touch-icon" sizes="180x180" href="{{ "favicon/apple-touch-icon.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
+<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">
+<link rel="manifest" href="{{ "favicon/site.webmanifest" | relURL }}">
+<link rel="mask-icon" href="{{ "favicon/safari-pinned-tab.svg" | relURL }}" color="#2f333e">
+<meta name="msapplication-TileColor" content="#2f333e">
+<meta name="theme-color" content="#2f333e">
+```

exampleSite/content/posts/usage/getting-started.md

@@ -250,6 +250,7 @@ There are a lot more things to discover. To get the most out of the Theme we hav
 - [Menus](/posts/usage/menus/)
 - **Features**
   - [Icon Sets](/posts/features/icon-sets/)
+  - [Theming](/posts/features/theming/)
   - [Authors](/posts/features/authors/)
   - [Sticky Posts](/posts/features/sticky/)
 - [Shortcodes](/posts/advanced/shortcodes/)

gulpfile.js

@@ -49,6 +49,13 @@ gulp.task("sass", function () {
     .pipe(gulp.dest(CSS_BUILD));
 });
 
+gulp.task("favicon-svg", function () {
+  return gulp
+    .src("src/favicon/favicon-master.svg")
+    .pipe(rename("favicon.svg"))
+    .pipe(gulp.dest("static/favicon/"));
+});
+
 gulp.task("favicon-generate", function (done) {
   realFavicon.generateFavicon(
     {
@@ -272,6 +279,8 @@ gulp.task("clean", function () {
 
 gulp.task("asset", gulp.series("asset-sync", "asset-rev"));
 
+gulp.task("favicon", gulp.series("favicon-svg", "favicon-generate"));
+
 gulp.task("svg", gulp.series("svg-sprite", devBuild ? "svg-sprite-list" : []));
 
 gulp.task(
@@ -284,7 +293,7 @@ gulp.task(
     devBuild ? "asset-map" : [],
     "svg",
     "iconfont",
-    "favicon-generate",
+    "favicon",
   ])
 );
 

layouts/partials/head/favicons.html

@@ -1,3 +1,3 @@
-<link rel="apple-touch-icon" sizes="180x180" href="{{ "favicon/apple-touch-icon.png" | relURL }}">
+<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
 <link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
 <link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">