Header anchors [needs discussion]

[puzrin]

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

Read first

• Use id attribute instead of name for ToC gjtorikian/html-pipeline#111 (comment) - 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?

[fengmk2]

add default perfix to make id unique? like prefixId="mdit-"

# this is h1 => id="mdit-this-is-h1"

Use can set perfixId to empty string, got id="this-is-h1"

[puzrin]

It's the most possible solution. Don't know how many expected things it will break. Also adds a second question - should we try to autofix links with anchors only (add prefix) or not.

[vyp]

What an about an option for the prefix, which is on by default? So if anyone doesn't want their anchors autofixed, they can turn it off?

[fengmk2]

I create a locally implementation for zeke/marky-markdown/pull/6

[puzrin]

What an about an option for the prefix, which is on by default? So if anyone doesn't want their anchors autofixed, they can turn it off?

Yes. According to http://www.slideshare.net/x00mario/in-the-dom-no-one-will-hear-you-scream id/name without prefix will add unlimited vectors for attacs. No prefix by default would be mad, even with sanitizers. So, we have 2 more questions to answer:

1. default prefix name? (something neutral, easy to type)
2. Should we try to automatically fix links to anchors (add prefix if not exists) or not? Will such magic add side effects? Is is really required?

[fengmk2]

How about follow the github way? github use user-content- perfix

[puzrin]

If we add such perfix to links too, those will look ugly. I'd prefer something like - or --.

[puzrin]

Updated current status in the first post. If you know other people, interested in solution and having practice with this topic - invite them to join. Correct and convenient resolution is important.

I don't have enougth usage stat, and don't wish to push all with my opinion.

/cc @jonathanong

[fengmk2]

@jonathanong old friend...

/cc @dead-horse

[jonathanong]

Make it a plugin and don't worry about it? Haha

I'm okay with a custom prefix though

[ixti]

IMHO it should be a plugin. And, it needs some options (how it will generate IDs).
I propose to support 3 variants of IDs generation. Assume we have markdown text:

# First heading

## Nice, second heading

## Another "nested" heading

# Here we go again

First variant: slugify. For the markdown above it will generate IDs like this:

#first-heading
#nice-second-heading
#another-nested-heading
#here-we-go-again

Second is actually slugify with prefix option (default: no prefix):

#my-prefix-first-heading
#my-prefix-nice-second-heading
#my-prefix-another-nested-heading
#my-prefix-here-we-go-again

Third one (I would go with this one by default):

#section-1
#section-1.1
#section-1.2
#section-2

Also, prefix option actually can affect both variants. So I imagine optiosn of a plugin like this:

{
  style: "slugify", // possible values: "slugify", "numerify"
  prefix: "section-" // default: no prefix 
}

[puzrin]

IMHO it should be a plugin. And, it needs some options (how it will generate IDs).

I think, that's unnecessary overcomplication. That will add more complexity than whole renderer function override. User can always do it, it (h|sh)e doesn't like default id generation method.

[puzrin]

Though i can add Renderer.anchorify() for easy override.