Justification for this feature is added in the docs.

Precedent for the precise syntax: Hugo.

Hugo puts this syntax behind a preference named headerIds, and automatic
header ID generation behind a preference named autoHeaderIds, with both
enabled by default. I have not implemented a switch to disable this.

My suggestion for a workaround for the improbable case of desiring a
literal “{#…}” at the end of a header is to replace `}` with `}`.

The algorithm I have used is not identical to [that
which Hugo uses][0], because Hugo’s looks to work at the source level,
whereas here we work at the pulldown-cmark event level, which is
generally more sane, but potentially limiting for extremely esoteric
IDs.

Practical differences in implementation from Hugo (based purely on
reading [blackfriday’s implementation][0], not actually trying it):

- I believe Hugo would treat `# Foo {#*bar*}` as a heading with text
  “Foo” and ID `*bar*`, since it is working at the source level; whereas
  this code turns it into a heading with HTML `Foo {#<em>bar</em>}`, as
  it works at the pulldown-cmark event level and doesn’t go out of its
  way to make that work (I’m not familiar with pulldown-cmark, but I get
  the impression that you could make it work Hugo’s way on this point).
  The difference should be negligible: only *very* esoteric hashes would
  include magic Markdown characters.

- Hugo will automatically generate an ID for `{#}`, whereas what I’ve
  coded here will yield a blank ID instead (which feels more correct to
  me—`None` versus `Some("")`, and all that).

In practice the results should be identical.

Fixes #433.

[0]: a477dd1646/block.go (L218-L234)