Hi! This is part of the CommonMark escaping strategy we inherited from our upstream. There's some truly ancient code in there; just now I git blamed something I didn't recognise even slightly and it was me, almost 8 years ago.

The extant strategy is that, in regular text, we simply always escape a bunch of characters, hash # included:

We obviously can be smarter about this, but it requires a bit more intelligence than the formatter currently provides for (viz. almost none — right now the function outputting a character has no context whatsoever).

Would you be willing to try submitting a PR to fix this? An acceptable minimal improvement would, for instance, pass through buf and i (instead of buf[i]) to self.outc on line 170, and then — in outc — not escape # if there's a following character which isn't whitespace. This gets you over the line without us rewriting the formatter.

Hey, yes that was my initial idea here, to match on string there instead of a char and the string would be "# "

Thanks, I'll make a PR today

I'm afraid it goes deeper, even exclamation marks are escaped

Yes, if you look at the code snippet I've quoted above, quite a lot of things are escaped — anything that could form part of valid markup. (For exclamation mark !, it's images: ![blah](blah).)