.mutt/markdown2html

   1 #!/usr/bin/python3
   2 #
   3 # markdown2html.py — simple Markdown-to-HTML converter for use with Mutt
   4 #
   5 # Mutt recently learnt [how to compose `multipart/alternative`
   6 # emails][1]. This script assumes a message has been composed using Markdown
   7 # (with a lot of pandoc extensions enabled), and translates it to `text/html`
   8 # for Mutt to tie into such a `multipart/alternative` message.
   9 #
  10 # [1]: https://gitlab.com/muttmua/mutt/commit/0e566a03725b4ad789aa6ac1d17cdf7bf4e7e354)
  11 #
  12 # Configuration:
  13 #   muttrc:
  14 #     set send_multipart_alternative=yes
  15 #     set send_multipart_alternative_filter=/path/to/markdown2html.py
  16 #
  17 # Optionally, Custom CSS styles will be read from `~/.mutt/markdown2html.css`,
  18 # if present.
  19 #
  20 # Requirements:
  21 #   - python3
  22 #   - PyPandoc (and pandoc installed, or downloaded)
  23 #   - Pynliner
  24 #
  25 # Optional:
  26 #   - Pygments, if installed, then syntax highlighting is enabled
  27 #
  28 # Latest version:
  29 #   https://git.madduck.net/etc/mutt.git/blob_plain/HEAD:/.mutt/markdown2html
  30 #
  31 # Copyright © 2019 martin f. krafft <madduck@madduck.net>
  32 # Released under the GPL-2+ licence, just like Mutt itself.
  33 #
  34
  35 import pypandoc
  36 import pynliner
  37 import re
  38 import os
  39 import sys
  40
  41 try:
  42     from pygments.formatters import get_formatter_by_name
  43     formatter = get_formatter_by_name('html', style='default')
  44     DEFAULT_CSS = formatter.get_style_defs('.sourceCode')
  45
  46 except ImportError:
  47     DEFAULT_CSS = ""
  48
  49
  50 DEFAULT_CSS += '''
  51 .quote {
  52     padding: 0 0.5em;
  53     margin: 0;
  54     font-style: italic;
  55     border-left: 2px solid #ccc;
  56     color: #999;
  57     font-size: 80%;
  58 }
  59 .quotelead {
  60     font-style: italic;
  61     margin-bottom: -1em;
  62     color: #999;
  63     font-size: 80%;
  64 }
  65 .quotechar { display: none; }
  66 .footnote-ref, .footnote-back { text-decoration: none;}
  67 .signature {
  68     color: #999;
  69     font-family: monospace;
  70     white-space: pre;
  71     margin: 1em 0 0 0;
  72     font-size: 80%;
  73 }'''
  74
  75 STYLESHEET = os.path.join(os.path.expanduser('~/.mutt'),
  76                           'markdown2html.css')
  77 if os.path.exists(STYLESHEET):
  78     DEFAULT_CSS += open(STYLESHEET).read()
  79
  80 HTML_DOCUMENT = '''<!DOCTYPE html>
  81 <html><head>
  82 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  83 <meta charset="utf-8"/>
  84 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"/>
  85 <title>HTML E-Mail</title>
  86 </head><body class="email">
  87 {htmlbody}
  88 </body></html>'''
  89
  90
  91 SIGNATURE_HTML = \
  92         '<div class="signature"><span class="leader">-- </span>{sig}</div>'
  93
  94
  95 def _preprocess_markdown(mdwn):
  96     '''
  97     Preprocess Markdown for handling by the converter.
  98     '''
  99     # convert hard line breaks within paragraphs to 2 trailing spaces, which
 100     # is the markdown way of representing hard line breaks. Note how the
 101     # regexp will not match between paragraphs.
 102     ret = re.sub(r'(\S)\n(\s*\S)', r'\g<1>  \n\g<2>', mdwn, flags=re.MULTILINE)
 103
 104     # Clients like Thunderbird need the leading '>' to be able to properly
 105     # create nested quotes, so we duplicate the symbol, the first instance
 106     # will tell pandoc to create a blockquote, while the second instance will
 107     # be a <span> containing the character, along with a class that causes CSS
 108     # to actually hide it from display. However, this does not work with the
 109     # text-mode HTML2text converters, and so it's left commented for now.
 110     #ret = re.sub(r'\n>', r'  \n>[>]{.quotechar}', ret, flags=re.MULTILINE)
 111
 112     return ret
 113
 114
 115 def _identify_quotes_for_later(mdwn):
 116     '''
 117     Email quoting such as:
 118
 119     ```
 120     On 1970-01-01, you said:
 121     > The Flat Earth Society has members all around the globe.
 122     ```
 123
 124     isn't really properly handled by Markdown, so let's do our best to
 125     identify the individual elements, and mark them, using a syntax similar to
 126     what pandoc uses already in some cases. As pandoc won't actually use these
 127     data (yet?), we call `self._reformat_quotes` later to use these markers
 128     to slap the appropriate classes on the HTML tags.
 129     '''
 130
 131     def generate_lines_with_context(mdwn):
 132         '''
 133         Iterates the input string line-wise, returning a triplet of
 134         previous, current, and next line, the first and last of which
 135         will be None on the first and last line of the input data
 136         respectively.
 137         '''
 138         prev = cur = nxt = None
 139         lines = iter(mdwn.splitlines())
 140         cur = next(lines)
 141         for nxt in lines:
 142             yield prev, cur, nxt
 143             prev = cur
 144             cur = nxt
 145         yield prev, cur, None
 146
 147     ret = []
 148     for prev, cur, nxt in generate_lines_with_context(mdwn):
 149
 150         # The lead-in to a quote is a single line immediately preceding the
 151         # quote, and ending with ':'. Note that there could be multiple of
 152         # these:
 153         if re.match(r'^.+:\s*$', cur) and nxt.startswith('>'):
 154             ret.append(f'{{.quotelead}}{cur.strip()}')
 155             # pandoc needs an empty line before the blockquote, so
 156             # we enter one for the purpose of HTML rendition:
 157             ret.append('')
 158             continue
 159
 160         # The first blockquote after such a lead-in gets marked as the
 161         # "initial" quote:
 162         elif prev and re.match(r'^.+:\s*$', prev) and cur.startswith('>'):
 163             ret.append(re.sub(r'^(\s*>\s*)+(.+)',
 164                               r'\g<1>{.quoteinitial}\g<2>',
 165                               cur, flags=re.MULTILINE))
 166
 167         # All other occurrences of blockquotes get the "subsequent" marker:
 168         elif cur.startswith('>') and prev and not prev.startswith('>'):
 169             ret.append(re.sub(r'^((?:\s*>\s*)+)(.+)',
 170                               r'\g<1>{.quotesubsequent}\g<2>',
 171                               cur, flags=re.MULTILINE))
 172
 173         else: # pass through everything else.
 174             ret.append(cur)
 175
 176     return '\n'.join(ret)
 177
 178
 179 def _reformat_quotes(html):
 180     '''
 181     Earlier in the pipeline, we marked email quoting, using markers, which we
 182     now need to turn into HTML classes, so that we can use CSS to style them.
 183     '''
 184     ret = html.replace('<p>{.quotelead}', '<p class="quotelead">')
 185     ret = re.sub(r'<blockquote>\n((?:<blockquote>\n)*)<p>(?:\{\.quote(\w+)\})',
 186                  r'<blockquote class="quote \g<2>">\n\g<1><p>', ret, flags=re.MULTILINE)
 187     return ret
 188
 189
 190
 191 def _convert_with_pandoc(mdwn, inputfmt='markdown', outputfmt='html5',
 192                          ext_enabled=None, ext_disabled=None,
 193                          standalone=True, title="HTML E-Mail"):
 194     '''
 195     Invoke pandoc to do the actual conversion of Markdown to HTML5.
 196     '''
 197     if not ext_enabled:
 198         ext_enabled = [ 'backtick_code_blocks',
 199                        'line_blocks',
 200                        'fancy_lists',
 201                        'startnum',
 202                        'definition_lists',
 203                        'example_lists',
 204                        'table_captions',
 205                        'simple_tables',
 206                        'multiline_tables',
 207                        'grid_tables',
 208                        'pipe_tables',
 209                        'all_symbols_escapable',
 210                        'intraword_underscores',
 211                        'strikeout',
 212                        'superscript',
 213                        'subscript',
 214                        'fenced_divs',
 215                        'bracketed_spans',
 216                        'footnotes',
 217                        'inline_notes',
 218                        'emoji',
 219                        'tex_math_double_backslash',
 220                       ]
 221     if not ext_disabled:
 222         ext_disabled = [ 'tex_math_single_backslash',
 223                          'tex_math_dollars',
 224                          'smart',
 225                          'raw_html'
 226                        ]
 227
 228     enabled = '+'.join(ext_enabled)
 229     disabled = '-'.join(ext_disabled)
 230     inputfmt = f'{inputfmt}+{enabled}-{disabled}'
 231
 232     args = []
 233     if standalone:
 234         args.append('--standalone')
 235     if title:
 236         args.append(f'--metadata=pagetitle:"{title}"')
 237
 238     return pypandoc.convert_text(mdwn, format=inputfmt, to=outputfmt,
 239                                  extra_args=args)
 240
 241
 242 def _apply_styling(html):
 243     '''
 244     Inline all styles defined and used into the individual HTML tags.
 245     '''
 246     return pynliner.Pynliner().from_string(html).with_cssString(DEFAULT_CSS).run()
 247
 248
 249 def _postprocess_html(html):
 250     '''
 251     Postprocess the generated and styled HTML.
 252     '''
 253     return html
 254
 255
 256 def convert_markdown_to_html(mdwn):
 257     '''
 258     Converts the input Markdown to HTML, handling separately the body, as well
 259     as an optional signature.
 260     '''
 261     parts = re.split(r'^-- $', mdwn, 1, flags=re.MULTILINE)
 262     body = parts[0]
 263     if len(parts) == 2:
 264         sig = parts[1]
 265     else:
 266         sig = None
 267
 268     html=''
 269     if body:
 270         body = _preprocess_markdown(body)
 271         body = _identify_quotes_for_later(body)
 272         html = _convert_with_pandoc(body, standalone=False)
 273         html = _reformat_quotes(html)
 274
 275     if sig:
 276         sig = _preprocess_markdown(sig)
 277         html += SIGNATURE_HTML.format(sig='<br/>'.join(sig.splitlines()))
 278
 279     html = HTML_DOCUMENT.format(htmlbody=html)
 280     html = _apply_styling(html)
 281     html = _postprocess_html(html)
 282
 283     return html
 284
 285
 286 def main():
 287     '''
 288     Convert text on stdin to HTML, and print it to stdout, like mutt would
 289     expect.
 290     '''
 291     html = convert_markdown_to_html(sys.stdin.read())
 292     if html:
 293         # mutt expects the content type in the first line, so:
 294         print(f'text/html\n\n{html}')
 295
 296
 297 if __name__ == '__main__':
 298     main()