Docusaurus: editUrl assumes local path is the same as repository path

[thesamet]

🐛 Bug Report

In v2 alpha 59, the "Edit this page" links for content docs are generated by joining the editUrl with the path setting. I am using a markdown preprocessor that generates files into the provided path, so I would like the edit links to point at the original files, not the generated ones.

Have you read the Contributing Guidelines on issues?

Y

To Reproduce

(Write your steps here:)

in presets:

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          homePageId: 'intro',
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/scalapb/zio-grpc/edit/master/docs',
          path: '../zio-grpc-docs/target/mdoc'
        },

Expected behavior

The path setting doesn't play a part in the edit url. In other words, the editUrl will look like https://github.com/scalapb/zio-grpc/edit/master/docs/intro.md

Actual Behavior

The generated edit url contains the path to the generated file (which is not checked in):

https://github.com/scalapb/zio-grpc/edit/master/zio-grpc-docs/target/mdoc/intro.md

Your Environment

Repository: https://github.com/scalapb/zio-grpc
Markdown generator processes files in docs into zio-grpc-docs/target/mdoc.
To invoke it, install sbt, and type: sbt docs/mdoc. Then cd to website and do a yarn start.

The docs dire

[slorber]

Hi,

This may not be ideal but you can use the custom_edit_url frontmatter in the docs directly

[thesamet]

Thanks, I have a pretty small site, so this would be a reasonable workaround for the time being.

[slorber]

Great, let's close this for now and see if this becomes needed

[thesamet]

This would be an issue for some projects in the Scala community who use mdoc to preprocess and typecheck their markdown before passing it to Docusaurus. This breakage started when I explored updating to Docusaurus v2. Given that mdoc with Docusaurus v1 is already being used by a number of projects (see list in the previous link), I anticipate this issue to come up again. It would be nice to have it fixed so mdoc users would have some sort of a documented solution if they wish to try Docusaurus v2.

[slorber]

Thanks, didn't know about all this mdoc ecosystem still on v1 (reported here https://github.com/facebook/docusaurus/issues/3035).

Is it the only problem you had by migrating to v2?

[thesamet]

@slorber Yes, the rest was just changes that are documented in the migration docs.

[slorber]

Would it work for you if the editUrl was a function that takes the absolute doc path, and then you return the edit url?

Something like:

        docs: {
          editUrl: (absoluteMDPath) => getMDEditUrl(absoluteMDPath),
        },

[thesamet]

Getting a function would be fine, though I think it would be preferable to get the relative path to the docs directory - this way the function would get the same input in dev and on CI.

[slorber]

makes sense :)

[ifiokjr]

The way I've worked around this is to set the editUrl to the path of the directory in which the docusaurus website is hosted instead of where the docs are located.

Example

That way the edit path is automatically set to the correct path.

[thesamet]

@ifiokjr I think that the situation in remirror is different than the one described by this ticket. It appears that in remirror there's no preprocessing of the markdown by an external tool. The source markdown for Docusaurus are the same files that are being being linked to through editUrl. The use case for this ticket requires a more complex transformation of editUrl.

[slorber]

We'll likely need this feature to improve the translation experience too.

Feedback from v1: https://github.com/facebook/docusaurus/issues/648

If user is editing primary language, we should link to Github, otherwise we should allow user to link to his own translation system URL. We use crowdin but should be able to configure whatever system we want, so having a function is probably the best option here, to give full power to the user.