Update navigation logic to maintain page context

[langestefan]

Context: #2799

Tested locally, seems to work correctly.

• Stay on page when changing versions from e.g. /stable/page.html to /dev/page.html.
• Fallback to home page (e.g. /dev) when /dev/page.html is not available.

[fingolfin]

Nice, thank you!

It needs a bit more work (not all by you):

• some thorough testing on different computers / browsers (it'd be super useful if we could find a way to make a preview build available somewhere)
• a changelog entry (can be added once this is "done" and agreed to merge)
• code formatting with prettier
• on the long run (after this PR is merged) a way to "upgrade" existing documentation versions to also support this
  • i.e. I guess one needs to iterate over all assets/documenter.js files in a gh-pages branch and "patch" them suitably, which might be a matter of searching&replacing a fixed substring -- or multiple, dunno how often this segment of the code changed over the years)

[langestefan]

some thorough testing on different computers / browsers

I'm on Linux Fedora 43, I tested using firefox. I could also test chrome, and I have a windows laptop I could test firefox and chrome on as well.

it'd be super useful if we could find a way to make a preview build available somewhere

You mean as in a webpage? I could just make the github pages endpoint available on my fork.

[fingolfin]

You mean as in a webpage? I could just make the github pages endpoint available on my fork.

That would be super helpful!

[langestefan]

That would be super helpful!

Should work now: https://langestefan.github.io/Documenter.jl

To test:

Redirect to home page

The following page is not available on the v1.16 version: https://langestefan.github.io/Documenter.jl/dev/test-another-feature/

Switching to v1.16 from that page should therefore redirect to

https://langestefan.github.io/Documenter.jl/v1.16.

Stay on page when switching version

Links that are available on all versions, for example https://langestefan.github.io/Documenter.jl/dev/lib/public/

So switching to v1.16 should link back to https://langestefan.github.io/Documenter.jl/v1.16/lib/public/

Still need to update the banner

This banner that appears at the top still links to the home page and not the current page:

This documentation is for an older version that may be missing recent changes.
Click here to go to the documentation for the latest stable release.

Direct links do not forward to the right page

A direct link to https://langestefan.github.io/Documenter.jl/v1.16/test-another-feature/ still yields a 404. So this only works if you use the version drop down menu. I'm personally okay with keeping it that way.

[asinghvi17]

on the long run (after this PR is merged) a way to "upgrade" existing documentation versions to also support this
i.e. I guess one needs to iterate over all assets/documenter.js files in a gh-pages branch and "patch" them suitably, which might be a matter of searching&replacing a fixed substring -- or multiple, dunno how often this segment of the code changed over the years)

It would be nice if this could be directly automated in deploydocs, which has access to the whole gh-pages branch. But we should make sure any link rewriting isn't going to mess with Vitepress.

[langestefan]

I'm not sure that belongs in this PR. I'd like to limit it to fixing the version button

[fingolfin]

Very good. The JavaScript code looks plausible to me and is clearly documented.

So let's try to wrap it up then?

• format code with prettier 1.x
• add changelog entry
• fix the version banner to also use this feature

Then I hope we can merge this soon. The "upgrade existing installations feature" can be implemented separately.

[langestefan]

@fingolfin The banner doesn't seem to be functioning correctly, no matter what forwarding logic I try it will not bring me back to the same page. After trying for a few hours, I conclude that I unfortunately don't have the JS skills to fix it (or even understand what's going on). I suggest we leave the banner what it is for now.

Regarding prettier. I ran the prettier formatter locally and pushed the changes, but CI prettier check still fails. There is no debug output at all on the CI so there is nothing for me to go on. It would be really helpful for future devs if you could add maybe a pre-commit file or something so I can replicate what the CI is doing locally. If the CI can't tell me what's wrong then I can't fix it.

[fingolfin]

I've not used prettier myself, all I know is what the Documenter manual says about it:

We use Prettier v2 for formatting the HTML/web front end related code.

Well and also that https://prettier.io/docs/install has some instructions on using it, but that's for v3 and for some reason Documenter uses v2; I am sure someone who knows npm will easily be able to adapt those instructions to run v2 (and my guess is that ChatGPT and friends will also help doing that; but I am not going to go down that rabbit hole, I already have enough on my plate...)

Regarding making this more convenient for contributors: I agree! See also issues #2528 and #2529 (in short: "someone" should indeed make this nicer, now that "someone" just needs to show up ... :-/ )

(BTW that someone may also have to look into forking actionsx/prettier as that repo has been dormant for 2 years, and not even dependabot PRs are being merged; as GH constantly evolves the containers for its actions, that means that an action may eventually become unusable if it is not update to work with the latest Node.js etc....)

[mortenpi]

but that's for v3 and for some reason Documenter uses v2

I've been keeping this at v2 because the (official) Prettier VS Code extension is stuck on v2 😞

[langestefan]

I've been keeping this at v2 because the (official) Prettier VS Code extension is stuck on v2

I think Biome would be a good replacement. It has both a github CI action and a pre-commit hook. That way you can tell devs to run pre-commit with your own provided config file, and it will produce identical results to the github CI.

[fingolfin]

Seems Biome also has first party VS Code support. Sounds good. Would you be interested in working on that, @langestefan ? Or, alternatively, to open an issue suggesting this?

[fingolfin]

It is somewhat unfortunate that the warner.js code is not updated, because that's actually a pretty common place where I miss that functionality.

But the perfect shouldn't be enemy of the good: this PR is already a great improvement. Perhaps we can open an issue after merging it which requests that a similar change be implemented in warner.js, and perhaps someone else will come along to figure it out.

(Likewise an issue could be opened for adding tooling which updates the JS of older documentation versions so that they also benefit from this change).

[langestefan]

Would you be interested in working on that, @langestefan

Sure! I will open an issue first to discuss.

It is somewhat unfortunate that the warner.js code is not updated, because that's actually a pretty common place where I miss that functionality.

I will take another look at it again this weekend. If I can fix it I will make a PR.

[fingolfin]

I figured out that I can run prettier v2 via npx prettier@v2 . --write and that seems to be it. Of course that requires node to be installed (which I did on macos via brew install node).

I've pushed an update to this PR.

[fingolfin]

Hm, weird, prettier check still fails. Locally I see this:

$ npx prettier@v2 . --write
Need to install the following packages:
[email protected]
Ok to proceed? (y)

.prettierrc 31ms
assets/html/js/collapse.js 14ms
assets/html/js/copy.js 6ms
assets/html/js/footnote.js 6ms
assets/html/js/headroom.js 1ms
assets/html/js/metadata.js 2ms
assets/html/js/search.js 25ms
assets/html/js/settings.js 2ms
assets/html/js/shortcut.js 5ms
assets/html/js/sidebar.js 3ms
assets/html/js/themes.js 2ms
assets/html/js/versions.js 3ms
assets/html/themeswap.js 2ms
assets/html/warner.js 2ms
coverage/.codecov.yml 2ms
docs/versions.js 0ms

$ npx prettier@v2 . --check
Need to install the following packages:
[email protected]
Ok to proceed? (y)

Checking formatting...
All matched files use Prettier code style!