GitHub rendering does not respect case-sensitive anchor tag names

[refset]

If you have a namespace with both Db (a protocol) and db (a function), the generated table of contents as GitHub renders it will incorrectly link both entries to the same db section due to the collision.

Inspecting GitHub's HTML shows that a case-insensitive naming scheming is applied e.g. user-content-db (for Db) and user-content-db-1 (for db), which perhaps hints at an approach to fixing this.

This is definitely not super important but I figured it was worth capturing 🙂

[borkdude]

@refset But the links in the TOC should still work... right?

[refset]

Yes the TOC still contains clickable links that scroll the page, but they both scroll to the same db heading because GitHub ignores the case-sensitivity of the two otherwise distinct URL fragments [...]#my.ns/Db vs [...]#my.ns/db

[borkdude]

Is there anything quickdoc can do to fix this?

[refset]

I reckon always adding a positional index as a suffix to the tag names regardless (-1, -2, -3, etc.) would never fail to disambiguate all the generated/interpreted links. It would break any existing links people may be relying on though. To mitigate that impact we could specifically look for case-insensitive duplicate entries and only disambiguate those (but also check that you're not about to introduce new collisions in that case!)...but perhaps that's too haphazard 🤔

[borkdude]

This is kind of what I had before:

quickdoc/src/quickdoc/impl.clj

Lines 113 to 118 in 66e4835

	(defn with-idx [s memo]
	(let [v (swap! memo update s (fnil inc -1))
	c (get v s)]
	(if (zero? c)
	s
	(str s "-" c))))

but got lost in a PR which improved the links in the TOC.

quickdoc/src/quickdoc/impl.clj

Lines 159 to 162 in 66e4835

	(println "- " (format "[`%s`](#%s) %s" ns-name
	(str (with-idx (md-munge ns-name) memo))
	(str (when-let [summary (var-summary ns)]
	(str " - " summary)))))