Wrong Pagination links for symlinked folders

[lebalz]

I'm organizing multiple courses for different grades - they share sometimes the exact same material, but sometimes the material differs from course to course.

I use the /docs folder to place all the material in. Each course gets it's own version, e.g. versioned_docs/version-courseA. I then create symlinks to the material, that was presented in the concrete course (e.g. to enable the material about loops in js for course A, i would do (cd "versioned_docs/version-courseA" && /bin/ln -s "../../docs/js-loops" .)).

Everything works as expected, expect the pagination: When using the pagination to go to the next page, and then wanting to go back again, it will not be anymore the versioned page for this course...

Code Sandbox

🐛 Bug Report

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io
• I have read the console error message carefully (if applicable)

Description

When having a symlinked folder in a versioned docs folder pointing to a folder in /docs (e.g. versioned_docs/version-courseA/js-basics --> /docs/js-basics), the pagination will not work when navigate over it. When clicking "Next" (or "Previous"), the following pagination is not in sync with the sidebar and points instead to the "Next" (and "Previous") Page of the /docs folder structure.

Have you read the Contributing Guidelines on issues?

Yes.

Steps to reproduce

1. Launch the Code Sandbox
2. navigate to e.g. "Course A" (you will land on page courseA/intro)
3. Click "Next" (Javascript Basics) - you will land on /courseA/js-basics/basics)
4. Notice: Even there should not be another "Next" Button (the Sidebar lists only the intro and the "JS Basics"), there is a "Next" button...
5. Click "Previous" and instead of landing on page courseA/intro, you land on /intro
   Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.

Expected behavior

The pagination is in sync with the sidebar, even when having symlinked folders.

Actual behavior

The links for the pagination are created before webpacker resolves the symlinks.

Your environment

https://codesandbox.io/s/gifted-darkness-mzxgp

Reproducible demo

https://codesandbox.io/s/gifted-darkness-mzxgp

[slorber]

We don't support symlinks well currently, particularly when they are nested inside the docs folder.

Eventually, you can make the root docs folder a symlink, but that requires changing a Webpack setting (+ there is a webpack caching bug). See #5126

I'd suggest for now to:

• not use symlinks inside docs
• resolve a potential docs symlink to the real path directly in your symlink

---

About use-case. I have no idea why you want to create a symlink such as versioned_docs/version-courseA/js-basics --> /docs/js-basics, it does not make sense to me and it's unlikely we support this kind of fancy feature in the future (even if we support symlinks better). A unique URL path is assigned to each filesystem source file, and it would be complicated to make Docusaurus understand that the url should be different according to which symlink was used to navigate to this doc.

What are your motivations? I don't understand your usecase. You should keep your most up-to-date docs (current version) in the /docs folder instead of creating symlinks. The versioned folder is for older / already released versions, once created you should not edit them much unless you want to backport changes for some reasons.

Notice: Even there should not be another "Next" Button (the Sidebar lists only the intro and the "JS Basics"), there is a "Next" button...

No, your sidebars file is using a single sidebar for a whole docs version, this means that all your courses are part of the same sidebar and you can then navigate from one course to another with pagination.

If you don't want this to happen, use multiple sidebars (autogenerated or not).

You can also try to use multiple docs plugin instances, in which case each instance docs folder is better isolated and can be configured independently to the location of your choice (including symlinks if you configure webpack, or absolute paths, git submodules or whatever you use)

[slorber]

Note: On CodeSandbox, I see regular folders and am not even sure symlinks work (at least can't see them). Also suggest to try this outside of Codesandbox as sometimes there are caching issues and CodeSandbox still see old files.

See how your original sandbox and my fork gives a different result (didn't change anything):

This one (yours) look wrong according to your side content:

Mine looks better:

[lebalz]

Thank you very much for your quick reply.

About my use case: you are right, it is not the standard of a documentation website. But there are no really suitable frameworks for parallel courses. But with versioning this could be adapted relatively "easy". I am aware that in the classic case older versions should not be changed if possible. For teaching, however, the "same version" should be made available at different times for individual courses. Therefore the hack with the symlinks...

Currently I already use different sidebars (versioned_sidebars) and that works, except for the pagination...

[lebalz]

Note: On CodeSandbox, I see regular folders and am not even sure symlinks work (at least can't see them). Also suggest to try this outside of Codesandbox as sometimes there are caching issues and CodeSandbox still see old files.

See how your original sandbox and my fork gives a different result (didn't change anything):

This one (yours) look wrong according to your side content:

Mine looks better:

Hmm, i'm not sure how code sandbox is managing this actually, but my sidebar shall look like my version... (since i wanted to make "js intro" available only to the courseA, but not to courseB, however the ground truth of all material lies in the docs folder... do you see the scenario?

The created symlinks should work and are looking as follows on my machine...

[slorber]

This folder contains a single file:

So it's very unexpected that you end up with a sidebar of 2 elements on path /courseA. It should only contain the file in this folder, this is the intended behavior.

[lebalz]

This folder contains a single file:

So it's very unexpected that you end up with a sidebar of 2 elements on path /courseA. It should only contain the file in this folder, this is the intended behavior.

Okay, sadly CodeSandbox does not copy symlinks when forking :(. To see the weird behavior you would need to execute the following command in the terminal of codesandbox:

(cd "versioned_docs/version-courseA" && /bin/ln -s "../../docs/js-loops" .)

Thanks again for your support.

[slorber]

I see, but even it's not something you should do and not likely that we'll want to support that either, so you'd rather use another option.

You can copy files around in your build process if needed