feat(v2): editUrl function for advanced use-cases (#4121)

* EditUrl function

* normalize blog/docs regarding the editUrl feature + editUrl function

* editUrl fn => always inject posix style relative paths, make tests more reliable
(see also https://github.com/facebook/docusaurus/issues/4124)

* fix editUrl on windows

website/docs/api/plugins/plugin-content-blog.md

@@ -31,11 +31,23 @@ module.exports = {
          */
         path: 'blog',
         /**
-         * URL for editing a blog post.
-         * Example: 'https://github.com/facebook/docusaurus/edit/master/website/blog/'
+         * Base url to edit your site.
+         * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
          */
-        editUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/blog/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        /**
+         * For advanced cases, compute the edit url for each markdown file yourself.
+         */
+        editUrl: ({locale, blogDirPath, blogPath}) => {
+          return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
+        },
+        /**
+         * Useful if you commit localized files to git.
+         * When markdown files are localized, the edit url will target the localized file,
+         * instead of the original unlocalized file.
+         * Note: this option is ignored when editUrl is a function
+         */
+        editLocalizedFiles: false,
         /**
          * Blog page title for better SEO
          */

website/docs/api/plugins/plugin-content-docs.md

@@ -31,22 +31,30 @@ module.exports = {
          */
         path: 'docs',
         /**
-         * URL for editing a doc in the website repo.
-         * Example: 'https://github.com/facebook/docusaurus/edit/master/website/'
+         * Base url to edit your site.
+         * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
          */
         editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
         /**
+         * For advanced cases, compute the edit url for each markdown file yourself.
+         */
+        editUrl: function ({locale, version, versionDocsDirPath, docPath}) {
+          return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
+        },
+        /**
+         * Useful if you commit localized files to git.
+         * When markdown files are localized, the edit url will target the localized file,
+         * instead of the original unlocalized file.
+         * Note: this option is ignored when editUrl is a function
+         */
+        editLocalizedFiles: false,
+        /**
+         * Useful if you don't want users to submit doc pull-requests to older versions.
          * When docs are versioned, the edit url will link to the doc
          * in current version, instead of the versioned doc.
-         * Useful if you don't want users to submit doc pull-requests to older versions.
+         * Note: this option is ignored when editUrl is a function
          */
         editCurrentVersion: false,
-        /**
-         * When docs are localized, the edit url will target the localized doc,
-         * instead of the original unlocalized doc.
-         * Useful if you commit localized docs to git, instead of using a translation service.
-         */
-        editLocalizedDocs: false,
         /**
          * URL route for the docs section of your site.
          * *DO NOT* include a trailing slash.

website/docs/i18n/i18n-crowdin.mdx

@@ -409,6 +409,54 @@ Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`,
 
 :::
 
+### Localize edit urls
+
+When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`.
+
+You may prefer the edit button to link to the Crowdin interface instead, and can use the `editUrl` function to customize the edit urls on a per-locale basis.
+
+```js title="docusaurus.config.js"
+const DefaultLocale = 'en';
+
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          // highlight-start
+          editUrl: ({locale, versionDocsDirPath, docPath}) => {
+            // Link to Crowdin for French docs
+            if (locale !== DefaultLocale) {
+              return `https://crowdin.com/project/docusaurus-v2/${locale}`;
+            }
+            // Link to Github for English docs
+            return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
+          },
+          // highlight-end
+        },
+        blog: {
+          // highlight-start
+          editUrl: ({locale, blogDirPath, blogPath}) => {
+            if (locale !== DefaultLocale) {
+              return `https://crowdin.com/project/docusaurus-v2/${locale}`;
+            }
+            return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
+          },
+          // highlight-start
+        },
+      },
+    ],
+  ],
+};
+```
+
+:::note
+
+It is currently **not possible to link to a specific file** in Crowdin.
+
+:::
+
 ### Example configuration
 
 The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:

website/docs/i18n/i18n-git.md

@@ -171,3 +171,11 @@ New translation will be appended, and existing ones will not be overridden.
 Reset your translations with the `--override` option.
 
 :::
+
+### Localize edit urls
+
+When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`.
+
+Your translations are on Git, and you can use the `editLocalizedFiles: true` option of the docs and blog plugins.
+
+The edit button will link to the localized doc at `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.