zola/docs/content/documentation
Chris Morgan 1a9ab968fe Allow manual specification of header IDs (#685)
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)
2019-05-20 13:08:49 -07:00
..
content Allow manual specification of header IDs (#685) 2019-05-20 13:08:49 -07:00
deployment Merge branch 'master' into next 2019-05-15 21:42:51 -07:00
getting-started Revert "Allow default base-path command line option to be set for building and serving" 2019-04-20 12:50:34 +02:00
templates Fix a bit the pagination template doc 2019-05-18 17:55:10 -07:00
themes Add some missing words to creating a theme page 2019-04-18 07:49:17 +10:00
_index.md Update _index.md 2018-03-22 15:47:34 -06:00