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

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

@@ -10,14 +10,20 @@ import path from 'path';
 import pluginContentBlog from '../index';
 import {DocusaurusConfig, LoadContext, I18n} from '@docusaurus/types';
 import {PluginOptionSchema} from '../pluginOptionSchema';
+import {PluginOptions, EditUrlFunction} from '../types';
+import Joi from 'joi';
 
 const DefaultI18N: I18n = {
   currentLocale: 'en',
   locales: ['en'],
   defaultLocale: 'en',
+  localeConfigs: {},
 };
 
-function validateAndNormalize(schema, options) {
+function validateAndNormalize(
+  schema: Joi.ObjectSchema,
+  options: Partial<PluginOptions>,
+) {
   const {value, error} = schema.validate(options);
   if (error) {
     throw error;
@@ -27,8 +33,14 @@ function validateAndNormalize(schema, options) {
 }
 
 describe('loadBlog', () => {
-  const pluginPath = 'blog';
-  const getBlogPosts = async (siteDir) => {
+  const PluginPath = 'blog';
+
+  const BaseEditUrl = 'https://baseEditUrl.com/edit';
+
+  const getBlogPosts = async (
+    siteDir: string,
+    pluginOptions: Partial<PluginOptions> = {},
+  ) => {
     const generatedFilesDir: string = path.resolve(siteDir, '.docusaurus');
     const siteConfig = {
       title: 'Hello',
@@ -43,12 +55,12 @@ describe('loadBlog', () => {
         i18n: DefaultI18N,
       } as LoadContext,
       validateAndNormalize(PluginOptionSchema, {
-        path: pluginPath,
-        editUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website-1x',
+        path: PluginPath,
+        editUrl: BaseEditUrl,
+        ...pluginOptions,
       }),
     );
-    const {blogPosts} = await plugin.loadContent();
+    const {blogPosts} = (await plugin.loadContent!())!;
 
     return blogPosts;
   };
@@ -58,14 +70,13 @@ describe('loadBlog', () => {
     const blogPosts = await getBlogPosts(siteDir);
 
     expect({
-      ...blogPosts.find((v) => v.metadata.title === 'date-matter').metadata,
+      ...blogPosts.find((v) => v.metadata.title === 'date-matter')!.metadata,
       ...{prevItem: undefined},
     }).toEqual({
-      editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/date-matter.md',
+      editUrl: `${BaseEditUrl}/blog/date-matter.md`,
       permalink: '/blog/date-matter',
       readingTime: 0.02,
-      source: path.posix.join('@site', pluginPath, 'date-matter.md'),
+      source: path.posix.join('@site', PluginPath, 'date-matter.md'),
       title: 'date-matter',
       description: `date inside front matter`,
       date: new Date('2019-01-01'),
@@ -81,10 +92,9 @@ describe('loadBlog', () => {
     expect(
       blogPosts.find(
         (v) => v.metadata.title === 'Happy 1st Birthday Slash! (translated)',
-      ).metadata,
+      )!.metadata,
     ).toEqual({
-      editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website-1x/i18n/en/docusaurus-plugin-content-blog/2018-12-14-Happy-First-Birthday-Slash.md',
+      editUrl: `${BaseEditUrl}/blog/2018-12-14-Happy-First-Birthday-Slash.md`,
       permalink: '/blog/2018/12/14/Happy-First-Birthday-Slash',
       readingTime: 0.015,
       source: path.posix.join(
@@ -105,14 +115,13 @@ describe('loadBlog', () => {
     });
 
     expect({
-      ...blogPosts.find((v) => v.metadata.title === 'Complex Slug').metadata,
+      ...blogPosts.find((v) => v.metadata.title === 'Complex Slug')!.metadata,
       ...{prevItem: undefined},
     }).toEqual({
-      editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/complex-slug.md',
+      editUrl: `${BaseEditUrl}/blog/complex-slug.md`,
       permalink: '/blog/hey/my super path/héllô',
       readingTime: 0.015,
-      source: path.posix.join('@site', pluginPath, 'complex-slug.md'),
+      source: path.posix.join('@site', PluginPath, 'complex-slug.md'),
       title: 'Complex Slug',
       description: `complex url slug`,
       prevItem: undefined,
@@ -126,14 +135,13 @@ describe('loadBlog', () => {
     });
 
     expect({
-      ...blogPosts.find((v) => v.metadata.title === 'Simple Slug').metadata,
+      ...blogPosts.find((v) => v.metadata.title === 'Simple Slug')!.metadata,
       ...{prevItem: undefined},
     }).toEqual({
-      editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/simple-slug.md',
+      editUrl: `${BaseEditUrl}/blog/simple-slug.md`,
       permalink: '/blog/simple/slug',
       readingTime: 0.015,
-      source: path.posix.join('@site', pluginPath, 'simple-slug.md'),
+      source: path.posix.join('@site', PluginPath, 'simple-slug.md'),
       title: 'Simple Slug',
       description: `simple url slug`,
       prevItem: undefined,
@@ -147,6 +155,59 @@ describe('loadBlog', () => {
     });
   });
 
+  test('edit url with editLocalizedBlogs true', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const blogPosts = await getBlogPosts(siteDir, {editLocalizedFiles: true});
+
+    const localizedBlogPost = blogPosts.find(
+      (v) => v.metadata.title === 'Happy 1st Birthday Slash! (translated)',
+    )!;
+
+    expect(localizedBlogPost.metadata.editUrl).toEqual(
+      `${BaseEditUrl}/i18n/en/docusaurus-plugin-content-blog/2018-12-14-Happy-First-Birthday-Slash.md`,
+    );
+  });
+
+  test('edit url with editUrl function', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+
+    const hardcodedEditUrl = 'hardcoded-edit-url';
+    const editUrlFunction: EditUrlFunction = jest.fn(() => hardcodedEditUrl);
+
+    const blogPosts = await getBlogPosts(siteDir, {editUrl: editUrlFunction});
+
+    blogPosts.forEach((blogPost) => {
+      expect(blogPost.metadata.editUrl).toEqual(hardcodedEditUrl);
+    });
+
+    expect(editUrlFunction).toHaveBeenCalledTimes(5);
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'date-matter.md',
+      locale: 'en',
+    });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'draft.md',
+      locale: 'en',
+    });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'complex-slug.md',
+      locale: 'en',
+    });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'blog',
+      blogPath: 'simple-slug.md',
+      locale: 'en',
+    });
+    expect(editUrlFunction).toHaveBeenCalledWith({
+      blogDirPath: 'i18n/en/docusaurus-plugin-content-blog',
+      blogPath: '2018-12-14-Happy-First-Birthday-Slash.md',
+      locale: 'en',
+    });
+  });
+
   test('draft blog post not exists in production build', async () => {
     process.env.NODE_ENV = 'production';
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
@@ -162,17 +223,16 @@ describe('loadBlog', () => {
       'website-blog-without-date',
     );
     const blogPosts = await getBlogPosts(siteDir);
-    const noDateSource = path.posix.join('@site', pluginPath, 'no date.md');
+    const noDateSource = path.posix.join('@site', PluginPath, 'no date.md');
     const noDateSourceBirthTime = (
       await fs.stat(noDateSource.replace('@site', siteDir))
     ).birthtime;
 
     expect({
-      ...blogPosts.find((v) => v.metadata.title === 'no date').metadata,
+      ...blogPosts.find((v) => v.metadata.title === 'no date')!.metadata,
       ...{prevItem: undefined},
     }).toEqual({
-      editUrl:
-        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/no date.md',
+      editUrl: `${BaseEditUrl}/blog/no date.md`,
       permalink: '/blog/no date',
       readingTime: 0.01,
       source: noDateSource,

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -26,6 +26,7 @@ import {
   aliasedSitePath,
   getEditUrl,
   getFolderContainingFile,
+  posixPath,
 } from '@docusaurus/utils';
 import {LoadContext} from '@docusaurus/types';
 import {keyBy} from 'lodash';
@@ -99,7 +100,7 @@ export async function generateBlogFeed(
 
 export async function generateBlogPosts(
   contentPaths: BlogContentPaths,
-  {siteConfig, siteDir}: LoadContext,
+  {siteConfig, siteDir, i18n}: LoadContext,
   options: PluginOptions,
 ): Promise<BlogPost[]> {
   const {
@@ -107,7 +108,7 @@ export async function generateBlogPosts(
     routeBasePath,
     truncateMarker,
     showReadingTime,
-    editUrl,
+    editUrl: siteEditUrl,
   } = options;
 
   if (!fs.existsSync(contentPaths.contentPath)) {
@@ -124,18 +125,47 @@ export async function generateBlogPosts(
   await Promise.all(
     blogSourceFiles.map(async (blogSourceFile: string) => {
       // Lookup in localized folder in priority
-      const contentPath = await getFolderContainingFile(
+      const blogDirPath = await getFolderContainingFile(
         getContentPathList(contentPaths),
         blogSourceFile,
       );
 
-      const source = path.join(contentPath, blogSourceFile);
+      const source = path.join(blogDirPath, blogSourceFile);
+
       const aliasedSource = aliasedSitePath(source, siteDir);
 
-      const relativePath = path.relative(siteDir, source);
       const blogFileName = path.basename(blogSourceFile);
 
-      const editBlogUrl = getEditUrl(relativePath, editUrl);
+      function getBlogEditUrl() {
+        const blogPathRelative = path.relative(
+          blogDirPath,
+          path.resolve(source),
+        );
+
+        if (typeof siteEditUrl === 'function') {
+          return siteEditUrl({
+            blogDirPath: posixPath(path.relative(siteDir, blogDirPath)),
+            blogPath: posixPath(blogPathRelative),
+            locale: i18n.currentLocale,
+          });
+        } else if (typeof siteEditUrl === 'string') {
+          const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
+          const fileContentPath =
+            isLocalized && options.editLocalizedFiles
+              ? contentPaths.contentPathLocalized
+              : contentPaths.contentPath;
+
+          const contentPathEditUrl = normalizeUrl([
+            siteEditUrl,
+            posixPath(path.relative(siteDir, fileContentPath)),
+          ]);
+
+          return getEditUrl(blogPathRelative, contentPathEditUrl);
+        } else {
+          return undefined;
+        }
+      }
+      const editBlogUrl = getBlogEditUrl();
 
       const {frontMatter, content, excerpt} = await parseMarkdownFile(source);
 

packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts

@@ -34,6 +34,7 @@ export const DEFAULT_OPTIONS = {
   include: ['*.md', '*.mdx'],
   routeBasePath: 'blog',
   path: 'blog',
+  editLocalizedFiles: false,
 };
 
 export const PluginOptionSchema = Joi.object({
@@ -67,7 +68,8 @@ export const PluginOptionSchema = Joi.object({
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
   admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
-  editUrl: URISchema,
+  editUrl: Joi.alternatives().try(URISchema, Joi.function()),
+  editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
   truncateMarker: Joi.object().default(DEFAULT_OPTIONS.truncateMarker),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRemarkPlugins,

packages/docusaurus-plugin-content-blog/src/types.ts

@@ -24,6 +24,12 @@ export interface DateLink {
 
 export type FeedType = 'rss' | 'atom';
 
+export type EditUrlFunction = (editUrlParams: {
+  blogDirPath: string;
+  blogPath: string;
+  locale: string;
+}) => string | undefined;
+
 export interface PluginOptions {
   id?: string;
   path: string;
@@ -57,7 +63,8 @@ export interface PluginOptions {
     copyright: string;
     language?: string;
   };
-  editUrl?: string;
+  editUrl?: string | EditUrlFunction;
+  editLocalizedFiles?: boolean;
   admonitions: Record<string, unknown>;
 }