I updated the documentation and used a different approach: going bottom→top in indexes, and top→bottom in posts/pages. This way, we can get a sensible ordering for both use cases.

@Kwpolska I resolved the conflicts, hope I did not mess it, feel free to push merge

@felixfontein, please explain, and perhaps suggest a solution to:

If one of the header links belongs to a child element with the same ID, you change the link to something wrong.

Maybe something like:

<div id="the-content">
  [...]
  <h1 id="the-content">The Content</h1><a class="headerlink" href="#the-content">¶</a>
</div>

(And there's another the-content ID somewhere so that both these end up in off.) If the code processes them from top to bottom, it will change it to the following:

<div id="the-content-2">
  [...]
  <h1 id="the-content-3">The Content</h1><a class="headerlink" href="#the-content-2">¶</a>
</div>

because the <div> is processed first.

To avoid this, you probably have to check if there's another the-content ID between the headerlink element and the element whose ID we're currently processing.

It sounds as if doing a break when we find the first headerlink will work, because those are supposed to be the first headerlink in a given header. (Using headerlinks[0] would work in 99.9% of cases, I believe). @felixfontein, please review again.

In the case I sketched above it won't work, because the <div> has no headerlink (because it is no header), so still the wrong headerlink will be "fixed". The problem here is that the header in the post happens end up with the same ID (because of it's title) than something generated by the theme (the <div id="the-content">).

Please propose a better solution then? I’m inclined to say “edge case not worth fixing”.

Is there an efficient way to find the first parent object of hl whose ID is id? If yes, you could check whether it is e.

I’m afraid this might not be efficient enough, and that would be needed only for an edge case. This happening in real input is very unlikely. (reST won’t ever generate it, for example)

Just manually walking up the DOM tree shouldn't be very slow. Usually DOM trees aren't excessively deep that you really get a performance hit. And since this search has only to be done for very few elements, it shouldn't really matter.

And yes, while this is an edge case, it is a bug and really shitty for a user if this happens. And if we ever fix this, it might break some existing links where someone might have worked around this bug.

In my opinion, we should get this filter into a form that should never require any changes, because every change might break existing links, which are supposed to be permalinks. But then, I probably won't be using it (in particular the headerlink feature), so I won't really mind if you decide to ignore this edge case :)

Edit: I just noticed that this only screws up the header links, but not the IDs themselves. So this won't destroy permalinks later on, it will just generate incorrect header links. So I'm really fine with leaving this as-is. On the other hand, walking up the DOM tree isn't that hard and inefficient either.

Ok, just thought of one reason where this can happen more realistically in real life: if someone decides to name a subsection the same as a section. Some people tend to do that. And if you don't use a compiler which prevents colliding IDs, you have a problem.

Edit: ah, I forgot about the break, that'll of course prevent this.

Thanks, merged. Will rebuild getnikola.com to use this in a second.