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:
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.