Consistent markdown parsing, docs on markdown and display settings

doc/admin/installation/docker_smallscale.rst

@@ -239,6 +239,8 @@ Restarting the service can take a few seconds, especially if the update requires
 Replace ``stable`` above with a specific version number like ``1.0`` or with ``latest`` for the development
 version, if you want to.
 
+.. _`docker_plugininstall`:
+
 Install a plugin
 ----------------
 

doc/admin/installation/manual_smallscale.rst

@@ -276,6 +276,8 @@ To upgrade to a new pretix release, pull the latest code changes and run the fol
     # systemctl restart pretix-web pretix-worker
 
 
+.. _`manual_plugininstall`:
+
 Install a plugin
 ----------------
 

doc/user/events/display.rst

@@ -0,0 +1,42 @@
+Display settings
+================
+
+The settings at "Settings" → "Display" allow you to customize the appearance of your ticket shop.
+
+.. thumbnail:: ../../screens/event/settings_display.png
+   :align: center
+   :class: screenshot
+
+The upper part of the page contains settings that you always need to set specifically for your event. Those are
+currently::
+
+Logo image
+    This logo will be shown as a banner above your shop. If you set it, the event name and date will no longer be
+    displayed by the shop, so we suggest to include them in the image yourself. The maximal height of the image is
+    120 pixels and if you want to use the full width, make your image 1140 pixels wide. If the user's screen is
+    smaller, the logo will be scaled down automatically, so it should still be legigible at smaller sizes.
+
+Frontpage text
+    This text will be shown on the front page of your ticket shop, above the list of products. You can use it to explain
+    your product types, give more information on the event or for other general notices.
+    You can use :ref:`Markdown syntax <markdown-guide>` in this field.
+
+Show variations of a product expanded by default
+    If this is not checked, a product with variations will be shown as one row in the show by default and will expand
+    into multiple rows once it is clicked on. With this box checked, the variations will be shown as multiple rows
+    right from the beginning.
+
+
+The lower part of the page contains settings that you can **either** set on organizer-level for all your events **or**
+override for this single event individually. Those are:
+
+Primary color
+    This color will be used for links, buttons, and other design elements throughout your shop and emails sent to your
+    customers. We suggest not choosing something to light, since text in that color should be readable on a white
+    background and white text should be readable on a background of this color.
+
+Font
+    Choose one of multiple fonts to use for your web shop.
+
+.. note:: Both the color and font settings can take a few seconds up to a few minutes before they become active on your
+          shop.

doc/user/events/plugins.rst

@@ -0,0 +1,20 @@
+Configuring plugins
+===================
+
+Plugins are optional parts of pretix that can be installed to extend the available functionality and that can be turned
+on or off completely for every event. For your event, a number of plugins might be active already, but you can unlock
+even more functionality by going to "Settings" → "Plugins" and enable more of them, if you need.
+
+.. thumbnail:: ../../screens/event/settings_plugins.png
+   :align: center
+   :class: screenshot
+
+For each plugin, you will find a short description as well as an Enable/Disable button. The pretix website has
+`an overview`_ of available plugins and more details of them. If you are on the pretix.eu hosted service, look for
+the "pretix Hosted" badge in the plugin list to learn which ones are supported there.
+
+If you are running pretix on your own server, refer to the installation manual of your installation type to learn
+how to install additional plugins (:ref:`manual <manual_plugininstall>` or :ref:`Docker <docker_plugininstall>`).
+
+.. _an overview: https://pretix.eu/about/en/plugins
+

doc/user/events/settings.rst

@@ -6,4 +6,6 @@ Configuring an event
 
    subevents
    ../payments/index
+   plugins
+   display
    taxes

doc/user/index.rst

@@ -11,4 +11,5 @@ wanting to use pretix to sell tickets.
    events/create
    events/settings
    events/widget
-   faq
+   faq
+   markdown

doc/user/markdown.rst

