+blog tutorial engagement part

Author: alexvoss

docs/tutorials/blogs/engage.md

@@ -194,10 +194,17 @@ feedback, learning something, as well as giving readers the opportunity to
 discuss the content and the topic it is about.
 
 There are plenty of discussion system out there and you will need to consider
-your audience when choosing one appropriate for your blog. In this tutorial,
-we will be using [Giscus] because it is free, open source, and uses [GitHub
-Discussions] as a backend. Because a lot of users of Material for MkDocs use
-GitHub, this seems like an obvious choice.
+your audience when choosing one appropriate for your blog. Likewise, you will
+also need to consider existing commitments to communication channels. If you
+are a heavy user Slack, for example, you may have a string preference for this
+system. Consider that when you add a communication channel, you will need to
+be prepared to use it regularly and to moderate discussions.
+
+### Giscus integration
+
+In this tutorial, we will be using [Giscus] because it is free, open source,
+and uses [GitHub Discussions] as a backend. Because a lot of users of Material
+for MkDocs use GitHub, this seems like an obvious choice.
 
 [Giscus]: https://giscus.app/
 [GitHub Discussions]: https://docs.github.com/en/discussions
@@ -209,30 +216,30 @@ To add Giscuss to your blog you will need to go through a number of steps:
 3. Configure the code needed to embed Giscus into your blog
 4. Add the code to your MkDocs project
 
-!!! example "Create a GitHub repository"
+[Giscus app]: https://github.com/apps/giscus
 
-    You may want to create a test repository for this tutorial that you an
-    scap later on. The instructions below assume that you are user "example"
-    and that you create a repository "giscus-test". The repository will need
-    to be public for people to be able to use the discussions.
+You may want to create a test repository for this tutorial that you can
+scrap later on. The instructions below assume that you are user "example"
+and that you create a repository "giscus-test." The repository will need
+to be public for people to be able to use the discussions.
 
-    In the instructions given, you will need to replace at least the username
-    but also the repository name if you chose another name such as when you
-    want to work directly on an existing repository.
+In the instructions given below, you will need to replace at least the username
+but also the repository name if you chose another name such as when you
+want to work directly on an existing repository.
 
 !!! example "Turn on discussions and install the Giscus app"
 
-    Once the repository is set up, go to its settings page and find the
-    `Features` section. Tick the checkbox for `Discussions`. You will see that
-    `Discussions` appears in the top navigation for the repository. If you
-    are using a live repository then you may want to add some minimal content
-    to the dicussions section at this point and come back to the tutorial.
+    Once the repository is set up, go to its settings page and find
+    `Features` in the `General` section. Tick the checkbox for `Discussions`.
+    You will see that `Discussions` appears in the top navigation for the
+    repository. If you are using a live repository then you may want to add some
+    minimal content to the dicussions section at this point and come back to the
+    tutorial.
 
-    Next, you need to [install the Giscus app] by following the link in this
+    Next, you need to install the [Giscus app] by following the link in this
     sentence, and choosing `Install`, then following the instructions to choose
     where the Giscus app is to be installed:
 
-
     1. Choose the account or organization for the repository you want to use.
     2. Choose to install only on select repositories and select the one you
        want to use. Note that you can choose more than one repository here.
@@ -241,43 +248,109 @@ To add Giscuss to your blog you will need to go through a number of steps:
     4. You will end up on the `Applications` page in your settings, where you
        can control the Gicsus app and uninstall it if so desired.
 
+That is all the preparation you will need for the repository. Next, it is time
+to generate a piece of code that embeds Giscuss in your site. The resulting code
+snippet will look something like this:
+
+```html
+<script
+    src="https://giscus.app/client.js"
+    data-repo="<username>/<repository>"
+    data-repo-id="..."
+    data-category="..."
+    data-category-id="..."
+    data-mapping="pathname"
+    data-reactions-enabled="1"
+    data-emit-metadata="1"
+    data-theme="preferred_color_scheme"
+    data-lang="en"
+    crossorigin="anonymous"
+    async
+>
+</script>
+```
+
 !!! example "Configure the code needed to embed Giscus into your blog"
 
