search

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
191 stars 29 forks source link

doc use of Giscus; add comments meta data tag #188

Closed 2bndy5 closed 1 year ago

2bndy5 commented 1 year ago

Allows integration of page comments using giscus (which uses github's discussions feature). Only thing we needed was a comments meta data field to enable comments for a specific page. Everything else is done by the user in the docs project's template overrides, which is now documented with instructions in customization.rst.

Tested this on a separate repo of mine (hosted at RTD.org), and it seems to work. It will not work when the URL is a file://. So, there's a preview at the bottom of this page.

2bndy5 commented 1 year ago

Giscus can derive a discussion's title from meta data, but we haven't been supporting the meta directive in a way that the inherited html templates can render the neccesary <meta> tags. So, I've added the necessary info to the pages' template context.

For example, users can specify the title of the github discussion to be embedded in a page by using the following rST source:


:show-comments:

.. meta::
    :property=og\:title: discussion name

Note: this requires the giscus generated <script> tag to have the data-mapping="og:title" attribute set.

Beneficially, I think this meta tag support also allows adding keywords/tags for search results:

.. meta::
    :keywords: tag_name
    :keywords lang=en: english tags
jbms commented 1 year ago

Looks good to me.