参与和传播¶

添加RSS源

将RSS插件安装到您的项目中：

$ pip install mkdocs-rss-plugin

确保配置了 site_name、site_description 和 site_url 设置，如 基本博客教程中所述。RSS插件利用这些信息构建源，因此请确保您已正确配置它们。

现在，在 mkdocs.yml 中配置插件。提供的选项将RSS条目创建限制为博客文章，这可能正是您想要的。还要注意日期字段的配置，以匹配Material for MkDocs用于创建日期和更新日期的格式。

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

查看 http://localhost:8000/feed_rss_created.xml 以查看RSS源的完整XML格式。您可以使用Firefox或Chrome等浏览器来显示原始RSS源，或使用 curl 获取源并使用 xmllint 格式化它。（您可能需要安装这些工具。）

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

您还可以尝试使用RSS阅读器测试您的源。有多种桌面和移动应用程序以及在线服务可供选择。当然，要使用后者，您需要将项目部署到可以访问它们的地方。

添加社交媒体个人资料链接

在您的 mkdocs.yml 中添加一个 extra 部分，并在其中添加一个 social 部分，以包含链接定义的列表。这些定义包括要使用的图标和个人资料的链接。

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

对于 icon，您可以选择与主题捆绑的任何有效图标路径。name 将用作图标的标题属性，包含此信息可以提高可访问性。对于流行的社交媒体系统，链接需要是绝对的，并且需要包含方案，最可能是 https://。

您还可以使用其他方案。例如，要创建一个允许人们发送电子邮件的图标，请添加以下内容：

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

最后，您可以指定站点内的URL，例如指向您的联系页面。可以仅指定页面的路径：

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

添加分享按钮

为了添加分享按钮，您可以添加一个钩子，该钩子为当前页面附加分享按钮。

在您的项目根目录中创建一个 hooks 目录，并在 mkdocs.yml 中进行配置：

hooks:
  - hooks/socialmedia.py

添加文件 hooks/socialmedia.py，并粘贴以下Python代码：

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 }}
    """)

钩子首先检查当前页面是否为博客文章，然后附加分享按钮的Markdown代码。按钮使用图标，因此您还需要配置以下Markdown扩展：

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

启用讨论并安装Giscus应用

一旦仓库设置完成，转到其设置页面，在 General 部分找到 Features。勾选 Discussions 的复选框。您会看到 Discussions 出现在仓库的顶部导航中。如果您使用的是实时仓库，您可能希望在此时向讨论部分添加一些最小内容，然后再返回教程。

接下来，您需要通过单击此句子中的链接安装 Giscus应用，然后选择 Install，并按照说明选择要安装Giscus应用的位置：

1. 选择您想要使用的仓库的帐户或组织。
2. 选择仅在所选仓库上安装，并选择您想要使用的仓库。请注意，您可以在这里选择多个仓库。
3. 最后选择 Install。您可能需要进行身份验证以授予权限。
4. 您将进入设置中的 Applications 页面，在这里您可以控制Giscus应用并在需要时卸载它。

配置嵌入Giscus到您的博客所需的代码

转到 Giscus主页 并配置嵌入代码。有多个设置：

1. 选择语言
2. 输入用户名/组织名称和仓库名称
3. 选择如何将讨论映射到您博客上的页面。由于对于博客文章，标题是URL的基础，因此使用 Discussion title contains page <title> 选项是合理的。
4. 在 Discussion Category 下选择 Announcements，以限制新讨论的创建仅限于Giscus和具有维护者或管理员权限的人。
5. 在 Features 下，选择以下内容：
   1. 为主帖子启用反应
   2. 发出讨论元数据
   3. 将评论框放在评论上方
6. 在 Theme 下，选择 Preferred color scheme，以便Giscus与用户为您的网站选择的颜色方案匹配。

添加Giscus集成代码

首先，您需要创建一个 overrides 目录，该目录将包含您想要覆盖的模板和部分。

mkdir -p overrides/partials

您需要在您的 mkdocs.yaml 中声明它：

theme:
  name: material
  custom_dir: overrides

现在添加文件 overrides/partials/comments.html，并粘贴您从Giscus主页获得的代码片段。查看本地结果，您将看到集成在网站的所有页面上都是活跃的。如果您想将其限制为博客文章，您需要在Giscus脚本周围添加一个条件，以测试是否应该包含评论。一个简单的方法是测试元数据标志：

{% if page.meta.comments %}
<script>...</script>
{% endif %}

缺点是您现在需要手动为每个博客文章启用评论 - 除非您想在某些文章上关闭它们。要在所有博客文章上获取评论部分，请使用如下代码：

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

您现在应该看到Giscus评论已添加到您的博客文章底部，但未出现在其他页面上。