How to properly setup Disqus?

[Andre601]

The Adding a Comment System page is kinda vague on how you actually setup disqus itself, as there seems to not be any proper documentation on that in regards to Material for MkDocs.

It basically is "You sign up to Disqus, create a new chat and use the shortname" which is really bare-bone and doesn't help beginners like me to understand how to integrate Disqus properly.

The issues I myself currently face is how to actually setup a chat to then use in the docs. I never did this before and on first look does it seem like you have to pay to use Disqus?
If there is a proper tutorial explaining the little details would I appreciate if you could link it for me, as I'm really lost here.

[Andre601]

How to setup Disqus for Material for MkDocs

I list a complete tutorial here on how to implement Disqus to your MkDocs documentation.

Step 1: Signup/Login to Disqus

You first need to signup or login to your account on https://disqus.com

Step 2: Create a new Chat

Go to Disqus.com/profile/signup/intent/ and click "I want to install Disqus on my site"

You then need to provide a Website name. This will also be used to generate the shortname, but you can alter it by clicking on "Customize Your URL".
Select a category for your chat and the main language and click "Create Site".

You're then landing on the subscription page where you need to choose the subscription you want. For the free one, scroll a bit down and select "Basic" by clicking on "Subscribe Now".

Now you're asked to select a platform. Scroll to the bottom and click the button that reads "I don't see my platform listed, install manually with Universal Code"

The next page isn't inportant for us so you just scroll down and click "Configure" at the bottom right.

On the second-last page can you now configure the different settings for your chat. Important is here, that you set the website URL you use for the documentation (What you have set as site_url in your mkdocs.yml).
You can also provide a link to your Privacy Policy, if available. But this is optional and defaults to Disqus' policy from what I figured out.

If you're done, just click "Next" to get to the final page. On this page can you now choose the moderation level that should be used. You can choose between Balanced and Strict. Both are explained.

To finish the setup click on "Complete Setup"

Step 3: Add to your Docs

If you followed Step 2 should you now be on https://<your-shortname>.disqus.com/admin/install/complete.
To add it now to your docs, select and copy <your-shortname> in the URL and paste it into the extra.disqus setting inside the mkdocs.yml file. If this setting doesn't exist, add it.

As a final step will you just need to publish/update your docs with those new changes and disqus should appear on all pages except the index page.

You can then continue with the "Selective integration" step on the Mkdocs Material docs to add/remove Disqus from specific pages.