From 16bbd9a164ae4c4afc8914199c37386ed6914582 Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Mon, 24 Aug 2026 21:33:52 +0200
Subject: docs(signatures): document the directory and the three keys

Part of item 152.
---
 CHANGELOG.md |  7 +++++++
 README.md    | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1144402..38d2a58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -65,6 +65,13 @@ point at which they are stable.
 - The notmuch hooks that auto-tag incoming mail now live in this repository,
   under `assets/hooks/`. They moved from the companion `mailctl` project,
   which is being retired.
+- Signatures. Markdown files in `~/.config/qtmaildir/signatures/`, one per
+  signature, chosen from a control on the composer's editor bar. One
+  signature serves both the plain-text and the HTML part of a message, since
+  the HTML is rendered from the same markdown. `[compose] signature` seeds a
+  new message, `[account.<key>] signature` overrides it per account, and
+  `[compose] signature_position` puts a new one at the end of the message
+  (the default) or above the quoted text in a reply.
 
 ### Changed
 
diff --git a/README.md b/README.md
index ae51de5..5b10332 100644
--- a/README.md
+++ b/README.md
@@ -516,6 +516,41 @@ that window stops it and returns you to the composer with everything intact.
 Nothing has reached the network until the countdown ends;
 `[compose] send_delay_ms` sets how long it lasts, and 0 removes it.
 
+### Signatures
+
+Signatures are markdown files, one per signature, in
+`~/.config/qtmaildir/signatures/`:
+
+```
+~/.config/qtmaildir/signatures/
+├── work.md
+├── personal.md
+└── brief.md
+```
+
+The filename without its extension is the name shown in the composer. There
+is no editor for them inside qtmaildir: the directory is yours to manage with
+your own editor.
+
+Markdown, like the body of a message. `qtmaildir` builds the plain-text part
+of a message from what you typed and the HTML part by rendering the same
+text, so one signature serves both and you never choose a format.
+
+The composer's editor bar carries a **Signature** control listing every file
+plus *None*. Choosing one replaces whichever is already in the message, so
+switching is safe to do repeatedly.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `[compose] signature` | none | The signature seeded on a new message, by name |
+| `[compose] signature_position` | `end` | `end`, or `above_quote` to put it before the quoted text in a reply |
+| `[account.<key>] signature` | none | Seeds this account's messages instead of the `[compose]` value |
+
+A signature is not tied to an account. `[account.<key>] signature` only
+chooses which one a message *starts* with; every signature stays reachable
+from the control whichever account you are sending from, and changing the
+From: account re-seeds it only until you pick one yourself.
+
 ## Tagging
 
 Archive, delete, spam, mark-important and toggle-unread write fixed tags. For anything
-- 
cgit v1.2.3