# Hyperkitty’s Email Rendering

Hyperkitty supports rich text rendering of Emails. Due to the fact the most people writing emails aren’t always aware that they are writing markdown, a prime philosophy of renderer is to prevent common plain-text to be mangled by rendering them as markdown.

Hyperkitty currently recognizes some rules that are used to parse the content of an email and render them as HTML with some CSS styling applied.

## Enabling Markdown Rendering

In Postorius UI, under Setttings -> Archiving -> Archive Rendering Mode, MailingList owners can choose between `Plain Text` and `Markdown text`.

Hyperkitty will use that to choose between the simple text renderer and markdown renderer.

## Text Renderer

Text renderer is the default renderer for the Emails since the default value of `archive_rendering_mode` setting for MailingLists is `text`. Text renderer supports the following rules only:

- Signature Rule

- PGP Signature Rule

- Autolink Rule

- Quote Rule

## Markdown Renderer

Markdown renderer support all the rendering rules mentioned in the Rendering Rules section below.

Added in version 1.3.4.

## Rendering Rules

Rules are essentially markup that are given special meaning such that they affect how the rendered text looks. Apart from well known Markdown rules (which are documented later in this page), there are some other rules that is supported by Hyperkitty’s renderer that make sense in the context of an Email.

### Signature Rule

Email signatures are often delimited by `--<SPACE>\n`. That is recognized as the boundary of the email and `hyperkitty.lib.renderer.plugin_signature()` parses that to produce a greyed out signature at the bottom of the email. An empty space after two dashes `--` is important and used as a standard email signature delimiter.

For example, something like:

    --
    Thanks,
    My Name
    http://example.com

### PGP Signature Rule

PGP signature rule recognizes inline PGP signatures that looks like this:

    ----BEGIN PGP SIGNED MESSAGE-----
    This is the text.
    -----BEGIN PGP SIGNATURE-----
    iQEXYZXYZ
    -----END PGP SIGNATURE-----

It is parsed and collapsed into a paragraph with a quote switch (`...PGP SIGNATURE...`) to expand the collapsed signature.

### Autolink Rule

This recognizes the URLs in the text which may or may not be included in angle brackets (`<http://example.com>`) and converts them to Hyperlinks. It will also truncate the text to 76 characters with following `...` characters if the length of the URL is longer than 76 characters.

This rule will also convert Email addresses into `mailto:aperson@example.com` URLs. It does not verify the validity of the Email address or even if the email address is a valid email address. The parsing is naive in many ways.

### Quote Rule

Or, Blockquote rule. This rule recognizes the lines starting with one or more `>` and converts them to blockquotes. They are also collapsed with a switch (`...`) for expanding and collapsing each section. Hyperkitty currently will parse upto 6 levels of nested quotes.

A different color styling is provided for each level of blockquote to make it easy to differentiate between a user’s reply and the previous user’s reply and so on and so forth.

For example, each level is indicated with a `>`:

    > This is level 1 quote
    > > This is Level 2 quote
    > > > This level 3 quote.

Each of them are collapsed with their own quote switch (`...`) to expand or collapse them.

The rendering of the blockquote can often times be found to be buggy, where text from a higher level quoting will appear under lower level quote when there are sentence breaks. Like for example:

    > > > This line of sentence will be broken unintentionally
    > > into the lower
    > > > level because of the improper folding of the email text
    > > by
    > > > some of the email clients.

This type of text will appear with a mixed level of quoting and can often times be very hard to read. This is caused by email client adding hard line breaks in the sentences when replying which makes it impossible to differentiate between the level of quote.

Hyperkitty’s current parser is unable to deal with these embarrassing quote wraps and will unfortunately present the text as mixed levels of quotes. As the current parser evolves, it might be possible to provide a better rendering experience for this with some heuristics.

### Image Rule

Remote image support for Hyperkitty is optional and disabled by default due to the fact that they can often be used to track users. Hyperkitty also doesn’t have support to upload attachments when replying from web interface, which makes it hard to support inline images.

To enable the support for images, administrators can add `HYPERKITTY_RENDER_INLINE_IMAGE = True` to Hyperkitty’s `settings.py`.

The default value of above setting is `False` and all Markdown image syntax is just ignored. If the above setting is set to True, the images are rendered inline with the text.

    ![Image's alt text](http://image.com/file.png "Image Title")

### Lists

    * List Items
    * List Item 2
      * List Item 3
      * List Item 4

    - List Item
    - List Item 2

### Bold

    **Bold Text**

### Italics

    *Italics*

### Horizontal Rule

    ---

    ***

### Code

    `inline code for text`

    ```
    Multi-line code segment
    ```

        Code can also be indented by 4 spaces without any backticks.

### Hyperlink

    [Text](https://url)

    [Text][1]

    [1]: https://URL

### Footnotes

    This text has a footnote reference[^note]

    [^note]: Foonotes for testing.

### Headers

Markdown headers using `##` syntax or using `==` or `--` are not supported in Hyperkitty. This is because these characters are very often used in different context and results in untentional `<h1>` and `<h2>` tags in the rendered output.

## Extending Hyperkitty Renderer

Hyperkitty uses the mistune library as the renderer but customizes the rendering rules to tailor the rendering behavior to its liking. Many of the above mentioned rules are implemented as mistune plugins using their standard plugin interface.

As it has been mentioned in the first paragraph of this page, the default set of rules that are enabled in Hyperkitty is going to be limited by what can be assumed in a unstructured plain text email.

But, new rendering rules that conform the above design can be added or contributed to Hyperkitty. It is possible to also extend the renderer to support optional rules that can be enabled by site administrators if they choose to do so. These rules would have to be mistune plugins and need to be either a 3rd party package or contributed to Hyperkitty.