ficd/mailfmt
1
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

added markdown safety

Browse source
This commit is contained in:
Daniel Fichtinger 2025-06-03 14:09:58 -04:00
parent d5551d2269
commit 804e5a22eb
2 changed files with 164 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

147
README.md
View file

@ -1,11 +1,26 @@
# Mail Format
<h1>Mail Format</h1>
`mailfmt` is a simple plain text email formatter. It's designed to ensure
consistent paragraph spacing while preserving markdown syntax, email headers,
sign-offs, and signature blocks.
By default, this script accepts its input on `stdin` and prints to `stdout`.
This makes it well suited for use with an editor like Helix. It has no
dependencies besides the standard Python interpreter, and was written and tested
against Python 3.13.2.
This makes it well suited for use as a formatter with a text editor like Kakoune
or Helix. It has no dependencies besides the standard Python interpreter, and
was written and tested against Python 3.13.3.
**Features:**
<!--toc:start-->
- [Features](#features)
- [Usage](#usage)
- [Output Example](#output-example)
- [Markdown Safety](#markdown-safety)
- [Aerc Integration](#aerc-integration)
- [Contributing](#contributing)
<!--toc:end-->
## Features
- Wraps emails at specified columns.
- Automatically reflows paragraphs.
@ -18,12 +33,16 @@ against Python 3.13.2.
- Markdown-style code blocks.
- Usenet-style signature block at EOF.
- Sign-offs.
- If specified, output can be made safe for passing to a Markdown renderer.
- Use case: piping the output to `pandoc` to write a `text/html` message. See
[Markdown Safety](#markdown-safety).
**Usage:**
## Usage
```
usage: format.py [-h] [-w WIDTH] [-b] [--no-replace-whitespace] [--no-reflow]
[--no-signoff] [--no-signature] [--no-squash] [-i INPUT] [-o OUTPUT]
usage: mailfmt [-h] [-w WIDTH] [-b] [--no-replace-whitespace] [--no-reflow]
[--no-signoff] [--no-signature] [--no-squash] [-m] [-i INPUT]
[-o OUTPUT]
Formatter for plain text email.
"--no-*" options are NOT passed by default.
@ -39,6 +58,118 @@ options:
--no-signoff Don't preserve signoff line breaks.
--no-signature Don't preserve signature block.
--no-squash Don't squash consecutive paragraph breaks.
-m, --markdown-safe Output format safe for Markdown rendering.
-i, --input INPUT Input file. (default: STDIN)
-o, --output OUTPUT Output file. (default: STDOUT)
Author : Daniel Fichtinger
License: ISC
Contact: daniel@ficd.ca
```
## Output Example
Before:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text editor uses soft-wrapping, so it ends up looking horrible when viewed without wrapping! Additionally,
if I manually add some line breaks, things start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful
markdown
syntax. Markdown formatters are also problematic because they mess up
my signoff and signature blocks! What should I do?
Best wishes,
Daniel
--
Daniel
sr.ht/~ficd
daniel@ficd.ca
```
After:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text
editor uses soft-wrapping, so it ends up looking horrible when viewed
without wrapping! Additionally, if I manually add some line breaks, things
start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful markdown
syntax. Markdown formatters are also problematic because they mess up my
signoff and signature blocks! What should I do?
Best wishes,
Daniel
--
Daniel
sr.ht/~ficd
daniel@ficd.ca
```
## Markdown Safety
In some cases, you may want to generate an HTML email. Ideally, you'd want the
HTML to be generated directly from the plain text message, and for _both_
versions to be legible and have the same semantics.
Although `mailfmt` was written with Markdown markup in mind, its intended output
is still the `text/plain` format. If you pass its output directly to a Markdown
renderer, line breaks in sign-offs and the signature block won't be preserved.
If you invoke `mailfmt --markdown-safe`, then `\` characters will be appended to
mark line breaks that would otherwise be squashed, making the output suitable
for conversion into HTML. Here's an example of one such pipeline:
```bash
cat message.txt | mailfmt --markdown-safe | pandoc -f markdown -t html
--standalone > message.html
```
Here's the earlier example message with markdown safe output:
```
Hey,
This is a really long paragraph with lots of words in it. However, my text
editor uses soft-wrapping, so it ends up looking horrible when viewed
without wrapping! Additionally, if I manually add some line breaks, things
start to look _super_ janky!
I can't just pipe this to `fmt` because it may break my beautiful markdown
syntax. Markdown formatters are also problematic because they mess up my
signoff and signature blocks! What should I do?
Best wishes, \
Daniel \
-- \
Daniel \
sr.ht/~ficd \
daniel@ficd.ca \
```
## Aerc Integration
For integration with `aerc`, consider adding the following to your `aerc.conf`:
```ini
[multipart-converters]
text/html=mailfmt --markdown-safe | pandoc -f markdown -t html --standalone
```
When you're done writing your email, you can call the `:multipart text/html`
command to generate a `multipart/alternative` message which includes _both_ your
original `text/plain` _and_ the newly generated `text/html` content.
## Contributing
Please send patches, requests, and concerns to my
[public inbox](https://lists.sr.ht/~ficd/public-inbox).