docusaurus: Error when using symlinked docs folder: Module parse failed: Assigning to rvalue

I have the same problem and symlinks: false solve it, add this to docusaurus.config.js and you are ready to go on symlinked folders, also HMR works ok 👌:

plugins: [
  function (context, options) {
    return {
      name: 'webpack-configuration-plugin',
      configureWebpack(config, isServer, utils) {
        return {
          resolve: {
            symlinks: false,
          }
        };
      }
    };
  },
],

@kewp we don’t read any webpack.config.js file.

The doc to create a local plugin is very simple: https://v2.docusaurus.io/docs/using-plugins#creating-plugins https://v2.docusaurus.io/docs/lifecycle-apis#configurewebpackconfig-isserver-utils

I think something like that:

module.exports = function(context, options) {
  return {
    name: "custom-docusaurus-plugin",
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          symlinks: false
        }
      };
    }
  };
};

great, we’ll figure out later if using symlinks inside the docs root folder is necessary.

If you have this need please explain your usecase.

I’ve added a new docs plugin instance using a root symlink so that we keep this behavior working over time. CI builds fine on linux/windows: https://deploy-preview-5126--docusaurus-2.netlify.app/docs-tests

FYI I coudn’t find any reason to use symlink: true.

I see it the same way, users should be able to use symlinked docs folder.

Do you all have the same use-case to create a single symlink for the root docs folder?

I’m going to use it this way, I hope that this was only one problem which I come across. I’m going to use it this way because I want to have documentation to be a part of the main project and create a new repository for the docusaurus.

So I will have two repos, main project eg. xyz and second repo xyz-github.io which will generate documentation with docusaurus and deploy to github.io. xyz-github.io will have symlinked docs folder to xyz/docs folder.

Going to revert to false in #5126

Nice thank you 🙏 For me it makes sense.

Yes! @CyborgMaster this is what fixed it for me.

For me, my user folder c:\users\karl is actually a symlink to c:\users\karlp. If I try run npm run start from the symlink folder it fails but it works from the actually one!

I assume what you’re thinking is correct - that webpack doesn’t understand symbolic links. Somehow some of the files are not being found.

Yes, only the docs plugin resolve relative md file paths currently and it’s limited to the scope of a single instance. We need some additional infrastructure so that plugins can expose to each others a filePath => absolute url mapping. But anyway if 2 instances have different version schemes you’d rather avoid such links because it won’t play well with versioning, as the versined docs would be in a totally different folders. In such case we’ll probably need to support something like [SomeLink](@site/docs/myDoc.md) to make those links easier to version.

Unfortunately, I have to revert the change I made (https://github.com/facebook/docusaurus/pull/5164).

There is a bug in Webpack 5 caching and using resolve.symlinks: false lead to deploying a Docusaurus site with stale cache entries.

If you implement a Docusaurus plugin as part of a monorepo and change some UI code, your new deployment (dev + prod) may not see your changes. Not many sites will be affected by this in practice (theme components should be fine fine), but it’s particularly painful for ourselves: Docusaurus PR Netlify deploy previews show stale UI components.

If you decide to stick to using webpack.resolve.symlinks = false in your site for symlinks reasons, and have some monorepo UI lib symlinked, I recommend to run docusaurus clear to be free of nasty side-effects.

Also, I’m not sure using symlinks: false is a good solution, and webpack contributors do not seem to agree it’s a good idea to use false either.

I’d like to recommend another workaround: instead of using symlinks: false, you can try to resolve the symlink to the real location, directly in your config:

    [
      '@docusaurus/plugin-content-docs',
      {
        routeBasePath: 'docs',
        sidebarPath: 'sidebars.js',
        path: fs.realpathSync('docs-symlink'),
      },
    ],

Please let me know if this workaround works for your site.

We’ll only try to apply symlinks: false again if some come up with a case where it does not work and we can’t find any other solution (repros / linked repos appreciated)

So I will have two repos, main project eg. xyz and second repo xyz-github.io which will generate documentation with docusaurus and deploy to github.io. xyz-github.io will have symlinked docs folder to xyz/docs folder.

That’s very much like my use case as well, just to say.

FYI I coudn’t find any reason to use symlink: true. The code introducing this is very old and does not explain this setting (https://github.com/facebook/docusaurus/commit/2ab412e563e4aa7ac87d05edaa05ebbfb4c7d8d1)

Going to revert to false in https://github.com/facebook/docusaurus/pull/5126

Using a symlinked folder as source docs seems to work fine (in dev/watchmode + prod)

Using symlinks inside the regular docs folder does not really work, and probably require more work so that features such as auto-generated sidebars etc work as intended.

Do you all have the same use-case to create a single symlink for the root docs folder?

Set resolve.symlinks: false is works. But when I modify the docs, the local site does not auto refresh and display the new modified content.

In the latest version of watchpack (v2.x), it added a followSymlinks option to solve this problem, but this requires us to upgrade webpack to the latest v5.x version.

Another issue with this symlinks error: https://github.com/facebook/docusaurus/issues/3579

Maybe we should consider switching symlinks to false by default. Not sure about the impact of this, so we’d rather be prepared to revert if users report bugs after release

Ok great to know.

Not sure what I can do about this issue, so I’m closing, but let’s reopen it if other users are affected and we get more info.