Merge pull request #864 from ix5/docs-markdown-rendering

[docs] Add Markdown rendering explanation, refs, more styling of tables and other elements
isso-comments · May 7, 2022 · 7e621d9 · 7e621d9
2 parents 2c4d472 + 10fd82e
commit 7e621d9
Show file tree

Hide file tree

Showing 5 changed files with 216 additions and 14 deletions.
diff --git a/docs/_static/css/site.css b/docs/_static/css/site.css
@@ -331,15 +331,33 @@ main {
           margin: 0; }
     main .docs table.hlist * {
       vertical-align: top; }
+    main .docs table.docutils {
+      margin: 1em 0;
+      border-collapse: collapse; }
+      main .docs table.docutils th, main .docs table.docutils td {
+        padding: 0.4em 0.5em;
+        border: 1px solid #d3d3d3;
+        border-collapse: collapse; }
     main .docs .versionadded,
     main .docs .versionchanged,
     main .docs .deprecated {
       margin: 0.3em 0; }
-      main .docs .versionadded span,
-      main .docs .versionchanged span,
-      main .docs .deprecated span {
-        background: lightyellow;
-        font-style: italic; }
+      main .docs .versionadded span.added,
+      main .docs .versionadded span.changed,
+      main .docs .versionchanged span.added,
+      main .docs .versionchanged span.changed,
+      main .docs .deprecated span.added,
+      main .docs .deprecated span.changed {
+        background: lightyellow; }
+      main .docs .versionadded span.deprecated,
+      main .docs .versionchanged span.deprecated,
+      main .docs .deprecated span.deprecated {
+        background: #ffe0e0; }
+      main .docs .versionadded span.versionmodified,
+      main .docs .versionchanged span.versionmodified,
+      main .docs .deprecated span.versionmodified {
+        font-style: italic;
+        margin-right: 0.6em; }
   main .vcs-edit {
     font-size: 1.16em;
     line-height: 1.16em;
@@ -389,11 +407,11 @@ main {
       background: #f29f97; }
       .admonition.danger .admonition-title:before, .admonition.error .admonition-title:before {
         color: #f29f97; }
-  .admonition.hint, .admonition.important, .admonition.tip {
+  .admonition.hint, .admonition.important, .admonition.tip, .admonition.seealso {
     background: #dbfaf4; }
-    .admonition.hint .admonition-title, .admonition.important .admonition-title, .admonition.tip .admonition-title {
+    .admonition.hint .admonition-title, .admonition.important .admonition-title, .admonition.tip .admonition-title, .admonition.seealso .admonition-title {
       background: #1abc9c; }
-      .admonition.hint .admonition-title:before, .admonition.important .admonition-title:before, .admonition.tip .admonition-title:before {
+      .admonition.hint .admonition-title:before, .admonition.important .admonition-title:before, .admonition.tip .admonition-title:before, .admonition.seealso .admonition-title:before {
         color: #1abc9c; }
   .admonition.note {
     background: #e7f2fa; }

diff --git a/docs/_static/css/site.scss b/docs/_static/css/site.scss
@@ -416,15 +416,33 @@ main {
         vertical-align: top;
     }
 
+    table.docutils {
+      margin: 1em 0;
+      border-collapse: collapse;
+
+      th, td {
+        padding: 0.4em 0.5em;
+        border: 1px solid $code-block-border-color;
+        border-collapse: collapse;
+      }
+    }
+
     .versionadded,
     .versionchanged,
     .deprecated {
 
         margin: 0.3em 0;
 
-        span {
+        span.added,
+        span.changed {
             background: $versionchanged;
+        }
+        span.deprecated {
+            background: #ffe0e0;
+        }
+        span.versionmodified {
             font-style: italic;
+            margin-right: 0.6em;
         }
     }
   }
@@ -505,7 +523,7 @@ main {
       }
     }
   }
-  &.hint, &.important, &.tip {
+  &.hint, &.important, &.tip, &.seealso {
     background: #dbfaf4;
 
     .admonition-title {

diff --git a/docs/docs/reference/markdown-config.rst b/docs/docs/reference/markdown-config.rst
@@ -0,0 +1,158 @@
+Configure how comments are rendered
+===================================
+
+You can use the :ref:`configure-markup` section in your configuration file to
+influence how the `Markdown`_ syntax in comments is rendered and displayed
+to the user.
+
+Per Isso's defaults, commenters can use **standard Markdown syntax**, **minus
+footnotes and tables**
+(see :ref:`below <available-markdown-options>` on how to activate them).
+
+.. _Markdown: https://daringfireball.net/projects/markdown/
+
+Because users can enter untrusted, potentially **malicious text** into the
+comment box, Isso applies some safety precautions so that the rendered comments
+do not contain e.g. malware ``<script>`` tags or ``iframes``. You should not
+blindly change these defaults to allow more elements without knowing what you
+are doing.
+
+Plain HTML in comments
+----------------------
+
+Per Isso's defaults, commenters can also enter plain HTML instead of or inside
+of Markdown text.
+
+To disallow user-entered plain HTML, add ``skip-html`` to ``[markup] flags``.
+
+.. todo:: Maybe replace this list with a link to ``isso.conf``?
+
++-------------------------------------------+-----------------------------------+
+| These HTML tags are allowed by default:   | These HTML *attributes* allowed   |
+|                                           | by default:                       |
+| ``<a>``, ``<blockquote>``, ``<br>``,      |                                   |
+| ``<code>``, ``<del>``, ``<em>``,          | ``align`` (for tables) and        |
+| ``<h1>``, ``<h2>``, ``<h3>``, ``<h4>``,   | ``href`` (for ``<a href="...">``) |
+| ``<h5>``, ``<h6>``, ``<hr>``, ``<ins>``,  |                                   |
+| ``<li>``, ``<ol>``, ``<p>``, ``<pre>``,   |                                   |
+| ``<strong>``, ``<table>``, ``<tbody>``,   |                                   |
+| ``<td>``, ``<th>``, ``<thead>``,          |                                   |
+| ``<ul>``.                                 |                                   |
++-------------------------------------------+-----------------------------------+
+
+Elements and attributes not in the allowed list will just be stripped.
+``<foo bar=1>text</foo>`` will simply become ``text``.
+
+.. note:: Keep in mind that removing an element from the allowed tags will not
+   only disallow commenters from entering it as a plain HTML tag, but also
+   remove formatting from any markdown that would generate the tag.
+
+   An example: Allowed elements are ``['a', 'strong']``. Then ``Some *text*``
+   would not be rendered in italics since the ``em`` element would be
+   forbidden.
+
+Line breaks
+-----------
+
+By default, Markdown requires two new lines to create a paragraph break.
+E.g. this block:
+
+.. code-block:: markdown
+
+   This is a quite **long paragraph** that spans multiple lines,
+   which is split over multiple lines in the Markdown source code.
+
+   Thus, the width remains under about 80 characters and the writer does not
+   have to scroll so far to the right.
+
+will be rendered as:
+
+    This is a quite **long paragraph** that spans multiple lines,
+    which is split over multiple lines in the Markdown source code.
+
+    Thus, the width remains under about 80 characters and the writer does not
+    have to scroll so far to the right.
+
+Set ``hard-wrap`` in ``[markup] flags`` to only require a single newline to
+create a line break (``<br>``):
+
+.. code-block:: markdown
+
+   One line.
+   Another line.
+
+will then be rendered as:
+
+   | One line.
+   | Another line.
+
+
+Defaults and available options
+------------------------------
+
+.. _available-markdown-options:
+
+.. note:: Make sure to use e.g. ``fenced-code`` (with a ``-`` dash) instead of
+   ``fenced_code`` (underline) to refer to extension names.
+
+The following behavior is **enabled by default:**
+
+.. role::  raw-html(raw)
+    :format: html
+
++----------------------------------------------------------+-------------------+
+| Explanation                                              | Extension name    |
++==========================================================+===================+
+| Automatically convert ``http://`` links and email        | ``autolink``      |
+| addresses into clickable links, even if commenters did   |                   |
+| not format them using ``[text](http://link.site)``       |                   |
++----------------------------------------------------------+-------------------+
+| Blocks that are surrounded by triple backticks (```````) | ``fenced-code``   |
+| at the beginning and at the end are rendered as code     |                   |
+| blocks, without needing to be indented.                  |                   |
++----------------------------------------------------------+-------------------+
+| Text surrounded in two ``~`` gets a line through:        | ``strikethrough`` |
+| ``Text ~~deleted~~``                                     |                   |
+| :raw-html:`&rarr; Text <del>deleted</del>`               |                   |
++----------------------------------------------------------+-------------------+
+| Text after the ``^`` character is rendered as            | ``superscript``   |
+| "superscript": ``Intelligence^2`` :raw-html:`&rarr;`     |                   |
+| Intelligence\ :sup:`2`.                                  |                   |
++----------------------------------------------------------+-------------------+
+
+The following **additional options** are available:
+
++----------------------------------------------------------+---------------------------+
+| Explanation                                              | Extension name            |
++==========================================================+===========================+
+| Ignore indented code blocks                              | ``disable-indented-code`` |
++----------------------------------------------------------+---------------------------+
+| Parse inline LaTeX-style math blocks, such as            | ``math``                  |
+| inline ``$equations$`` or display ``$$equations$$``      |                           |
++----------------------------------------------------------+---------------------------+
+| Normally, everything between two ``_underscores_`` would | ``no-intra-emphasis``     |
+| be rendered with *emphasis*. This option disables        |                           |
+| parsing of underscores *within* words.                   |                           |
+| ``A_good_day`` :raw-html:`&rarr;` A_good_day,            |                           |
+| not A\ *good*\ day                                       |                           |
++----------------------------------------------------------+---------------------------+
+| Parse markdown footnotes. Not recommended because        | ``footnotes``             |
+| multiple footnotes by different commenters on the same   |                           |
+| page could clash due to duplicate links to footnotes.    |                           |
++----------------------------------------------------------+---------------------------+
+| Use two ``=`` signs like ``==this==`` to highlight text  | ``highlight``             |
++----------------------------------------------------------+---------------------------+
+| Text inside quotes gets a special "quote" class.         | ``quote``                 |
+| Perhaps useful for styling in CSS                        |                           |
++----------------------------------------------------------+---------------------------+
+| Enable Markdown tables                                   | ``tables``                |
++----------------------------------------------------------+---------------------------+
+| Instead of ``_underscore`` resulting in *emphasis*,      | ``underline``             |
+| the resulting text will be... underlined                 |                           |
++----------------------------------------------------------+---------------------------+
+
+.. todo:: ``no-intra-emphasis`` should be made default
+
+.. seealso::
+    The `flask-misaka docs <https://flask-misaka.readthedocs.io/en/latest/#options>`_
+    also have a good explanation of what each extension options does.
diff --git a/docs/docs/reference/server-config.rst b/docs/docs/reference/server-config.rst
@@ -385,12 +385,13 @@ Markup
 
 Customize markup and sanitized HTML. Currently, only Markdown (via Misaka) is
 supported, but new languages are relatively easy to add.
+For a more detailed explanation, see :doc:`/docs/reference/markdown-config`.
 
 .. code-block:: ini
 
     [markup]
     options = strikethrough, superscript, autolink, fenced-code
-    flags = skip-html, escape, hard-wrap
+    flags =
     allowed-elements =
     allowed-attributes =
 
@@ -399,12 +400,12 @@ options
     extension options can be used there, separated by comma, either by their
     name (``fenced-code``) or as ``EXT_FENCED_CODE``.
 
-    The `flask-misaka docs <https://flask-misaka.readthedocs.io/en/latest/#options>`_
-    have a good explanation of what each extension options does.
-
     Note: Use e.g. ``fenced-code`` (with a ``-`` dash) instead of
     ``fenced_code`` (underline) to refer to extension names.
 
+    For a more detailed explanation, see
+    :ref:`Markdown Configuration: Extensions <available-markdown-options>`
+
     Default: ``strikethrough, superscript, autolink, fenced-code``
 
 flags
@@ -413,6 +414,8 @@ flags
     can be used here, separated by comma, either by their name (``hard-wrap``)
     or as e.g. ``HTML_HARD_WRAP``.
 
+    For a more detailed explanation, see :doc:`/docs/reference/markdown-config`.
+
     Default: (empty)
 
     .. versionadded:: 0.12.4
@@ -425,6 +428,8 @@ allowed-elements
     ``ol``, ``p``, ``pre``, ``strong``, ``table``, ``tbody``, ``td``, ``th``,
     ``thead`` and ``ul`` are allowed.
 
+    For a more detailed explanation, see :doc:`/docs/reference/markdown-config`.
+
     .. warning::
 
        This option (together with ``allowed-attributes``) is frequently
@@ -444,6 +449,8 @@ allowed-attributes
     By default, only ``align`` and ``href`` are allowed (same caveats as for
     ``allowed-elements`` above apply)
 
+    For a more detailed explanation, see :doc:`/docs/reference/markdown-config`.
+
     Default: (empty)
 
 .. note:: To allow images in comments, you need to add

diff --git a/docs/docs/toc.rst b/docs/docs/toc.rst
@@ -19,6 +19,7 @@
    Installation <reference/installation>
    Server Configuration <reference/server-config>
    Client Configuration <reference/client-config>
+   Markdown Configuration <reference/markdown-config>
    Deployment <reference/deployment>
    Multiple Sites & Sub-URI <reference/multi-site-sub-uri>
    Server API <reference/server-api>