## File: README.md

# Isso – a commenting server similar to Disqus

Isso – *Ich schrei sonst* – is a lightweight commenting server written in
Python and JavaScript. It aims to be a drop-in replacement for
[Disqus](http://disqus.com).

## Features

- **Comments written in Markdown**  
  Users can edit or delete own comments (within 15 minutes by default).
  Comments in moderation queue are not publicly visible before activation.
- **SQLite backend**  
  *Because comments are not Big Data.*
- **Disqus & WordPress Import**  
  You can migrate your Disqus/WordPress comments without any hassle.
- **Configurable JS client**  
  Embed a single JS file, 65kB (20kB gzipped) and you are done.

See **[isso-comments.de](https://isso-comments.de/)** for a **live demo**, more
details and [documentation](https://isso-comments.de/docs/).

## Screenshot



## Getting started

### Requirements

- Python 3.7+ (+ devel headers)
- SQLite 3.3.8 or later
- a working C compiler

Install Isso from [PyPi](https://pypi.python.org/pypi/isso/):

```console
pip install isso
```

Then, follow the [Quickstart](https://isso-comments.de/docs/guides/quickstart/) guide.

If you're stuck, follow the [Install guide](https://isso-comments.de/docs/reference/installation/),
see [Troubleshooting](https://isso-comments.de/docs/guides/troubleshooting/) and browse
the [the full documentation](https://isso-comments.de/docs/).

## Docker

A Docker image with the latest stable release is provided at
`ghcr.io/isso-comments/isso:latest`. See
[Using Docker](https://isso-comments.de/docs/reference/installation/#using-docker).

## Contributing

- Pull requests are very much welcome! These might be
  [good first issues](https://github.com/posativ/isso/labels/good-first-issue)
- See [Ways to Contribute](https://isso-comments.de/docs/contributing/)
- [Translate](https://isso-comments.de/docs/contributing/#translations)

### Development


Refer to the docs for
[Installing from Source](https://isso-comments.de/docs/reference/installation/#install-from-source).

### Help

- Join `#isso` via [Matrix](https://matrix.to/#/#isso:libera.chat) or via IRC on
  [Libera.Chat](https://libera.chat/)
- Ask a question on [GitHub Discussions](https://github.com/posativ/isso/discussions).

## License

MIT, see [LICENSE](LICENSE).

---

## File: docs/docs/guides/advanced-integration.rst

Advanced integration
====================

Comment counter
---------------

If you want to display a comment counter for a given thread, simply
put a link to that comments thread anchor:

.. code-block:: html

    [Comments](/my-uri.html#isso-thread)

The *isso js client* will replace the content of this tag with a human readable
counter like *"5 comments"*.

Alternatively, if guessing from `href` is not relevant, you could use a
`data-isso-id` attribute on the `<a>` to indicate which thread to count for.

Now, either include `count.min.js` if you want to show only the comment count
(e.g. on an index page) or `embed.min.js` for the full comment client (see
:doc:`quickstart`); do not mix both.

You can have as many comments counters as you want in a page, and they will be
merged into a single `GET` request.

Asynchronous comments loading
-----------------------------

Isso will automatically fetch comments after `DOMContentLoaded` event. However
in the case where your website is creating content dynamically (eg. via ajax),
you need to re-fetch comment thread manually. Here is how you can re-fetch the
comment thread:

.. code-block:: js

    window.Isso.fetchComments()

It will delete all comments under the thread but not the PostBox, fetch
comments with `data-isso-id` attribute of the element `section#isso-thread` (if
that attribute does not exist, fallback to `window.location.pathname`), then
fill comments into the thread. In other words, you should change `data-isso-id`
attribute of the element `section#isso-thread` (or modify the pathname with
`location.pushState`) before you can get new comments. And the thread element
itself should *NOT* be touched or removed.

If you removed the `section#isso-thread` element, just create another element
with same TagName and ID in which you wish comments to be placed, then call the
`init` method of `Isso`:

.. code-block:: js

    window.Isso.init()

Then Isso will initialize the comment section and fetch comments, as if the page
was loaded.

---

## File: docs/docs/guides/faq.rst

Frequently asked questions
==========================

Why SQLite3?
------------

Although partially answered on the index page, here is a more complete answer: If
you manage massive amounts of comments, Isso is a really bad choice. Isso is
designed to be simple and easy to setup, it is not optimized for high-traffic
websites.

    **Comments are not big data.**

For example, if you have 209 threads and 778 comments in total this only needs 620 kilobytes
of memory. This is an excellent use case for SQLite.

What does "Isso" mean?
----------------------

Isso is an informal, german abbreviation for "Ich schrei sonst!", which can
roughly be translated to "I'm yelling otherwise". It usually ends the
discussion without any further arguments.

In germany, Isso `is also pokémon N° 360`__.

.. __: http://bulbapedia.bulbagarden.net/wiki/Wynaut_(Pok%C3%A9mon)

.. attention::

   This section of the Isso documentation is incomplete. Please help by expanding it.

   Click the ``Edit on GitHub`` button in the top right corner and read the
   GitHub Issue named
   `Improve & Expand Documentation <https://github.com/posativ/isso/issues/797>`_
   for further information.

   **What's missing?**

   - How is Isso different from Disqus, Facebook Comments, and the rest?
   - How can I report bugs or request features?
   - In which ways can I contribute?
   - I am seeing an error!

   ... and other frequently asked questions.

---

## File: docs/docs/guides/quickstart.rst

Quickstart
==========

Assuming you have successfully :doc:`installed </docs/reference/installation>`
Isso, here's a quickstart guide that covers the most common setup. Sections
covered:

.. contents::
    :local:
    :depth: 1

Configuration
-------------

You must provide a custom configuration to set ``dbpath`` (your database
location) and ``host`` (a list of websites for CORS_). All other options have
sane defaults.

.. code-block:: ini

    [general]
    ; database location, check permissions, automatically created if it
    ; does not exist
    dbpath = /var/lib/isso/comments.db
    ; your website or blog (not the location of Isso!)
    host = http://example.tld/
    ; you can add multiple hosts for local development
    ; or SSL connections. There is no wildcard to allow
    ; any domain.
    host =
        http://localhost:1234/
        http://example.tld/
        https://example.tld/

Note, that multiple, *different* websites are **not** supported in a single
configuration. To serve comments for different websites, refer to
:ref:`Multiple Sites <configure-multiple-sites>`.

The moderation is done with signed URLs sent by email or logged to stdout.
By default, comments are accepted and immediately shown to other users. To
enable moderation queue, add:

.. code-block:: ini

    [moderation]
    enabled = true

To moderate comments, either use the activation or deletion URL in the logs or
:ref:`use SMTP <configure-smtp>` to get notified of new comments, including the
URLs for activation and deletion:

.. code-block:: ini

    [general]
    notify = smtp
    [smtp]
    ; SMTP settings

For more options, see :doc:`server </docs/reference/server-config>`
and :doc:`client </docs/reference/client-config>` configuration.

Migration
---------

Isso provides a tool for importing comments from Disqus_ or WordPress_.
You can also import comments from any other comment system, but this topic is more
complex and is covered in :ref:`advanced migration <advanced-migration>`.

To export your comments from Disqus, log into Disqus, go to your website, click
on *Discussions* and select the *Export* tab. You'll receive an email with your
comments. Unfortunately, Disqus does not export up- and downvotes.

To export comments from your previous WordPress installation, go to *Tools*,
export your data. It has been reported that WordPress may generate broken XML.
Try to repair the file using ``xmllint`` before you continue with the import.

Now import the XML dump:

.. code-block:: console

    (.venv) $ isso -c /path/to/isso.cfg import -t [disqus|wordpress] disqus-or-wordpress.xml
    [100%]  53 threads, 192 comments

.. _Disqus: https://disqus.com/
.. _WordPress: https://wordpress.org/

Running Isso
------------

To run Isso, simply execute:

.. code-block:: console

    (.venv) $ isso -c /path/to/isso.cfg run
    2013-11-25 15:31:34,773 INFO: connected to HTTP server

Next, we configure Nginx_ to proxy Isso. Do not run Isso on a public interface!
A popular but often error-prone (because of CORS_) setup to host Isso uses a
dedicated domain such as ``comments.example.tld``.

Assuming both, your website and Isso are on the same server, the nginx
configuration looks like this:

.. code-block:: nginx
  :emphasize-lines: 9,12

    server {
        listen [::]:80 default;
        server_name example.tld;
        root ...;
    }

    server {
        listen [::]:80;
        server_name comments.example.tld;

        location / {
            proxy_pass http://localhost:8080;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }

Integration
-----------

Now, you embed Isso to your website:

.. code-block:: html

    <script data-isso="//comments.example.tld/"
            src="//comments.example.tld/js/embed.min.js"></script>

    <section id="isso-thread">
        <noscript>Javascript needs to be activated to view comments.</noscript>
    </section>

Note, that ``data-isso`` is optional, but when a website includes a script using
``async`` it is no longer possible to determine the script's external URL.

That's it. When you open your website, you should see a commenting form. Leave
a comment to see if the setup works. If not, see :doc:`troubleshooting`.

Going Further
-------------

There are several server and client configuration options not covered in this
quickstart, check out :doc:`/docs/reference/server-config` and
:doc:`/docs/reference/client-config` for more information. For further website
integration, see :doc:`advanced-integration`.

To launch Isso automatically, check the :ref:`init-scripts` section from the
installation guide. A different approach to deploy a web application is
written here: :doc:`Deployment of Isso </docs/reference/deployment/>`.

.. _Nginx: http://nginx.org/
.. _CORS: https://developer.mozilla.org/en/docs/HTTP/Access_control_CORS

---

## File: docs/docs/guides/tips-and-tricks.rst

Tips & Tricks
=============

Sections covered in this document:

.. contents::
    :local:
    :depth: 1


Lazy-loading on scroll
----------------------

You can defer loading the ``embed.min.js`` script until the user has scrolled
to the bottom of the page:

.. code-block:: html

    <script type="text/javascript">
        // Lazy-load isso only when page end is in view
        function loadIsso() {
            var script = document.createElement("script");
            script.setAttribute("type", "text/javascript");
            script.setAttribute("src", "/prefix/js/embed.min.js");
            // add relevant data-isso attributes here
            script.setAttribute("data-isso", "/prefix/");
            document.getElementsByTagName("head")[0].appendChild(script);
        }
        let offset = 50; // Start loading 50px before reaching bottom
        function scrollBottomListener(ev) {
            if ((window.scrollY + window.innerHeight)
                    >= (document.documentElement.scrollHeight - offset)) {
                loadIsso();
                window.removeEventListener('scroll', scrollBottomListener);
            }
        }
        window.onload = function() {
          // If viewport >= page height, load immediately
          if ((window.scrollY + window.innerHeight)
                    >= (document.documentElement.scrollHeight - offset)) {
              loadIsso();
          } else {
              window.addEventListener('scroll', scrollBottomListener);
          }
        }
    </script>

*Note that loading additional content only after user interaction is bad for
SEO. Additionally, users could experience a "jank" effect.*

Use lazy-loading only if you are desperately trying to save bandwidth. By
specifying ``async`` in the ``<script`` tag, loading the Isso Javascript will
not render-block anyway.

.. _advanced-migration:

Advanced Migration
------------------

In quickstart we saw you can import comments from Disqus or WordPress. But there
are many other comments system and you could be using one of them.

Isso provides a way to import such comments, however it's up to you to to:

- dump comments
- fit the data to the following JSON format::

    A list of threads, each item being a dict with the following data:

    - id: a text representing the unique thread id (note: by default isso
          associates this ID to the article URL, but it can be changed on
          client side with "data-isso-id" - see :doc:`client configuration <../configuration/client>` )
    - title: the title of the thread
    - comments: the list of comments

        Each item in that list of comments is a dict with the following data:

        - id: an integer with the unique id of the comment inside the thread
          (it can be repeated among different threads); this will be used to
          order the comment inside the thread
        - author: the author's name
        - email: the author's email
        - website: the author's website
        - remote_addr: the author's IP
        - created: a timestamp, in the format "%Y-%m-%d %H:%M:%S"

Example:

.. code-block:: json

    [
        {
            "id": "/blog/article1",
            "title": "First article!",
            "comments": [
                {
                    "author": "James",
                    "created": "2018-11-28 17:24:23",
                    "email": "email@mail.com",
                    "id": "1",
                    "remote_addr": "127.0.0.1",
                    "text": "Great article!",
                    "website": "http://fefzfzef.frzr"
                },
                {
                    "author": "Harold",
                    "created": "2018-11-28 17:58:03",
                    "email": "email2@mail.com",
                    "id": "2",
                    "remote_addr": "",
                    "text": "I hated it...",
                    "website": ""
                }
            ]
        }
    ]

Keep in mind that isso expects to have an array, so keep the opening and ending square bracket even if you have only one article thread!

Next you can import you json dump:

.. code-block:: sh

    ~> isso -c /path/to/isso.cfg import -t generic comment-dump.json
    [100%]  53 threads, 192 comments

Export comments as CSV
----------------------

As suggested by `Joshua Gleitze`_:

.. code-block:: bash

    dbpath='/path/to/your/isso.db'
    data=$(sqlite3 ${dbpath} -csv 'SELECT threads.uri, threads.title, comments.id, comments.mode, datetime(comments.created, "unixepoch", "localtime"), datetime(comments.modified, "unixepoch", "localtime"), comments.author, comments.email, comments.website, comments.remote_addr, comments.likes, comments.dislikes, comments.voters,comments.text FROM comments INNER JOIN threads ON comments.tid=threads.id')
    header='"page: URI","page: title","ID","mode","created on","modified on","author: name","author: email","author: website","author: IP","likes","dislikes","voters","text"'
    echo -e "${header}\n""${data}" > export.csv

Use `isso-to-disqus.py <https://github.com/angristan/isso-to-disqus>`_ and see
other options as discussed in `this issue`_.

.. _Joshua Gleitze: https://github.com/isso-comments/isso/issues/186#issuecomment-223550325
.. _this issue: https://github.com/isso-comments/isso/issues/186

Pretty-print entire comments database
-------------------------------------

.. Migration complete from https://github.com/isso-comments/isso/wiki/Tips-&-tricks

The following bash function pretty-print the entire comments DB sorted by
insertion date.

.. code-block:: bash

   get_blog_comments () {
       ssh $host sqlite3 -line /path/to/isso/isso.db \
           "'SELECT t.uri,c.created,c.modified,c.text,c.author,c.email,c.website \
             FROM comments AS c, threads as t WHERE c.tid = t.id;'" \
           | perl -wpe '/(created|modified) = ./&&s/= (.*)/"= ".scalar(localtime($1))/e';
   }

Example output:

.. code-block:: text

        uri = /lucas/blog/2014/12/12/fr-la-tete-dans-le-guidon/
    created = Mon Dec 15 13:10:28 2014
   modified =
       text = Merci ! Je suis très content d'apprendre que cette lecture a pu plaire à quelqu'un
   N'hésitez pas à partager vos propres réflexions et astuces dans les commentaires.
     author = lucas
      email = lucas@chezsoi.org
    website = https://chezsoi.org/lucas/blog


Delete IP addresses weekly
--------------------------

Add this to your ``crontab`` to set all saved commenter IP addresses to
``127.0.0.1`` to preserve their privacy under GDPR:

.. code-block:: text

   @weekly /usr/bin/sqlite3 /path/to/isso/comments.db 'UPDATE comments SET remote_addr = "127.0.0.1";'

From `blog.mdosch.de <https://blog.mdosch.de/2018/05/20/isso-ip-adressen-woechentlich-loeschen/>`_:

*Note that Isso already anonymizes the last part of IP addresses by setting
them to to zero.*


Change linked comment highlight color
-------------------------------------

When you click a link that goes to a specific Isso comment (such as ``https://example.com/example-post/#isso-43``),
the comment will be highlighted yellow and then fade out over a few seconds.

Add the following CSS to your site to change that color (replace ``#3f3c1c`` with any color of your choice):

.. code-block:: css

   @keyframes isso-target-fade {
     0% { background-color: #3f3c1c; }
   }


.. attention::

   This section of the Isso documentation is incomplete. Please help by expanding it.

   Click the ``Edit on GitHub`` button in the top right corner and read the
   GitHub Issue named
   `Improve & Expand Documentation <https://github.com/isso-comments/isso/issues/797>`_
   for further information.

   **What's missing?**

   - Removing unused languages
   - Importing & exporting comments (integrate migration docs)
   - Keeping compat using babel

   ... and other collected tips & tricks, maybe also from the wiki.

---

## File: docs/docs/guides/troubleshooting.rst

Troubleshooting
===============

For uberspace users
-------------------
Some uberspace users experienced problems with isso and they solved their
issues by adding `DirectoryIndex disabled` as the first line in the `.htaccess`
file for the domain the isso server is running on.

The `Installing Isso on Uberspace <https://lab.uberspace.de/guide_isso/>`_
guide should also be helpful.

pkg_ressources.DistributionNotFound
-----------------------------------

This is usually caused by messing up the system's Python with newer packages
from PyPi (e.g. by executing `easy_install --upgrade pip` as root) and is not
related to Isso at all.

Install Isso in a virtual environment as described in
:ref:`install-interludium`. Alternatively, you can use `pip install --user`
to install Isso into the user's home.

Why isn't markdown in my comments rendering as I expect?
--------------------------------------------------------

Please :ref:`configure <configure-markup>` Isso's markup parser to your
requirements as described in :doc:`/docs/reference/markdown-config`.

UnicodeDecodeError: 'ascii' codec can't decode byte 0xff
--------------------------------------------------------

Likely an issue with your environment, check you set your preferred file
encoding either in :envvar:`LANG`, :envvar:`LANGUAGE`, :envvar:`LC_ALL` or
:envvar:`LC_CTYPE`:

.. code-block:: text

    $ env LANG=C.UTF-8 isso [-h] [--version] ...

If none of the mentioned variables are set, the interaction with Isso will
likely fail (unable to print non-ascii characters to stdout/err, unable to
parse configuration file with non-ascii characters and so forth).

The web console shows 404 Not Found responses
---------------------------------------------

Isso returned "404 Not Found" to indicate "No comments" in versions prior to
0.12.3. This behaviour was changed in
`a pull request <https://github.com/posativ/isso/pull/565>`_ to return a code
of "200" with an empty array.

---

## File: docs/docs/contributing/documentation.rst

Writing Documentation
=====================

The documentation for Isso has several purposes: It should help newcomers have
a good experience in installing and setting up Isso, make it clear how to
configure for several use cases, and invite people to improve the project by
participating.

.. note::
   You may look at the `docs/`_ folder to see how existing documentation is
   written or click the top right **"Edit on GitHub"** button to directly edit
   a page.

.. _docs/: https://github.com/isso-comments/isso/tree/master/docs

Sections covered in this document:

.. contents::
   :local:

Introduction
------------

The documentation for Isso is written using the `Sphinx`__ documentation
project in a markup language called ``reStructuredText`` (``reST``). The
documentation files have have ``.rst`` as a file extension.

``reST`` works a bit like Markdown, but has some differences. Here's an
example:

.. code-block:: rst

    One asterisk: *text* for emphasis (italics),
    Two asterisks: **text** for strong emphasis (boldface), and
    Double backticks: ``text`` for code samples.

.. __: https://www.sphinx-doc.org/en/master/

Building the docs
-----------------

You will need to have the latest version of the ``Sphinx`` documentation generator installed
`from PyPi <https://pypi.org/project/Sphinx/>`_.

.. warning:: Please avoid using the version installed by your operating system
   since it may be severely outdated and throw errors with Isso's theme. Isso's
   docs need **at least Sphinx version 4.5.0**.

Install via pip:

.. code-block:: console

   $ virtualenv --download .venv && $ source .venv/bin/activate
   (.venv) $ pip install sphinx
   (.venv) $ sphinx-build --version
   ~> sphinx-build 4.5.0

Build the docs:

.. code-block:: console

   (.venv) $ make site

You can then view the generated docs by starting a local server with
``cd docs/_build/html && python -m http.server`` and visiting ``http://localhost:8000``.

Styles
^^^^^^

The stylesheets of the theme are written in a CSS-like language called
`sass <https://sass-lang.com/guide>`_ and have the ``.scss`` file extension.

If you have made any changes to the stylesheets, you need to install the
`sassc`__ program and then re-generate the CSS file at
``docs/_static/css/site.css``:

.. code-block:: console

   $ apt install sassc
   $ make css

.. __: https://github.com/sass/sassc

How to write reST
-----------------
First and foremost, see the
`reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
You can play with a live rST editor at `snippets.documatt.com <https://snippets.documatt.com/>`_.

**Links:**

.. code-block:: rst

    Use `Link text <https://domain.invalid/>`_ for **inline web links**.

    This is a paragraph that contains `a link`_ using **references**.

    .. _a link: https://domain.invalid/

**Headings:**

Headings must always be *underlined* with at least as many characters as the
text is wide.

.. code-block:: rst

   Page title
   ==========

Use page title only once per file (at the top). This is also the name that the
page will appear under.

.. code-block:: rst

   Section heading (h3)
   --------------------

Use section heading to divide page into sections

.. code-block:: rst

   Sub-Heading (h4)
   ^^^^^^^^^^^^^^^^

Use sub-heading only if necessary - if you need this many levels of headings,
maybe the content would better be spread out across multiple articles

**Referencing other sections:** (see `:ref:`__)

.. code-block:: rst

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

.. __: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role

**Referencing other documents:** (see `:doc:`__)

.. code-block:: rst

    See also :doc:`/contributing` or :doc:`the news page </news>`

.. __: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents

**Code blocks:**

Use ``.. code-block:: <language>`` and indent the code by one level:

.. code-block:: rst

   .. code-block:: console

        $ sudo apt install python3 python3-pip python3-virtualenv
        $ virtualenv --download .venv
        $ source .venv/bin/activate
        (.venv) $ python [cmd]

Syntax standards
----------------

- Use at most three levels of headlines:
  ``===`` for page title, ``---`` for section headings (h3), ``^^^`` for
  sub-headings (h4).
- Use ``$ /usr/bin/command`` to refer to shell commands and use
  ``code-block:: console`` over ``bash`` or ``sh``.
  For actual shell scripts, use ``sh``.
- Use ``(.venv) $ python [cmd]`` for things that need to be run inside a
  virtual environment and be consistent
  (see `Sphinx: Narrative Documentation`__)
- Use ``/path/to/isso/`` to refer to items inside Isso's installation
  directory or for user data and use ``comments.db`` as the name for the
  database, ``isso.cfg`` (not ``.conf``) for (user) config files.
- Admonitions should only be: ``note``, ``tip``, ``warning``, ``attention``,
  (maybe also ``error``?). See `docutils: Admonitions`__.
- Try to keep line length under 80 characters, but don't worry when going over
  that limit when using links or code blocks
- Use ``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::`` to
  make it clear to readers which version of Isso are affected by an
  option or behavior

.. __: https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html
.. __: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions

Inspiration
-----------

The following documentation pages should serve as good examples. They are from
related projects that also offer commenting functionality.

- `Commento Documentation <https://docs.commento.io/>`_, especially the
  `contributing section <https://docs.commento.io/contributing/>`_.
- `Remark42 Documentation <https://remark42.com/docs/getting-started/installation/>`_
- `Schnack Documentation <https://schnack.cool/>`_

A model for good documentation has been laid out by Divio as the
`Divio Documentation System <https://documentation.divio.com/>`_.
It divides docs into four clear areas:

- Tutorials
- How-to guides
- Explanation
- Reference

The `Django docs <https://docs.djangoproject.com/en/dev/#how-the-documentation-is-organized>`_
also follow this system.

Other Tips & Tricks
-------------------

Helpful links:

- `Cross-referencing with Sphinx <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
- `Sphinx directives <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
- For theme authors: Look at
  `sphinx-rtd-theme internals <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html>`_

Debugging cross-references:

.. code-block:: sh

    python -m sphinx.ext.intersphinx docs/_build/html/objects.inv

Also make sure you have used ``:ref:`` or ``:doc``
correctly and not confused the two.

Automatic rebuilds
^^^^^^^^^^^^^^^^^^

For easier docs development through file watching, automatic rebuilding and
refreshing the browser, use `sphinx-autobuild`_:

.. code-block:: console

   (.venv) $ pip install sphinx-autobuild
   (.venv) $ sphinx-autobuild -b dirhtml docs/ docs/_build/html

Then visit ``localhost:8000``

.. _sphinx-autobuild: https://github.com/executablebooks/sphinx-autobuild


.. attention::

   This section of the Isso documentation could be improved. Please help by expanding it.

   Click the ``Edit on GitHub`` button in the top right corner and read the
   GitHub Issue named
   `Improve & Expand Documentation <https://github.com/isso-comments/isso/issues/797>`_
   for further information.

   **What's missing?**

   - How to write good documentation, maybe link to a few guides and example sites
   - More syntax standards, and also correct wrong usage across the docs

   ... and other things about documentation that should be documented.

---

## File: docs/docs/contributing/index.rst

Contribute
==========

.. list-table:: **I am looking to...**

    * - ... :ref:`report an issue <contribute-report-issues>`
      - ... :ref:`translate Isso into my language <contribute-translations>`
      - ... :ref:`improve the documentation <contribute-docs>`
      - ... :ref:`contribute code <contribute-code>`

*The Isso community welcomes your changes. We don't bite and are happy for
anyone who donates their time and effort to the project.*

.. _contribute-report-issues:

Report issues
-------------

You are welcome report issues at the
`GitHub Issue tracker <https://github.com/posativ/isso/issues>`_.

If you need help or want to request a feature, please `open a discussion`__
instead. For more ways to get in contact, see the :doc:`/community` page.

.. __: https://github.com/posativ/isso/discussions

Here are a few general rules to keep in mind when reporting issues:

- **Disqus import fails** – if ``isso import /path/to/disqus.xml`` fails,
  please do *NOT* attach the raw dump file to GH:Issues. Please anonymize all
  IP addresses inside the ```` tag first, as second step, replace
  all ```` addresses with a generic one.

- **embed.min.js-related issues** –  if you get a cryptic JavaScript error in
  the console, embed ``embed.dev.js`` instead of ``embed.min.js`` and create an
  issue with ±10 lines of code around the error.

- **Isso-related issues** – Copy and paste traceback into a ticket and provide
  some details of your usage.

.. _contribute-translations:

Translations
------------

Isso supports multiple languages and it is fairly easy to add new translations.
You can use the `english translation file`__ and `other translations`__ as a
referece and open a Pull Request.

You may notice some "weird" newlines in translations -- that's the separator
for pluralforms_ in the templating engine.

.. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/en.js
.. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/
.. _pluralforms: http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms

.. _contribute-docs:

Documentation
-------------

Documentation improvements are sorely needed. Anything that makes the
experience for a newcomer more pleasant is always welcome.
Please see the :doc:`documentation` page for more details.

.. _contribute-code:

Code contributions
------------------

You've chosen to make Isso better and that's great! Please follow this checklist when
contributing code:

.. _contribute-checklist:

.. note:: **Submitting a change**

    1. Write **proper commit messages** (see next paragraph)
    2. If adding features: **Add or amend tests** to cover the changes
    3. Run all **test suites** (see :doc:`/docs/technical-docs/testing`) and make
       sure they pass
    4. If docs changes needed: Update the :doc:`documentation <documentation>`
       accordingly.
    5. If it's a user-facing feature or an important bugfix, add ``CHANGES.rst``
       entry
    6. Add yourself to ``CONTRIBUTORS.txt``, if you like

.. _contribute-commitmsg:

How to write good commit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Mention the affected part in the title (e.g. ``setup.py``)
- Keep title under 50 characters if possible, at most 72
- Keep body under 80 characters of width
- Explain what the change does
- Link to related issues or references
- Ideally, how to verify that this commit does what it says

For example, this a **good commit:**

.. code-block::

    js: Postbox: Use labels rather than placeholders

    Placeholders are is meant to be a hint (an example input)
    for the user about what to enter into the field, but
    shouldn't be used in lieu of a <label>.

    See following links for further justification:
    - https://www.tpgi.com/html5-accessibility-chops-the-placeholder-attribute/
    - https://www.nngroup.com/articles/form-design-placeholders/
    - https://www.maxability.co.in/2016/01/03/placeholder-attribute-and-why-it-is-not-accessible/

    This commit is a reland of
    https://github.com/posativ/isso/pull/356 with a fix for the
    placeholder-replacement code in `isso.js` as reported in
    https://github.com/posativ/isso/issues/524

...while this is a **bad commit:**

.. code-block::

    Fix classes

It does not tell the reviewer which part is affected, why it is necessary or
why this particular way of doing things was chosen.
The `commento docs`_ have a more extensive explanation of good commits.

.. _commento docs: https://docs.commento.io/contributing/development-guidelines.html

Considerations when submitting changes
--------------------------------------

The following sections will help you decide how to tackle larger architectural
issues and help avoid wasted efforts for changes that are unlikely to be
accepted.

You do not have to read this whole section; the maintainers will give you
feedback in the review process. But if you want to be a nice and helpful
person, you can make the lives of the maintainers a lot easier.
These guidelines are here to help your thought process and hopefully make you
aware of a few aspects you might not have thought about yet.

Design philosophy / Zen of Isso
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Isso should not be a "move fast and break things" project.
- Be mindful of the users. They do not anxiously await a new release - they
  simply want their websites to work.
- Try to avoid breaking changes: People do not want to dig through changelogs
  to find out why suddenly their comment section is gone.

What kind of changes will be accepted?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As a rule, you want to make the life of the maintainers as easy as possible.
Removing cruft is good, as is improving tests or docs. Introducing new
features, possibly with new config options, should have good reasoning and is
harder to review.

What should I think about?

- Will everyone benefit from my contribution or is this just fixing my pet
  peeve/supporting my exotic use case?
- Will this add complexity? If many changes similar to mine are introduced, will
  this make the project more confusing and complex?
- Should this be done in a more generalized manner? As a hypothetical example,
  do not create a new toggle with ``is-submit-button-green`` or
  ``submit-button-color``, but rather create a mechanism by which the color of
  all buttons can be set.

If adding a new option/config:

- Is the option well-named? Can users already figure out what it does, without
  having to read the description?
- Is the option really necessary? Should the default behaviour be changed
  instead?
- Is the option well-documented? Is it clear what it does? Are the available
  choices well-documented?
- Is the option in the right config section?
- Backward compatibility

A config option is sort of a promise to users. They will be confused if it is
removed and their setup no longer works.

What is currently needed?
^^^^^^^^^^^^^^^^^^^^^^^^^

- **Improvements of test coverage** - really important for the project to move
  forward!
- Look at `open issues with label "needs-contributor"`__
- Look at `open issues with label "good-first-issue"`__
- Look at `open issues with label "needs-decision"`__ and chime in with your
  well thought-out opinion
- Look at `milestones`__ - the next release of Isso will be version 0.13, and
  you can help by looking for open issues and PRs that
  `contribute to 0.13 <https://github.com/posativ/isso/milestone/5>`_
- Nicer automated testing, via docker or GH actions, of most of the available
  setup options (fastcgi/proxy configs, docker, apachge/nginx, ...)

@posativ's wishlist:

- `Admin Web Interface <https://github.com/posativ/isso/issues/10>`_ –
  administration via email is cumbersome with a high amount of comments. A
  administration web interface should include the ability to:

  - Delete or activate comments matching a filter (e.g. name, email, ip address)
  - Close threads and remove threads completely

.. __: https://github.com/posativ/isso/labels/needs-contributor
.. __: https://github.com/posativ/isso/labels/good-first-issue
.. __: https://github.com/posativ/isso/labels/needs-decision
.. __: https://github.com/posativ/isso/milestones

Regarding fancy new CI tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Linters are fine, but please create sensible configs
- Nothing too "magic", AI-based
- Keep in mind that too many bots running will need constant updates and maintenance
- Nothing that compromises this project's integrity, by granting repo access to bots
- Nothing too "chatty" - it will just be ignored and increase the burden on
  maintainers even more

Complexity
^^^^^^^^^^

Isso started out as a fairly simple project, but it has grown over time.
It is built using many different technologies and moving parts

.. Try to avoid adding new dependencies to the project. Adding complexity makes it
.. exponentially harder to understand the breadth of components, makes it harder
.. to keep track of the growing list of external dependencies, and also means that
.. the maintainers will have to do even more work before merging your change - in
.. practice, they will probably not be able to find the time.

Below is a non-exhaustive list of tools, services, dependencies and
technologies Isso's contributors and maintainers need to at least peripherally
be aware of - that's a lot to demand of someone! Your aim should be to reduce
this complexity, not add to it.

.. hlist::
   :columns: 2

   * **Docs**

     -  apiDoc
     -  sphinx with reST syntax

   * **Python**

     -  Pallets project: werkzeug, jinja2, flask
     -  misaka (and changing config opts)
     -  bleach, html5lib
     -  Different python versions, OS versions
     -  setuptools, pip
     -  Python Package Index (PyPI) uploading

   * **Python testing**

     -  pytest (unit testing)
     -  coverage
     -  flake8

   * **Convenience tools**

     -  Docker
     -  Vagrant
     -  Ansible

   * **Javascript**

     -  Node.js
     -  npm
     -  package.json oddities
     -  webpack
     -  Jest
     -  puppeteer
     -  Browser compatibility and ES5/ES6 standards

   * **Development tools**

     -  make
     -  Github Actions

   * **Deployment options**

     -  ``isso run [opts]``
     -  Apache (``mod_wsgi``)
     -  Apache (``mod_fastcgi``)
     -  Apache (proxy)
     -  nginx (proxy)
     -  uwswgi
     -  gunicorn
     -  gevent

   * **Importers**

     -  Current disqus export format
     -  Current and past Wordpress export formats

---

## File: docs/docs/contributing/infrastructure.rst

Isso Project Infrastructure
===========================

Conceived initially as  Martin Zimmermann (`@posativ`_)'s nimble personal project,
Isso has grown to encompass a larger community of users and maintainers. With a
transition away from being controlled solely by Martin, the project
infrastructure is now largely community-owned.

This page documents the parts that make up the project and who is responsible
for them, in order for new or potential maintainers to get a better overview.

.. attention::

   We realize that many of our processes could use an overhaul and would
   benefit from much more automation. If you know how, please open a Pull
   Request or offer your help in an issue!

Website
-------

The project website used to be hosted at `posativ.org/isso`_, but now lives at
its own domain `isso-comments.de`_.

* The domain `isso-comments.de`_ is registered by `@ix5`_ through German registrar
  `netcup.de`_. Costs exactly 1.44€ each year so quite sustainable, but makes
  @ix5 a potential bus factor.
* Website content is served by GitHub Pages. The `sphinx-doc`_-built site is
  auto-deployed to `isso-comments.github.io`_ via a `GitHub Action`_ on every push
  to the Isso main repository. Requires appropriate ``A`` and ``CNAME`` records
  to GitHub's servers:

  .. code-block:: console

      $ dig www.isso-comments.de
      www.isso-comments.de.	300	IN	CNAME	isso-comments.github.io.
      isso-comments.github.io. 3600	IN	A	185.199.108.153
      isso-comments.github.io. 3600	IN	A	185.199.109.153
      isso-comments.github.io. 3600	IN	A	185.199.110.153
      isso-comments.github.io. 3600	IN	A	185.199.111.153

* The demo instance of the comment form (on the homepage) lives on `@ix5`_'s
  server at `comments.isso-comments.de`_ and consists of the latest ``isso``
  package from ``PyPI``, deployed via ``gunicorn``.
  The ansible role to set this up is available at `ansible-role-isso`_. The
  simple auto-reset feature to curtail vandalism is documented at
  `isso-demo-config`_.

.. _@posativ: https://github.com/posativ
.. _posativ.org/isso: https://posativ.org/isso
.. _isso-comments.de: https://isso-comments.de
.. _@ix5: https://github.com/ix5
.. _netcup.de: https://netcup.de
.. _sphinx-doc: https://www.sphinx-doc.org/
.. _isso-comments.github.io: https://github.com/isso-comments/isso-comments.github.io
.. _GitHub Action: https://github.com/isso-comments/isso/blob/master/.github/workflows/build-upload-docs.yml
.. _comments.isso-comments.de: https://comments.isso-comments.de
.. _ansible-role-isso: https://git.ix5.org/felix/ansible-role-isso
.. _isso-demo-config: https://github.com/isso-comments/isso-demo-config

Development
-----------

Development happens under the `isso-comments GitHub organisation`_, with the
main `isso-comments/isso`_ repository serving as the source for the Python
parts, Javascript client, website and documentation, API documentation as well
as CI/CD configuration.

The ``master`` branch has branch protections set up, requiring an approving
maintainer review before merging.

.. _isso-comments GitHub organisation: https://github.com/isso-comments
.. _isso-comments/isso: https://github.com/isso-comments/isso

Packaging
---------

Isso is released "officially" as an installable Python package on `PyPI`_
and as a docker image. Other distributors may package releases of Isso natively
for operating systems (e.g. for the Arch User repository or formerly Debian),
but support for these releases should be given by the packager.

.. _PyPI: https://pypi.org/project/isso/

PyPI (Python Package Index)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Release rights for the `isso PyPI`_ project are held by @jelmer, @posativ, @blatinier and @ix5.

.. _isso PyPI: https://pypi.org/project/isso/

Docker image
^^^^^^^^^^^^

The `ghcr.io/isso-comments/isso docker image`_ is rebuilt on every push to
``master``. Push rights for manually created tags (e.g. ``:release``) are
inherited from the main ``isso-comments/isso`` GitHub repository (toggle
``Inherit access from source repository`` turned on).

The `ghcr.io/isso-comments/isso-js-testbed`_ image for running ``Jest``- and
``puppet``-based unit and integration tests is rebuilt and pushed every week by
a GitHub Action.

.. _ghcr.io/isso-comments/isso docker image: https://github.com/isso-comments/isso/pkgs/container/isso
.. _ghcr.io/isso-comments/isso-js-testbed: https://github.com/orgs/isso-comments/packages/container/package/isso-js-testbed

Secrets
-------

There are some "`secrets`_" needed to make the auto-deploy feature for GitHub Pages work.

* The main ``isso-comments/isso`` repository holds a *private* key in the
  variable ``ACTIONS_DEPLOY_KEY`` (`link to action secrets`_).
* The deploy repository ``isso-comments/isso-comments.github.io`` for GitHub
  Pages is set up with a *public* deploy key (`link to deploy keys`_)
  corresponding to the action secrets private key, allowing actions running in
  the source repository to deploy code (the newly generated website) in this
  repository.

*(The direct links only work for maintainers with full repository access).*

The docker actions do not need to be outfitted with any special secrets since
the main repository is already set up as a source for "Actions access" with
write access (`link to package settings`_).

.. _link to action secrets: https://github.com/isso-comments/isso/settings/secrets/actions
.. _link to deploy keys: https://github.com/isso-comments/isso-comments.github.io/settings/keys
.. _secrets: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
.. _link to package settings: https://github.com/orgs/isso-comments/packages/container/isso/settings

Social
------

There exists an IRC channel (``#isso``) on `Libera.chat`_ but it is seldom
active and not used for coordination between maintainers. Most discussion
happens in public on GitHub Issues; for private communication among each other
regarding handover of project resources/keys (very rare) the maintainers have
so far used E-mail.

.. _Libera.chat: https://libera.chat/

---

## File: docs/docs/reference/client-config.rst

Client Configuration
====================

You can configure the client (the JS part) with custom data attributes,
preferably in the script tag which embeds the JS:

.. code-block:: html

    <script data-isso="/prefix/"
            data-isso-css="true"
            data-isso-css-url="null"
            data-isso-lang="ru"
            data-isso-max-comments-top="10"
            data-isso-max-comments-nested="5"
            data-isso-reveal-on-click="5"
            data-isso-sorting="newest"
            data-isso-avatar="true"
            data-isso-avatar-bg="#f0f0f0"
            data-isso-avatar-fg="#9abf88 #5698c4 #e279a3 #9163b6 ..."
            data-isso-vote="true"
            data-isso-vote-levels=""
            data-isso-page-author-hashes="f124cf6b2f01,7831fe17a8cd"
            data-isso-reply-notifications-default-enabled="false"
            src="/prefix/js/embed.js"></script>

Furthermore you can override the automatic title detection inside
the embed tag, as well as the thread ID, e.g.:

.. code-block:: html

    <section id="isso-thread" data-title="Foo!" data-isso-id="/path/to/resource"></section>

Overriding translation strings
------------------------------

Additionally, you can override any translation string for any language by adding
a ``data-isso-`` attribute that is equal to the translation key (found `here`__) with
``-text-[lang]`` appended to it. So, for example, if you want to override the
english translation of the ``postbox-notification`` message, you could add:

.. code-block:: html

    data-isso-postbox-notification-text-en="Select to be notified of replies to your comment"

.. __: https://github.com/isso-comments/isso/blob/master/isso/js/app/i18n/en.js

data-isso-* directives
------------------------

.. _data-isso:

data-isso
   Isso usually detects the REST API automatically, but when you serve the JS
   script on a different location, this may fail. Use ``data-isso`` to
   override the API location:

   .. code-block:: html

       <script data-isso="/isso" src="/path/to/embed.min.js"></script>

.. _data-isso-css-url:

data-isso-css-url
    Set URL from which to fetch ``isso.css``, e.g. from a CDN.
    Defaults to fetching from the API endpoint.

    .. code-block:: html

        <script src="..." data-isso-css-url="/path/to/isso.css"></script>

    Default: ``"{api-endpoint}/css/isso.css"``

.. _data-isso-css:

data-isso-css
    Set to ``false`` prevents Isso from automatically appending the stylesheet.

    .. code-block:: html

        <script src="..." data-isso-css="false"></script>

    Default: ``true``

.. _data-isso-lang:

data-isso-lang
    Always render the Isso UI in this language, ignoring what the
    user-agent says is the preferred language.  The default is to
    honor the user-agent's preferred language, and this can be
    specified explicitly by using ``data-isso-lang=""``.

    The value of this property should be a `BCP 47 language tag
    <https://tools.ietf.org/html/bcp47>`_, such as ``en``, ``ru``, or
    ``pt-BR``.
    Language tags are processed case-insensitively, and may use
    underscores as separators instead of dashes (e.g. ``pt_br`` is treated the
    same as same as ``pt-BR``).

    You can find a list of all supported languages by browsing the
    `i18n directory
    <https://github.com/isso-comments/isso/tree/master/isso/js/app/i18n>`_ of
    the source tree.

    Default: ``null``

.. _data-isso-default-lang:

data-isso-default-lang
    Render the Isso UI in this language when the user-agent does not
    specify a preferred language, or if the language it specifies is not
    supported.  Like :ref:`data-isso-lang`, the value of this property should
    be a `BCP 47 language tag <https://tools.ietf.org/html/bcp47>`_,
    such as ``en``, ``ru``, or ``pt-BR``.

    If you specify both ``data-isso-default-lang`` and ``data-isso-lang``,
    ``data-isso-lang`` takes precedence.

    Default: ``"en"``

    .. versionadded:: 0.12.6

.. _data-isso-max-comments-top:

data-isso-max-comments-top
    Number of top level comments to show by default. If some comments are not
    shown, an "X Hidden" link is shown.

    Set to ``"inf"`` to show all, or ``"0"`` to hide all.

    Default: ``"inf"``

.. _data-isso-max-comments-nested:

data-isso-max-comments-nested
    Number of nested comments to show by default. If some comments are not
    shown, an "X Hidden" link is shown.

    Set to ``"inf"`` to show all, or ``"0"`` to hide all.

    Default: ``5``

.. _data-isso-reveal-on-click:

data-isso-reveal-on-click
    Number of comments to reveal on clicking the "X Hidden" link.

    Default: ``5``

.. _data-isso-avatar:

data-isso-avatar
    Enable or disable avatar generation. Ignored if gravatar is enabled on
    server side, since gravatars will take precedence and disable avatar
    generation.

    Default: ``true``

.. _data-isso-avatar-bg:

data-isso-avatar-bg
    Set avatar background color. Any valid CSS color will do.

    Default: ``"#f0f0f0"``

.. _data-isso-avatar-fg:

data-isso-avatar-fg
    Set avatar foreground color. Up to 8 colors are possible. The default color
    scheme is based in `this color palette <http://colrd.com/palette/19308/>`_.
    Multiple colors must be separated by space. If you use less than eight colors
    and not a multiple of 2, the color distribution is not even.

    Default: ``"#9abf88 #5698c4 #e279a3 #9163b6 #be5168 #f19670 #e4bf80 #447c69"``

.. _data-isso-vote:

data-isso-vote
    Enable or disable voting feature on the client side.

    Default: ``true``

.. _data-isso-vote-levels:

data-isso-vote-levels
    List of vote levels used to customize comment appearance based on score.
    Provide a comma-separated values (eg. ``"0,5,10,25,100"``) or a JSON array (eg. ``"[-5,5,15]"``).

    For example, the value ``"-5,5"`` will cause each ``isso-comment`` to be given one of these 3 classes:

    - ``isso-vote-level-0`` for scores lower than ``-5``
    - ``isso-vote-level-1`` for scores between ``-5`` and ``4``
    - ``isso-vote-level-2`` for scores of ``5`` and greater

    These classes can then be used to customize the appearance of comments (eg. put a star on popular comments)

    Default: ``null``

.. _data-isso-page-author-hashes:

data-isso-page-author-hashes
    Provide the hash (or list of hashes) of the current page's author. Any
    comments made by those authors will be given the ``isso-is-page-author``
    class. This can be styled using CSS.

    The hash of a user can be found by checking the ``data-hash`` parameter on the
    ```` tag containing their comment. This is what the element looks like:

    .. code-block:: html

        

    According to this example, your script tag would look something like this:

    .. code-block:: html

        <script src="..." data-isso-page-author-hashes="41faef0a49fc"></script>

    When adding multiple hashes to support multiple page authors, separate the
    hashes by a command and/or space. All of the following are acceptable
    (although the hashes are made up):

    - ``data-isso-page-author-hashes="86g7n8g67nm,8m787mg8"``
    - ``data-isso-page-author-hashes="86g7n8g67nm 8m787mg8"``
    - ``data-isso-page-author-hashes="86g7n8g67nm, 8m787mg8"``

    For example, these CSS rules make the page author's name a sort of
    turquoise color, and the comment's background a lighter version of that:

    .. code-block:: css

        .isso-comment.isso-is-page-author > .isso-text-wrapper {
            background-color: #bae0ea;
        }

        .isso-comment.isso-is-page-author > .isso-text-wrapper > .isso-comment-header > .isso-author {
            color: #19798d;
        }

    Default: ``null``

    .. versionadded:: 0.13


.. _data-isso-reply-notifications-default-enabled:

data-isso-reply-notifications-default-enabled
    Set to ``true`` to make the reply notifications checkbox on the postbox be
    checked by default. Otherwise, the user will have to manually opt-in to
    reply notifications.

    This setting will have no effect if ``reply-notifications`` are not enabled
    on the server.

    Default: ``false``

    .. versionadded:: 0.13


.. _data-isso-sorting:

data-isso-sorting
    Sort thread comments by specified sorting method.

    Possible sorting methods:

    - ``newest``: Bring newest comments to the top
    - ``oldest``: Bring oldest comments to the top
    - ``upvotes``: Bring most liked comments to the top

    Default sorting is ``oldest``. As of 0.13.1, replies are always sorted as
    ``oldest``.

    .. versionadded:: 0.13.1

Deprecated Client Settings
--------------------------

In earlier versions the following settings had to mirror the
corresponding settings in the server configuration, but they are now
read out from the server automatically.

data-isso-reply-to-self
    .. deprecated:: 0.12.6

    Set to ``true`` when spam guard is configured with ``reply-to-self = true``.

data-isso-require-author
    .. deprecated:: 0.12.6

    Set to ``true`` when spam guard is configured with ``require-author = true``.

data-isso-require-email
    .. deprecated:: 0.12.6

    Set to ``true`` when spam guard is configured with ``require-email = true``.

data-isso-reply-notifications
    .. deprecated:: 0.12.6

    Set to ``true`` when reply notifications is configured with ``reply-notifications = true``.

data-isso-gravatar
    .. deprecated:: 0.12.6

    Set to ``true`` when gravatars are enabled with ``gravatar = true`` in the
    server configuration.

data-isso-feed
    .. deprecated:: 0.13

    Enable or disable the addition of a link to the feed for the comment
    thread. The link will only be valid if the appropriate setting, in
    ``[rss]`` section, is also enabled server-side.