Crosslinks should not include .html

[philwebb]

Eg:

read the "getting-started.html" and "using.html" sections

in https://docs.spring.io/spring-boot/docs/2.6.x/reference/html/features.html#features

[wilkinsona]

Unfortunately, there are still quite a few other .html links in the multi-page docs. Asciidoctor manages to use the title of the section to which we're linking in the single-page docs. It would be good to find a way to get that to work in the multi-page docs as well without having to provide the link text manually.

[mhalbritter]

This seems to be the problem:

https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/

I'm trying to find a workaround.

[mhalbritter]

I got an answer here: https://asciidoctor.zulipchat.com/#narrow/stream/279644-users.2Fasciidoctorj/topic/.E2.9C.94.20Link.20titles.20in.20multipage.20crossreferences

Looks like the << ... >> syntax is deprecated and even when using xref we have to make sure to satisfies all the rules. Going to take a look if this is feasible for us.

[mhalbritter]

Dan Allen said:

You can't get automatic titles across separate documents (unless you are using AsciiDoc with Antora).

[mhalbritter]

Workaround would be to add the title by hand to all xrefs which have no explicit title. Downside is that then the title in the link can differ from the linked section, if the section is renamed and the link stays at the old title.

[philwebb]

We might be able to hack something on out custom backend in the meantime

[philwebb]

There's no easy way to do this with the backend so I think we should just live with it until the Antora migration.