Skip to content

Commit

Permalink
+blog tutorial engagement part
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexvoss
alexvoss committed May 2, 2024
1 parent 876e7c6 commit cd15b11
Showing 1 changed file with 116 additions and 43 deletions.
159 changes: 116 additions & 43 deletions docs/tutorials/blogs/engage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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

0 comments on commit cd15b11

Please sign in to comment.