link fragments should follow the GitHub heading algorithm

[mnemnion]

Issue

A reference like [Section](#section-name) doesn't work, it must be [Section](#Section-Name), assuming the section name is titlecased. The former ought to be supported.

Rationale

While the format of fragment links is not a part of the CommonMark standard, the convention used in GitHub is a strong one, many Markdown editing suites will only recognize document fragments if they are defined according to it, see this Markdown linting rule.

This would make documentation easier to write, and aid conversion of e.g. GitHub README.md files into Documenter documents, and would conform to the de-facto standard, which is always a good thing.

Fix

This doesn't have to be a breaking change, HTML allows for multiple fragment names using consecutive <a name="fragment"> elements before the header in question.

Another option is to add a makedocs option, githubheadings=true, which would generate links in the accustomed style.

Thank you for your hard work, and for considering this proposal.

[goerz]

You should use @ref links for these, not manual links to an anchor.

And, I would absolutely consider this a breaking change. For one, it would break https://github.com/JuliaDocs/DocumenterInterLinks.jl. (I can adapt to a new algorithm, of course, but it’s a semver-breaking release for both packages). Thus, I’m pretty strongly opposed to this. And I don’t think we should litter the HTML with additional redundant anchor tags.

Although I do agree that it would have been nicer to emulate GitHub sluggification from the start, so we could put this in the log for when/if we get around to Documenter 2.0

[mnemnion]

The main interest is in maintaining a part of a README (designed to be read on GitHub) as part of Documenter, so a @ref link doesn't actually help.

It's understandable not to want to do this, given an ecosystem which depends on the refs as they are. I hope you might consider an opt-in githubfragments=true which, well, litters the HTML with redundant links. I'm one user who would get a lot of use out of the extra complexity this would introduce, which is hopefully limited to the HTML generation.

[goerz]

For that use case, I would recommend a snippet of code in your make.jl file that reads the main README.md file with Github syntax and writes it to a docs/src/index.md file in a format more suitable for Documenter. The main README.md should be in the repo root, and Documenter can't use sources from outside the docs/src folder, so you have to copy it anyway.

[mortenpi]

Although I do agree that it would have been nicer to emulate GitHub sluggification from the start, so we could put this in the log for when/if we get around to Documenter 2.0

In my mind, I don't think the generated slugs are part of the Documenter public API though. Largely because I would love to clean them up at some point (at which point we could declare the algorithm to be public API).

For the README use case, pre-processing the README seems to be the right way to go though.

[mnemnion]

For what it's worth as a non-contributor user, I would consider outright changing the slug syntax to be breaking. Not only would it invalidate user links, it would invalidate document links into the documentation on other people's websites.

Adding duplicates (in the common case where the GitHub-flavored slug and the Documenter-flavored slug differ) would not be breaking, and adding a keyword-option which enabled them (with or without the original ones) would definitely not be, added functionality is never breaking in SemVer.

A script to add portions of the README to the Docs file is pretty easy, reprocessing the fragments is not, because the information needed to reconstruct the Document style isn't in the fragment, it's in the header. I'll probably go in the other direction, actually, since lowercase(documenterslug) should (at least in my cases) produce a GitHub-flavored slug.

[goerz]

Link checkers (the link check we use in Documenter, specifically) don't notice if an anchor doesn't exist, right? If they did, or if we could make linkcheck=true detect incorrect anchors in some other way, I'd be less cautious about changing the slug.

As for linking to documentation on other people's website, DocumenterInterLinks would solve that problem in principle, as it would either automatically adjust to new slugs or throw an error if linking to a non-existing slug. However, first I have to make a PR to add inventory writing to Documenter (#2366), then that has to be merged/released and then that new release has to become widely adopted. And even then, there are a lot of legacy docs with direct links to other latest documentations that probably will never get around to replacing those links with DocumenterInterLinks. All of those links would break in a hard-to-detect way if we change the slugs.

[goerz]

My thinking on this might be evolving, due to sphinx-doc/sphinx#12008

(I'll see if I can fix the bug in Sphinx, though)

[mnemnion]

This comes up a lot when you have a de-facto standard. CommonMark doesn't require github-flavored fragments, but they're presumed by a lot of tooling. CommonMark is also a specification for specifically-not-Markdown, at Gruber's insistence, but really Markdown is whatever you find in the wild. There was a similar effect when certain parties starting pushing to change "master" branches to "main", the former was a de-facto standard and it broke a lot of tooling. I'd argue in that case that the tooling was buggy, and probably in this case with Sphinx as well. But there's a case to be made for going with the flow on this one.

Thanks for keeping the issue open.

[goerz]

I've also tweaked the DocumenterInterLinks documentation to strongly discourage the form [Section Title](@extref Project) and noted that the transformation from "Section Title" to an anchor slug is Documenter-specific and not guaranteed to be stable, and that links like that are better written as [Section Title](@extref Project Section-Title) (or whatever the actual slug is in the inventory of Project).

Thus, changing the sluggification algorithm would no longer be breaking, at least not for me. It would definitely break a lot of existing direct links in the wild, but maybe that would be a motivation for projects using such links to switch to DocumenterInterLinks as soon as possible ;-)