.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                          'raw_html'
 225                        ]
 226
 227     enabled = '+'.join(ext_enabled)
 228     disabled = '-'.join(ext_disabled)
 229     inputfmt = f'{inputfmt}+{enabled}-{disabled}'
 230
 231     args = []
 232     if standalone:
 233         args.append('--standalone')
 234     if title:
 235         args.append(f'--metadata=pagetitle:"{title}"')
 236
 237     return pypandoc.convert_text(mdwn, format=inputfmt, to=outputfmt,
 238                                  extra_args=args)
 239
 240
 241 def _apply_styling(html):
 242     '''
 243     Inline all styles defined and used into the individual HTML tags.
 244     '''
 245     return pynliner.Pynliner().from_string(html).with_cssString(DEFAULT_CSS).run()
 246
 247
 248 def _postprocess_html(html):
 249     '''
 250     Postprocess the generated and styled HTML.
 251     '''
 252     return html
 253
 254
 255 def convert_markdown_to_html(mdwn):
 256     '''
 257     Converts the input Markdown to HTML, handling separately the body, as well
 258     as an optional signature.
 259     '''
 260     parts = re.split(r'^-- $', mdwn, 1, flags=re.MULTILINE)
 261     body = parts[0]
 262     if len(parts) == 2:
 263         sig = parts[1]
 264     else:
 265         sig = None
 266
 267     html=''
 268     if body:
 269         body = _preprocess_markdown(body)
 270         body = _identify_quotes_for_later(body)
 271         html = _convert_with_pandoc(body, standalone=False)
 272         html = _reformat_quotes(html)
 273
 274     if sig:
 275         sig = _preprocess_markdown(sig)
 276         html += SIGNATURE_HTML.format(sig='<br/>'.join(sig.splitlines()))
 277
 278     html = HTML_DOCUMENT.format(htmlbody=html)
 279     html = _apply_styling(html)
 280     html = _postprocess_html(html)
 281
 282     return html
 283
 284
 285 def main():
 286     '''
 287     Convert text on stdin to HTML, and print it to stdout, like mutt would
 288     expect.
 289     '''
 290     html = convert_markdown_to_html(sys.stdin.read())
 291     if html:
 292         # mutt expects the content type in the first line, so:
 293         print(f'text/html\n\n{html}')
 294
 295
 296 if __name__ == '__main__':
 297     main()