isso Documentation

File: README.md Copy Chapter

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.

Features Copy Chapter

• 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 for a live demo, more
details and documentation.

Screenshot Copy Chapter

Getting started Copy Chapter

Requirements Copy Section

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

Install Isso from PyPi:

pip install isso

Then, follow the Quickstart guide.

If you're stuck, follow the Install guide,
see Troubleshooting and browse
the the full documentation.

Docker Copy Chapter

A Docker image with the latest stable release is provided at
ghcr.io/isso-comments/isso:latest. See
Using Docker.

Contributing Copy Chapter

• Pull requests are very much welcome! These might be
  good first issues
• See Ways to Contribute
• Translate

Development Copy Section

Refer to the docs for
Installing from Source.

Help Copy Section

• Join #isso via Matrix or via IRC on
  Libera.Chat
• Ask a question on GitHub Discussions.

License Copy Chapter

MIT, see LICENSE.

File: docs/docs/guides/advanced-integration.rst Copy Chapter

Advanced integration

Comment counter Copy Chapter

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 Copy Chapter

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 Copy Chapter

Frequently asked questions

Why SQLite3? Copy Chapter

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? Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Tips & Tricks

Sections covered in this document:

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

Lazy-loading on scroll Copy Chapter

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 Copy Chapter

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 protected]",
                "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": "[email protected]",
                "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 Copy Chapter

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 Copy Chapter

.. 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 = [email protected]
website = https://chezsoi.org/lucas/blog

Delete IP addresses weekly Copy Chapter

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 Copy Chapter

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 Copy Chapter

Troubleshooting

For uberspace users Copy Chapter

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 Copy Chapter

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? Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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) Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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

  text Copy

  $ 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

.. _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 Copy Chapter

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.