fix(v2): doc path special char (space or other) should lead to a valid slug (#3262)

* doc path special char (space or other) should lead to a valid slug

* doc path special char (space or other) should lead to a valid slug

* improve doc bad slug message

packages/docusaurus-plugin-content-docs/src/__tests__/slug.test.ts

@@ -15,6 +15,13 @@ describe('getSlug', () => {
     );
   });
 
+  // See https://github.com/facebook/docusaurus/issues/3223
+  test('should handle special chars in doc path', () => {
+    expect(
+      getSlug({baseID: 'my dôc', dirName: '/dir with spâce/hey $hello'}),
+    ).toEqual('/dir with spâce/hey $hello/my dôc');
+  });
+
   test('should handle current dir', () => {
     expect(getSlug({baseID: 'doc', dirName: '.'})).toEqual('/doc');
     expect(getSlug({baseID: 'doc', dirName: '/'})).toEqual('/doc');

packages/docusaurus-plugin-content-docs/src/slug.ts

@@ -33,7 +33,16 @@ export default function getSlug({
 
   if (!isValidPathname(slug)) {
     throw new Error(
-      `Unable to resolve valid document slug. Maybe your slug frontmatter is incorrect? Doc id=${baseID} / dirName=${dirName} / frontmatterSlug=${frontmatterSlug} => bad result slug=${slug}`,
+      `We couldn't compute a valid slug for document with id=${baseID} in folder=${dirName}
+The slug we computed looks invalid: ${slug}
+Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
+By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
+
+Example =>
+---
+slug: /my/customDocPath
+---
+`,
     );
   }
 

packages/docusaurus-utils/src/__tests__/index.test.ts

@@ -394,10 +394,11 @@ describe('load utils', () => {
     expect(isValidPathname('/hey/ho/')).toBe(true);
     expect(isValidPathname('/hey/h%C3%B4/')).toBe(true);
     expect(isValidPathname('/hey///ho///')).toBe(true); // Unexpected but valid
+    expect(isValidPathname('/hey/héllô you')).toBe(true);
+
     //
     expect(isValidPathname('')).toBe(false);
     expect(isValidPathname('hey')).toBe(false);
-    expect(isValidPathname('/hey/hô')).toBe(false);
     expect(isValidPathname('/hey?qs=ho')).toBe(false);
     expect(isValidPathname('https://fb.com/hey')).toBe(false);
     expect(isValidPathname('//hey')).toBe(false);

packages/docusaurus-utils/src/index.ts

@@ -365,7 +365,8 @@ export function isValidPathname(str: string): boolean {
   }
   try {
     // weird, but is there a better way?
-    return new URL(str, 'https://domain.com').pathname === str;
+    const parsedPathname = new URL(str, 'https://domain.com').pathname;
+    return parsedPathname === str || parsedPathname === encodeURI(str);
   } catch (e) {
     return false;
   }