[Feature Request] docs: comments.

[Eliav2]

I think your blog posts are awesome. Consider enabling comments for docusaurus for blogs(or for doc pages as well) . You can follow this tutorial https://dev.to/m19v/how-to-add-giscus-comments-to-docusaurus-439h

I can open a PR for it if you are interested, I've already done it to our company docusaurus website

[jiashengguo]

Thanks! That would be great, we would love to have a new contributor!

[ymc9]

That'll be amazing @Eliav2 ! I've always wanted to have commenting for the doc site!

[Eliav2]

On the way! Would you like a PR to the dev or to the main branch?

• you would also need to enable discussions on zenstack-docs repo. OR creating new type of discussions in zenstack and providing me the required details. to enable discussions:
  • enable discussions in your repo settings.
  • create new discussions category and named it 'Comments`. i would suggest 'Question / Answer' format if you want to allow users to be able to comment on other comments as well.
  • run the following command:

    gh api graphql -f query='
    query {
      repository(owner: "zenstackhq", name: "zenstack-docs") {
        id
        discussionCategories(first: 10) {
          edges {
            node {
              id
              name
            }
          }
        }
      }
    }

  • provide me the output of the above command. i would need the id of the Comments category. you would get somthing like this:

    {
    "data": {
      "repository": {
        "id": "R_kgDOLao3kw",
        "discussionCategories": {
          "edges": [
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5p",
                "name": "Announcements"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb6H",
                "name": "Comments"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5q",
                "name": "General"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5s",
                "name": "Ideas"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5u",
                "name": "Polls"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5r",
                "name": "Q&A"
              }
            },
            {
              "node": {
                "id": "DIC_kwDOLao3k84Ceb5t",
                "name": "Show and tell"
              }
            }
          ]
        }
      }
    }
    }

    in this case, the id of the Comments category is DIC_kwDOLao3k84Ceb6H.

  • i would also need repoId. you can use the command gh repo view "Eliav2/zenstack-docs" --json id --jq '.id' `
  • then i would render Giscus component.

    <Giscus
    repo="Eliav2/zenstack-docs"
    repoId="R_kgDOLao3kw"
    category="Comments"
    categoryId="DIC_kwDOLao3k84Ceb6H" // id of "Comments"
    mapping="pathname" // Important! To map comments to URL
    term="Welcome zenstack site comments!"
    strict="0"
    reactionsEnabled="1"
    emitMetadata="0"
    inputPosition="top"
    theme={colorMode}
    lang="en"
    loading="lazy"
    />

  • Enable Giscus Configure giscus in your GitHub account. In Section "Repository access" add only created repository from previous step to be accessed by giscus and click "Save".
  • Thats it! Now commenting on the site immediately appears on site and creating new discussion. see

the only thing left is for you to follow my instructions and gave me the details of your actual real repo (zenstack-docs or zenstack, you get to decide where you want the discussion comments to apear).

Here's the pr

[jiashengguo]

@Eliav2, Thanks for working on it. I followed your instructions step by step and updated the information in the Giscus component to point to the zenstack-doc repository. However, I still can't see the comments UI on the blog page, both in the Vercel build and my local build. Did I miss anything?

[Eliav2]

Hey @jiashengguo I mentioned in the pr "currently, comments on blog post are not enabled. if you want i can enable them as well". This requiring "swizelling" the blog pages as well(a term used to describes outing out of built in components to custom ones. You can read about it in docusaurus).

If you wish, I can make comments available for blog as well. Just let me know what are your preferences, docs comments, blog comments, or both.

[Eliav2]

I've added comment to blog pages as well.

I've confirmed both docs page comments and blogs page comments are working properly. this pr is safe to be merged.

@jiashengguo please review pr.

and don't forget to delete my dummy discussions on zenstack-docs repo(once a real comment would be created a new discussion with your real url page would be created)

[jiashengguo]

Looks good to me! The only issue is with the blog comments. It seems that one comment from a blog appears under every blog on the blog list page(Thanks to your dummy discussion)

Is there an easy way to disable it on the list page? If not, we can simply disable the blog comment for now.

[Eliav2]

Absolutely right. I was probably swizelling the wrong component(thanks to some blog 😅) I would fix it this evening

[jiashengguo]

@Eliav2, the PR has been merged, great job!

There is a small issue in dark mode. When the page is first loaded, the background color doesn't appear correct. However, after switching, it displays correctly.

[Eliav2]

hey @jiashengguo i was not able to reproduce this bug on my side, even on initial page load on dark mode

[jiashengguo]

That's weird. Both Yiming and I saw it on our machine:

In the dark mode, after you hit refresh, you will see it. Then if you navigate to any other page, it will become normal.

[Eliav2]

it looks like a problem with Giscus: its storing its color mode. Giscus is rendered only when scrolled to view to reproduce:

• scroll to view in light mode. Giscus would be rendered light.
• move to another page and ensure Giscus is not in view yet. change the theme to dark. scroll Giscus to view. Giscus would be rendered with light theme because it stored it.

i was able to confirm that the problem is with the implementation of Giscus component and not useColorMode hook from Docusaurus.

it is probably because Giscus is a react wrapper around pure javascript lib. such bugs are common in such cases.

it can be fixed by unmounting and re-mounting GiscusComponent on colorMode change.

[Eliav2]

I was able to fix it. I'm opening pr with fix. heres the pr

[Eliav2]

the pr has been merged. keep on the awesome work, Zenstack team. thanks, until the next contribution

[ymc9]

the pr has been merged. keep on the awesome work, Zenstack team. thanks, until the next contribution

Thank you @Eliav2 ! The feature is fantastic!