From 3adf71550cce7c5ef8c135036ecb3f9514703a85 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Sat, 2 Apr 2022 14:42:13 +0200
Subject: [PATCH] Documentation

---
 docs/setup/changing-the-logo-and-icons.md | 25 ++++++++++++++++++-
 docs/setup/setting-up-site-analytics.md   | 29 ++++++++++++++++-------
 2 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md
index a6eedbc6b..70ca36fa6 100644
--- a/docs/setup/changing-the-logo-and-icons.md
+++ b/docs/setup/changing-the-logo-and-icons.md
@@ -108,8 +108,31 @@ markdown_extensions:
           - overrides/.icons
 ```
 
-You can now use all :fontawesome-brands-bootstrap: Bootstrap icons.
+You can now use all :fontawesome-brands-bootstrap: Bootstrap icons anywhere in
+Markdown files, as well as everywhere icons can be used in `mkdocs.yml`.
+However, note that the syntaxes are slightly different:
+
+- __Using icons in configuration__: take the path of the `*.svg` icon file
+  starting at the `.icons` folder and drop the file extension, e.g. for
+  `.icons/bootstrap/envelope-paper.svg`, use:
+
+    ``` yaml
+    theme:
+      icon:
+        logo: bootstrap/enveloper-paper
+    ```
+
+- __Using icons in Markdown files__: additionally to taking the path from the
+  `.icons` folder as noted above, replace all `/` with `-` and enclose the icon
+  shortcode in two colons:
+
+    ```
+    :bootstrap-enveloper-paper:
+    ```
+
+For further notes on icon usage, please consult the [icon reference].
 
   [extend the theme]: ../customization.md#extending-the-theme
   [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
   [Bootstrap]: https://icons.getbootstrap.com/
+  [icon reference]: ../reference/icons-emojis.md#using-icons
diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md
index faa55dda3..fe34840a3 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -121,20 +121,31 @@ integrated with the [cookie consent] feature[^1].
 
     === ":material-google-analytics: Google Analytics 4"
 
-        1. Go to your Google Analytics __dashboard__
-        2. Go to the __Configure__ page on the left hand menu, then select __Custom Definitions__
-        3. Click the __Custom metrics__ tab and then __Create custom metrics__, enter the following values:
+        1.  Go to your Google Analytics __dashboard__
+
+        2.  Go to the __configure__ page on the left hand menu, then select
+            __custom definitions__
+
+        3.  Click the __custom metrics__ tab and then __create custom metrics__, 
+            enter the following values:
+
             * Metric name: Page helpful
             * Description: Was this page helpful?
-            * Event parameter: data
+            * Event parameter: `data`
             * Unit of measurement: Standard
-        4. Go to the __Explore__ page on the left hand menu, create a new __blank exploration__
-        5. Configure the report as follows:
+
+        4.  Go to the __explore__ page on the left hand menu, create a new
+            __blank exploration__
+
+        5.  Configure the report as follows:
+
             * Dimensions: Add `Event name` and `Page location`
-            * Metrics: Add `Event count` and `Page helpful` (the custom metric created in step 3)
+            * Metrics: Add `Event count` and `Page helpful`
+              (the custom metric created in step 3)
             * Rows: `Page location`
-            * Values: `Page helpful`
-            * Filters: Add a new filter for `Event name / exactly matches / feedback`
+            * Values: Drag in both `Event count` and `Page helpful`
+            * Filters: Add a new filter for 
+              `Event name / exactly matches / feedback`
 
         !!! warning "Delay in data availability"