JuliaDocs
Feature request: stay on page when changing version
Often when I am reading documentation, I want to change the version of the docs I am looking at.
For example, I am currently reading: https://docs.sciml.ai/ModelingToolkit/stable/basics/MTKLanguage/
When I want to read the dev version of this page, I go to the bottom left and change the version to dev.
Instead of forwarding me to https://docs.sciml.ai/ModelingToolkit/dev/basics/MTKLanguage/, this forwards me to the homepage at https://docs.sciml.ai/ModelingToolkit/dev/.
Ofcourse sometimes that particular page is not available in different versions of the documentation, but in that case we can fall back to the homepage. Can we make it so that, if that page is available, changing the version leads to the page I'm currently viewing?
I'd like this as well, but it's not so easy. Right now we have no good way to determine whether the target page exists. So a naive approach would end up on a 404 error page.
And of course pages built with an older Documenter version won't have this (so you can't switch back) unless we implement some tool that updates old page's version.
But of course all of that could be overcome, I simply wanted to explain why it isn't that easy.
Got it, thanks for responding! This is available in sphinx (the python docs framework), so maybe we can take inspiration from that.
Sure. If anyone knows how sphinx does it, please leave a comment here explaining it.
Isn't it as basic as this?
- Check if page exists. If it returns a
200 OK, forward to it. - If it doesn't exist, forward to home page.
Yeah, OK, but how do you get the browser to do that? By inserting some JavaScript?
I'm not a frontend expert, but this sounds like something that should be relatively straightforward. Claude tells me this (untested, but looks reasonable, as a starting point):
<!DOCTYPE html>
<html>
<head>
<title>Smart Links</title>
</head>
<body>
<a href="/primary-page"
data-fallback="/backup-page"
class="smart-link">
Click me
</a>
<script>
document.querySelectorAll('.smart-link').forEach(link => {
link.addEventListener('click', async (e) => {
e.preventDefault();
const primaryUrl = link.href;
const fallbackUrl = link.dataset.fallback;
try {
const response = await fetch(primaryUrl, {
method: 'HEAD' // Only fetch headers, not the whole page
});
if (response.status === 200) {
window.location.href = primaryUrl;
} else {
window.location.href = fallbackUrl;
}
} catch (error) {
// Network error or other failure - use fallback
window.location.href = fallbackUrl;
}
});
});
</script>
</body>
</html>
An alternative approach for handling this would be via post-processing, during deployment. Deployment has access to the full gh-pages branch, so it could check which pages exist in other versions. Or, it could draw information from the Inventory file.
The post-processing approach could also be realized by a completely separate script or package.
In any case, I think staying on the current page when changing version would be a very desirable feature.
I'm not a frontend expert, but this sounds like something that should be relatively straightforward. Claude tells me this (untested, but looks reasonable, as a starting point):
I gave a shot at implementing this at #2801. Could somebody with more frontend knowledge than me check this out? It works correctly on my local machine.
If you want to test this: https://github.com/JuliaDocs/Documenter.jl/pull/2801#issuecomment-3483297607
Summary of current state of this issue: thanks to PR #2801 we have a basic version of this: when using the version selector popup to switch to different version, then we now stay on the corresponding page in the chose version (if available)
Missing in order to close this are, IMHO:
- the code in
warner.js(which shows a badge when looking at old or dev versions of manuals, with a link to the stable version) does not yet do this, but really also should - the logic does not take the "hash" / anchor part of the URL into account
- What I mean is this: suppose you start on https://docs.julialang.org/en/v1.12/base/arrays/#Base.findnext-Tuple{Any,%20Integer} and switch to version 1.10, then right now you end up at the top of https://docs.julialang.org/en/v1.10/base/arrays/ but ideally we'd preserve the part of the URL after
#and switch to https://docs.julialang.org/en/v1.10/base/arrays/#Base.findnext-Tuple{Any,%20Integer} (it is possible the anchor is not available in that version -- that's fine, though, it will just be ignored)
- What I mean is this: suppose you start on https://docs.julialang.org/en/v1.12/base/arrays/#Base.findnext-Tuple{Any,%20Integer} and switch to version 1.10, then right now you end up at the top of https://docs.julialang.org/en/v1.10/base/arrays/ but ideally we'd preserve the part of the URL after
- support in DocumenterTools to patch older versions of a manual to also use the improved JavaScript, so that one can also "switch back". That said, we could also open three new issues for those and close this one.
That said, we could also open three new issues for those and close this one.
I would be in favour of that. This may be a long shot, but maybe a claude agent or copilot (with some guidance) could tackle these issues separately? It would require a clear issue description and someone would have to test the implementation.
I am pretty sure someone could use Claud/Copilot/etc. to assist them to tackle any of the three. But I feel that's a bit besides the point: we care about the issues being resolved, which tool (be it an AI, or an IDE, or something else) they use for that is not part of the issue.
My point was, code agents can work 'independently' on issues if they are simple enough and self-contained. So if nobody is available / willing to tackle this, perhaps an agent can work on the issue.
OK, but "an agent" would still have to be supervised by someone. We don't want automated AI slop here.
Anyway: if someone opens three new self-contained issues for this, I'll be happy to close this one.
(Maybe my last comment was a bit too implicit, so, to spell out what I meant: If a human guides the AI agent, I don't think it matters whether there is a separate issue or not. They can point at the specific paragraph where I explain the subissue, resp. copy-and-paste that. Conversely, an AI agent that only can do something if there is a hand-taylored issue made just for its sake would be a very poor tool indeed.)
I dont want to turn this into a whole discussion about AI. But there are plenty of examples in the wild now that show AI agents can produce, independently, useful code. Provided you give a clear set of requirements, aka a dedicated issue.