-    Now it is time to go back to the [Giscus homepage] and configure the
-    embedding code. There are a number of settings:
+    Go to the [Giscus homepage] and configure the embedding code. There are a
+    number of settings:
 
     1. Choose the language
     2. Enter the username / organization name and repository name
     3. Choose how the discussions are to be mapped to the page on your blog.
        Because for a blog post the title is the basis of the URL, it makes
        sense to use the `Discussion title contains page <title>` option.
     4. Under `Discussion Category` choose `Announcements` to limit the creation
-       of new
-
+       of new discussions to Giscuss and people with maintainer or admin
+       permissions.
     5. Under `Features`, select the following:
-       1. Enable reactions for the main post
-       2. Emit discussion metadata
-       3.
+         1. Enable reactions for the main post
+         2. Emit discussion metadata
+         3. Place the comment box above the comments
+    6. Under `Theme`, select `Preferred color scheme` so that Giscus matches
+       the color scheme selected by the user for your site.
+
+[Giscus homepage]: https://giscus.app/
 
+With these settings in place, you now need to integrate the code into your
+site. There is a partial `partials/comments.html` that exists for this purpose
+and is empty be default. It is included by the `content.html` partial, so will
+be included for every page on your site. You may or may not want this. In this
+tutorial, you will limit the Giscus integration to only blog posts but it is
+easy enough to leave out the code that achieves this if you want to have Giscus
+discussions active for every page.
+
+!!! example "Add Giscus integration code"
+
+    First, you need to create an `overrides` directory that will contain the
+    templates and partials you want to override.
+
+    ```
+    mkdir -p overrides/partials
+    ```
 
-    The resulting code snippet should look like this:
+    You need to declare it in your `mkdocs.yaml`:
+
+    ```yaml hl_lines="3"
+    theme:
+      name: material
+      custom_dir: overrides
+    ```
+
+    Now add a file `overrides/partials/comments.html` and paste in the code
+    snippet you obtained from the Giscus homepage. Look at the result locally
+    and you will see that the integration is active on all pages of the site.
+    If you want to restrict it to your blog posts, you need to add a conditional
+    around the Giscus script that tests if comments should be included. A simple
+    way of doing this is to test for a metadata flag:
+
+    ```html
+    {% if page.meta.comments %}
+    <script>...</script>
+    {% endif %}
+    ```
+
+    The disadvantage is that you now need to manually turn on comments for each
+    blog post - unless you want to turn them off on some. To get the comments
+    section on all blog posts, use code like this:
 
     ```html
-    <script
-        src="https://giscus.app/client.js"
-        data-repo="<username>/<repository>"
-        data-repo-id="..."
-        data-category="..."
-        data-category-id="..."
-        data-mapping="pathname"
-        data-reactions-enabled="1"
-        data-emit-metadata="1"
-        data-theme="preferred_color_scheme"
-        data-lang="en"
-        crossorigin="anonymous"
-        async
-    >
-    </script>
+    {% if page.file.src_uri.startswith('blog/posts') %}
+    <script>...</script>
+    {% endif %}
     ```
 
-[Giscus homepage]: https://giscus.app/
+    You should see now that the Giscus comments are added at the bottom of your
+    blog posts but not on other pages.
+
+## What's next?
+
+This is the end of the blog tutorial. We hope you have enjoyed it and manage to
+set up your blog the way you like it. There are numerous other features and
+options that we have not been able to cover here. The [blog plugin reference]
+provides comprehensive documentation for the plugin. You may also want to
+look at the [social plugin tutorial] to generate social cards for your blog
+posts that get displayed when you post links to social media systems.
+
+[blog plugin reference]: https://squidfunk.github.io/mkdocs-material/plugins/blog/
+[social plugin tutorial]: ../social.md