Header anchors [needs discussion]

It's very popular request to add header ancors. Prior to do it, we need to discuss possible security problems and solutions.

Read first

• https://github.com/jch/html-pipeline/pull/111#issuecomment-34369984 - discussion about github implementation
• http://www.slideshare.net/x00mario/in-the-dom-no-one-will-hear-you-scream - awesome presentation about dom clobbering

Problems:

1. id - collisions
2. name - dom clobbering
3. cross-conflicts when multiple docs on the same page have the same headers

Possible solutions

1. Do nothing
   • unsafe, you need to control content, or site will be vulnerable
2. Add prefix
   • will require js to keep references work
   • without js will make manual references typing not convenient
     • does anyone type such way?
     • not a problem for autogenerated tocs (we can add prefix to both anchors and refs)
3. Add per-doc unique prefix
   • not convenient in use. required in very limited cases

Need to discuss better solutions, and what to do by default, because anchors are really needed

current status

1. Must have not empty default prefix
   • options.anchorPrefix - instance default. env.anchorPrefix - every-time-render override
2. Open questions:
   • default prefix name?
     • - or -- of no objections (short and easy to type)
   • should we autofix local relative anchor links? any bad side effects?

Start with the linked html-pipeline discussion and the DOM clobbering presentation, then review the proposed anchorPrefix options and open questions in this issue. Done means reaching a decision on the safe default behavior, prefix naming, and whether local relative anchor links should be adjusted.