@@ -0,0 +1,166 @@
+.. _markdown-guide:
+
+Markdown Guide
+==============
+
+What is markdown?
+-----------------
+
+In many places of your shop, like frontpage texts, product descriptions and email texts, you can use
+`Markdown`_ to create links, bold text, and other formatted content. Markdown is a good middle-ground
+since it is way easier to learn than languages like HTML but allows all basic formatting options required
+for text in those places.
+
+Formatting rules
+----------------
+
+Simple text formatting
+""""""""""""""""""""""
+
+To set a text in italics, you can put it in asterisks or underscores. For example,
+
+.. code-block:: markdown
+
+    Please *really* pay your _ticket_.
+
+will become:
+
+    Please *really* pay your _ticket_.
+
+If you set double asterisks or underscores, the text will be printed in bold. For example,
+
+.. code-block:: markdown
+
+    This is **important**.
+
+will become:
+
+    This is **important**.
+
+You can also display, for example:
+
+.. code-block:: markdown
+
+    Input this `exactly like this`.
+
+You will get:
+
+    Input this ``exactly like this``.
+
+Links
+"""""
+
+You can create a link by just pasting it in, e.g.
+
+.. code-block:: markdown
+
+    Check this on https://en.wikipedia.org
+
+will become:
+
+    Check this on https://en.wikipedia.org
+
+However, if you want to control the text of the link, you can put the text of the link in ``[]`` brackets and the
+link target in ``()`` parentheses, like this:
+
+.. code-block:: markdown
+
+    Check this on [Wikipedia](https://en.wikipedia.org).
+
+This will yield:
+
+    Check this on `Wikipedia`_
+
+All links created with pretix Markdown syntax will open in a new tab.
+
+Lists
+"""""
+
+You can create un-numbered lists by prepending the lines with asterisks.
+
+.. code-block:: markdown
+
+    * First item
+    * Second item with a text that is too long to
+      fit in a line
+    * Third item
+
+will become:
+
+    * First item
+    * Second item with a text that is too long to
+      fit in a line
+    * Third item
+
+You can also use numbers as list items
+
+.. code-block:: markdown
+
+    1.  Red
+    2.  Green
+    3.  Blue
+
+to get
+
+    1.  Red
+    2.  Green
+    3.  Blue
+
+Headlines
+"""""""""
+
+To create a headline, prepend it with ``#`` for the main headline, ``##`` for a headline of the second level,
+and so on. For example:
+
+.. code-block:: markdown
+
+    # Headline 1
+    ## Headline 2
+    ### Headline 3
+    #### Headline 4
+    ##### Headline 5
+    ###### Headline 6
+
+We do not recommend using headlines of the first level, as pretix will already set the name of your event as a level-1
+headline of the page and HTML pages should have only one headline on the first level.
+
+You can also use
+
+.. code-block:: markdown
+
+    *****
+
+to create a horizontal line, like the following:
+
+.. raw:: html
+
+    <hr>
+
+Using HTML
+----------
+
+You can also directly embed HTML code, if you want, although we recommend
+using Markdown, as it enables e.g. people using text-based email clients
+to get a better plain text representation of your text. Note however, that for
+security reasons you can only use the following HTML elements::
+
+    a, abbr, acronym, b, br, code, div, em, h1, h2,
+    h3, h4, h5, h6, hr, i, li, ol, p, span, strong,
+    table, tbody, td, thead, tr, ul
+
+Additionally, only the following attributes are allowed on them::
+
+    <a href="…" title="…">
+    <abbr title="…">
+    <acronym title="…">
+    <table width="…">
+    <td width="…" align="…">
+    <div class="…">
+    <p class="…">
+    <span class="…">
+
+All other elements and attributes will be stripped during parsing.
+
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+.. _Wikipedia: https://en.wikipedia.org

src/pretix/base/services/mail.py

@@ -16,6 +16,7 @@ from pretix.base.i18n import language
 from pretix.base.models import Event, Invoice, InvoiceAddress, Order
 from pretix.base.services.invoices import invoice_pdf_task
 from pretix.base.signals import email_filter
+from pretix.base.templatetags.rich_text import markdown_compile
 from pretix.celery_app import app
 from pretix.multidomain.urlreverse import build_absolute_uri
 
@@ -210,11 +211,8 @@ def render_mail(template, context):
         body = str(template)
         if context:
             body = body.format_map(TolerantDict(context))
-        body_md = bleach.linkify(bleach.clean(markdown.markdown(body), tags=bleach.ALLOWED_TAGS + [
-            'p', 'pre'
-        ]))
     else:
         tpl = get_template(template)
         body = tpl.render(context)
-        body_md = bleach.linkify(markdown.markdown(body))
+    body_md = bleach.linkify(markdown_compile(body))
     return body, body_md

src/pretix/base/templatetags/rich_text.py

@@ -35,12 +35,14 @@ ALLOWED_TAGS = [
     'th',
     'div',
     'span',
+    'hr',
     'h1',
     'h2',
     'h3',
     'h4',
     'h5',
     'h6',
+    # Update doc/user/markdown.rst if you change this!
 ]
 
 ALLOWED_ATTRIBUTES = {
@@ -52,6 +54,7 @@ ALLOWED_ATTRIBUTES = {
     'div': ['class'],
     'p': ['class'],
     'span': ['class'],
+    # Update doc/user/markdown.rst if you change this!
 }
 
 
@@ -72,15 +75,28 @@ def abslink_callback(attrs, new=False):
     return attrs
 
 
+def markdown_compile(source):
+    return bleach.clean(
+        markdown.markdown(
+            source,
+            extensions=[
+                'markdown.extensions.sane_lists',
+                # 'markdown.extensions.nl2br',  # TODO: Enable, but check backwards-compatibility issues e.g. with mails
+            ]
+        ),
+        tags=ALLOWED_TAGS,
+        attributes=ALLOWED_ATTRIBUTES
+    )
+
+
 @register.filter
 def rich_text(text: str, **kwargs):
     """
     Processes markdown and cleans HTML in a text input.
     """
     text = str(text)
-    body_md = bleach.linkify(bleach.clean(
+    body_md = bleach.linkify(
-        markdown.markdown(text),
+        markdown_compile(text),
-        tags=ALLOWED_TAGS,
+        callbacks=DEFAULT_CALLBACKS + ([safelink_callback] if kwargs.get('safelinks', True) else [abslink_callback])
-        attributes=ALLOWED_ATTRIBUTES,
+    )
-    ), callbacks=DEFAULT_CALLBACKS + ([safelink_callback] if kwargs.get('safelinks', True) else [abslink_callback]))
     return mark_safe(body_md)