Engagement and dissemination¶

Add an RSS feed

Install the RSS plugin into your project:

$ pip install mkdocs-rss-plugin

It is important that have the site_name, site_description and site_url settings configured as instructed in the basic blog tutorial. The RSS plugin makes use of this information to construct the feed, so make sure you have configured them.

Now, configure the plugin in the mkdocs.yml. The options provided restrict the pages that RSS entries are created for to the blog posts, which is probably what you want. Also note the configuration of the date fields to match the format that Material for MkDocs uses to accommodate both a creation date and a date for updates.

plugins:
    - ...
    - rss:
        match_path: "blog/posts/.*"
        date_from_meta:
          as_creation: date.created
          as_update: date.updated

Have a look at http://localhost:8000/feed_rss_created.xml to see the RSS feed in all its XML glory. You can use a browser like Firefox or Chrome that can display the raw RSS feed or use curl to get the feed and xmllint to format it. (You may need to install these tools.)

curl -s http://localhost:8000/feed_rss_created.xml | xmllint --format -

You may also want to try your feed with a feed reader. There are various desktop and mobile apps as well as online services. Of course, to use the latter you will need to deploy your project somewhere that is accessible to them.

Adding social media profile links

Add an extra section to your mkdocs.yml and, within it, a social section to contain a list of link definitions. These consist of the logo to use and the link to the profile.

extra:
  social:
    - icon: fontawesome/brands/mastodon
      name: squidfunk on Mastodon
      link: https://fosstodon.org/@squidfunk

For the icon, you can choose any valid path to an icon bundled with the theme. The name will be used as the title attribute for the icon and including this improves accessibility. For popular social media systems, the link needs to be absolute and needs to include the scheme, most likely https://.

You can also use other schemes. For example, to cerate an icon that allows people to create an email, add this:

extra:
  social:
  - icon: /fontawesome/regular/envelope
    name: send me an email
    link: mailto:<email-address>

Finally, you can specify a URL within your site, such as to your contact page. It is possible to specify only the path to the page:

extra:
  social:
  - icon: /material/mailbox
    name: contact us
    link: /contact

Add share buttons

In order to add the share buttons, you can add a hook that appends buttons for sharing the current page.

Create a directory hooks in your project root and configure it in your mkdocs.yml:

hooks:
  - hooks/socialmedia.py

Add the file hooks/socialmedia.py with the following Python code:

from textwrap import dedent
import urllib.parse
import re

x_intent = "https://x.com/intent/tweet"
fb_sharer = "https://www.facebook.com/sharer/sharer.php"
include = re.compile(r"blog/[1-9].*")

def on_page_markdown(markdown, **kwargs):
    page = kwargs['page']
    config = kwargs['config']
    if not include.match(page.url):
        return markdown

    page_url = config.site_url+page.url
    page_title = urllib.parse.quote(page.title+'\n')

    return markdown + dedent(f"""
    [Share on :simple-x:]({x_intent}?text={page_title}&url={page_url}){{ .md-button }}
    [Share on :simple-facebook:]({fb_sharer}?u={page_url}){{ .md-button }}
    """)

The hook first checks if the current page is a blog post and then appends Markdown code for the share buttons. The buttons use icons, so you also need to configure the following markdown extensions:

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Turn on discussions and install the Giscus app

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 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.
3. Select Install at the end. You may need to authenticate to give permission for this to happen.
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.

Configure the code needed to embed Giscus into your blog

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 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. 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.

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

You need to declare it in your mkdocs.yaml:

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:

{% 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:

{% if page.file.src_uri.startswith('blog/posts') %}
<script>...</script>
{% endif %}

You should see now that the Giscus comments are added at the bottom of your blog posts but not on other pages.