× Introducing Rollout, An awesome deployment system for your PHP webapps. [More info]
Thu 23 Aug 2018

Setup disqus commenting plugin for readthedocs theme with mkdocs.

Setup disqus commenting plugin with mkdocs

Create disqus site configuration if you don't have already and if you have one get the following details handy.

sitename

The sitename that you give in the disqus, which diqus use to uniquely identify.

embed code

The div tag thats where the comments would show up.

<div id="disqus_thread"></div>

The JS piece

<script>
var disqus_config = function () {
// Replace PAGE_URL with your page's canonical URL variable
this.page.url = PAGE_URL;  

// Replace PAGE_IDENTIFIER with your page's unique identifier variable
this.page.identifier = PAGE_IDENTIFIER; 
};

(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://rolloutdocs.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

To show comment count Place the following code before your site's closing </body>tag:

<script id="dsq-count-scr" src="//rolloutdocs.disqus.com/count.js" async>
</script>

Once you obtain these, we need to add the js script right in the page content section of base.html in the readthedocs theme.

Generally on mac it will be on /Library/Python/2.7/site-packages/mkdocs/themes/readthedocs

You can find the actual location by doing a mkdocs -v build you can look for the info as below.

DEBUG   -  Config value: 'theme' = Theme(name='readthedocs', 
    dirs=['/Library/Python/2.7/site-packages/mkdocs/themes/readthedocs', u'/Library/Python/2.7/site-packages/mkdocs/templates'], 
    static_templates=[u'404.html', u'sitemap.xml'], 
    )

Edit the base.html file present in the /Library/Python/2.7/site-packages/mkdocs/themes/readthedocs folder on mac but the folder location may vary for other operating systems. Please do accordingly.

      {# PAGE CONTENT #}
      <div class="wy-nav-content">
        <div class="rst-content">
          {% include "breadcrumbs.html" %}
          <div role="main">
            <div class="section">
              {% block content %}
                {{ page.content }}
              {% endblock %}
              <!-- disqus js piece should insert here -->

            </div>
          </div>

Setup the disqus_config with the following details.

var disqus_config = function () {
                    this.page.url = "{{ page.canonical_url }}";
                    this.page.identifier =
                    "{{ page.canonical_url | replace(config.site_url, "") }}";
                  };

So that end markup should be like this.

      {# PAGE CONTENT #}
      <div class="wy-nav-content">
        <div class="rst-content">
          {% include "breadcrumbs.html" %}
          <div role="main">
            <div class="section">
              {% block content %}
                {{ page.content }}
              {% endblock %}

              {% if config.extra.disqus and not page.is_homepage %}
                <div id="disqus_thread"></div>
                <script>
                  var disqus_config = function () {
                    this.page.url = "{{ page.canonical_url }}";
                    this.page.identifier =
                      "{{ page.canonical_url | replace(config.site_url, "") }}";
                  };
                  (function() {
                    var d = document, s = d.createElement("script");
                    s.src = "//{{ config.extra.disqus }}.disqus.com/embed.js";
                    s.setAttribute("data-timestamp", +new Date());
                    (d.head || d.body).appendChild(s);
                  })();
                </script>
              {% endif %}

            </div>
          </div>

Now in your mkdocs.yml file add the disqus in the extra section as shown here.

extra:
    disqus: 'Your disqus site name goes here'

You are done. Now you can do new build using the command mkdocs build and it would work like a charm. If you find this useful feel free to bookmark this - Ctrl + D.