Some comments for VersionPicker

[ytdHuang]

To the developers of DocumenterVitepress.jl,

I'm a developer of a package called QuantumToolbox.jl.

We recently saw the fancy documentation page you have and started to switch from the original Documenter.jl to Vitepress page.

I basically followed the same procedure from some of you did in Lux.jl, and faced some issues.

Although I think I resolved those issues, I still want to mention it here, to help improve DocumenterVitepress.jl and also see if there is a better solution.

1. Fix Symbolic links

When implementing the VersionPicker, it seems to be necessary that one needs to add a CI pipeline to gh-pages-branch to fix the symbolic links for the page (like this one implemented in Lux.jl).

However, the shell command executed in this CI pipeline:

find -type l -exec bash -c 'dir="$0"; newlnk=${dir:2}; lnk="$(readlink -m "$0")"; orglnk=$(basename $lnk); echo "$newlnk <--> $orglnk"; rm "$0"; cp -r $lnk "$0"; cd "$0"; grep "$orglnk" . -lr | xargs sed -i "s/$orglnk/$newlnk/g"; cd ..' {} \;

basically replace all the strings that matches the version tag (e.g., v0.12.3 for orglnk) to the tags listed in versions.js in gh-pages-branch (like stable or v0.12 for newlnk).

This not just changed the symbolic links, but also changed all the strings that has the same pattern v0.12.3 in the entire documentation.

For example, if one generates the changelog from Changelog.jl, there will also be a version tag inside the changelog, but the string and the corresponding hyperlink will be changed due to the replacement.

So I suggest to exactly specify the entire newlnk and orglnk, for example

url="lux.csail.mit.edu\/"
newlnk="$url${dir:2}"
orglnk="$url$(basename $lnk)"

which the command becomes

find -type l -exec bash -c 'dir="$0"; url="lux.csail.mit.edu\/"; newlnk="$url${dir:2}"; lnk="$(readlink -m "$0")"; orglnk="$url$(basename $lnk)"; echo "$newlnk <--> $orglnk"; rm "$0"; cp -r $lnk "$0"; cd "$0"; grep "$orglnk" . -lr | xargs sed -i "s/$orglnk/$newlnk/g"; cd ..' {} \;

so it only replace the entire "link"s instead of tags.

2. Typo

In PR #178, there's part of the code in .vitepress/theme/VersionPicker.vue:

const getBaseRepository = () => {
  if (typeof window === 'undefined') return ''; // Handle server-side rendering (SSR)
  const { origin, pathname } = window.location;
  // Check if it's a GitHub Pages (or similar) setup
  if (origin.includes('github.io')) {
    // Extract the first part of the path as the repository name
    const pathParts = pathname.split('/').filter(Boolean);
    const baseRepo = pathParts.length > 0 ? `/${pathParts[0]}/` : '/';
    return `${origin}${baseRepo}`;
  } else {
    // For custom domains, use just the origin (e.g., https://docs.makie.org)
    return origin;
  }
};

the baseRepo should be

const baseRepo = pathParts.length > 0 ? `/${pathParts[0]}` : ''; // don't add the final `/`

This gives the same behavior with the custom domain case. Otherwise, the links will become double / in the handling afterwards.

[lazarusA]

Thanks for the feedback. For 2, I can update the corresponding PR. But for 1, @avik-pal was the one that came up with that line, I would be happy to have an easy copy/paste CI template for this in the documentation, if possible a PR documenting this is very welcome.

[asinghvi17]

If it's sufficiently easy to do in Julia, we can even do it automatically in DocumenterVitepress, would save a lot of headaches.