Jupyterhub: anchor links on markdown docs pages are unreliable

[minrk]

Some of the pages generated from markdown sources have either missing or inconsistent anchors. For instance, on the changelog, version headings do not get any ID and repeated headings (e.g. added in each release) all get the same ID. This could be a bug in recommonmark, or something else.

@willingc as resident sphinx expert, can you investigate?

[willingc]

Will do.

[willingc]

@minrk I was able to look at this briefly. The changelog definitely has the issues you mention. If you have a specific instance on another page, that would be helpful. Will look into it over the weekend. My initial instinct is recommonmark has an issue with subheaders and anchors. I want to see if the same behavior occurs if I swap out the custom theme and see what happens if I use plain alabaster.

[minrk]

my initial instinct on which links have the most trouble suggests that it might have difficulty with headings that are only numerical and/or have links in them.

[manics]

Shall we close this and assume it is or will be fixed by the current versions of sphinx/recommonmark?