Avoid broken links caused by htmlsingle to html5 directory name change

[wilkinsona]

With thanks to @dreis2211 for bringing it to my attention, the change from htmlsingle to html5 in Spring Security 5.3 has broken some documentation links. It'd be nice if existing links to https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/ would continue to work. It'd also be nice if you could take any 5.2.x link and change it to 5.3.x and not get a 404.

[philwebb]

Is there any reason that the html5 folder has been chosen? I think it would be better if all out docs tried to publish with the same folder structure.

[rwinch]

@philwebb Good question. It use to be that we produced html5 (pure asciidoctor output) and htmlsingle (going through docbook toolchain). You can see that here https://docs.spring.io/spring-security/site/docs/5.0.0.RELEASE/reference/ We've removed the docbook toolchain and now only html5 remains. We could rename it, but that would break people who linked to the old format. This is probably a lot fewer people, but I imagine that it still exists

[snicoll]

We could rename it, but that would break people who linked to the old format.

Can't you fix that with redirect rules on the server?

We're post RC now and we still have a broken link in our doc. Can you please give us a decision before 2.3 is GA?

[rwinch]

I think the answer is that we have redirects setup from htmlsingle to html5 vs the other way around.

Sorry I forgot to update the issue. This should be solved. Are there missing redirects still?

[snicoll]

https://docs.spring.io/spring-security/site/docs/5.3.0.RELEASE/reference/htmlsingle/ is 404ing for me. We are providing link to the matching Spring Security version in our bom so I don't think the current state of affairs would work for us.

[rwinch]

@snicoll I had thought we had a redirect setup. I'll look into that. I'd suggest updating the link so you don't put users through an unnecessary redirect.

[philwebb]

I think the answer is that we have redirects setup from htmlsingle to html5 vs the other way around.

Any chance of changing that in a future release so we can link to htmlsingle and not get the redirect? AFAICT there are aren't many /html5 paths in the other published Spring project Docs.

[rwinch]

@philwebb Is there something I'm missing here? I wouldn't think there would be so much push back on changing a link. Is this causing some problems that I'm missing?

The issue is that either change is a "breaking" change since one format was removed. Switching to htmlsingle will just cause those using html5 the same problem you are experiencing. We chose this approach because it is consistent with what Spring Security has been doing since supporting both formats.

[philwebb]

I'm really just striving for consistency as much as possible across the portfolio. There's no technical reason that we can't link to /html5 and it's not a massive deal if you don't change it. If you look at the other popular Spring projects, they mostly seem to have settled on /html or /htmlsingle, e.g:

https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/
https://docs.spring.io/spring-integration/docs/current/reference/html/
https://docs.spring.io/spring-batch/docs/current/reference/html/
https://docs.spring.io/spring-data/jdbc/docs/current/reference/html/
https://docs.spring.io/spring-security/site/docs/5.2.4.RELEASE/reference/htmlsingle/

It does look like Spring Framework is another exception, but I'm pretty sure they used to publish to /html and I'll raise an issue to see if they will do that again.

So all I'm really saying is, given the choice to redirect from /htmlsingle to /html5 or /html5 to /htmlsingle if you choose the latter then things are consistent with other project.

[philwebb]

Asking the same question the other way around, what am I missing? What's the reason to keep /html5?

[rwinch]

I'd be open to changing this for 5.4 (our next minor release), but this means you will need to update links twice which seems like more work. If that works for you, I will schedule it for our 5.4.x release

[philwebb]

Sounds good, it's not a lot of work on our end. I'll open a Boot issue to remind us to migrate back.

[rwinch]

Thanks @philwebb! I guess I misunderstood the reasoning and was not figuring you wanted to switch twice.

I've schedule this for 5.4