feat(v2): add useBaseUrlUtils() hook (#3033)

* add useBaseUrlUtils

* fix code highlighted lines

packages/docusaurus/src/client/exports/__tests__/useBaseUrl.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import useBaseUrl from '../useBaseUrl';
+import useBaseUrl, {useBaseUrlUtils} from '../useBaseUrl';
 import useDocusaurusContext from '../useDocusaurusContext';
 
 jest.mock('../useDocusaurusContext', () => jest.fn(), {virtual: true});
@@ -65,3 +65,59 @@ describe('useBaseUrl', () => {
     );
   });
 });
+
+describe('useBaseUrlUtils().withBaseUrl()', () => {
+  test('empty base URL', () => {
+    mockedContext.mockImplementation(() => ({
+      siteConfig: {
+        baseUrl: '/',
+        url: 'https://v2.docusaurus.io',
+      },
+    }));
+    const {withBaseUrl} = useBaseUrlUtils();
+
+    expect(withBaseUrl('hello')).toEqual('/hello');
+    expect(withBaseUrl('/hello')).toEqual('/hello');
+    expect(withBaseUrl('hello/')).toEqual('/hello/');
+    expect(withBaseUrl('/hello/')).toEqual('/hello/');
+    expect(withBaseUrl('hello/byebye')).toEqual('/hello/byebye');
+    expect(withBaseUrl('/hello/byebye')).toEqual('/hello/byebye');
+    expect(withBaseUrl('hello/byebye/')).toEqual('/hello/byebye/');
+    expect(withBaseUrl('/hello/byebye/')).toEqual('/hello/byebye/');
+    expect(withBaseUrl('https://github.com')).toEqual('https://github.com');
+    expect(withBaseUrl('//reactjs.org')).toEqual('//reactjs.org');
+    expect(
+      withBaseUrl('https://site.com', {forcePrependBaseUrl: true}),
+    ).toEqual('/https://site.com');
+    expect(withBaseUrl('/hello/byebye', {absolute: true})).toEqual(
+      'https://v2.docusaurus.io/hello/byebye',
+    );
+  });
+
+  test('non-empty base URL', () => {
+    mockedContext.mockImplementation(() => ({
+      siteConfig: {
+        baseUrl: '/docusaurus/',
+        url: 'https://v2.docusaurus.io',
+      },
+    }));
+    const {withBaseUrl} = useBaseUrlUtils();
+
+    expect(withBaseUrl('hello')).toEqual('/docusaurus/hello');
+    expect(withBaseUrl('/hello')).toEqual('/docusaurus/hello');
+    expect(withBaseUrl('hello/')).toEqual('/docusaurus/hello/');
+    expect(withBaseUrl('/hello/')).toEqual('/docusaurus/hello/');
+    expect(withBaseUrl('hello/byebye')).toEqual('/docusaurus/hello/byebye');
+    expect(withBaseUrl('/hello/byebye')).toEqual('/docusaurus/hello/byebye');
+    expect(withBaseUrl('hello/byebye/')).toEqual('/docusaurus/hello/byebye/');
+    expect(withBaseUrl('/hello/byebye/')).toEqual('/docusaurus/hello/byebye/');
+    expect(withBaseUrl('https://github.com')).toEqual('https://github.com');
+    expect(withBaseUrl('//reactjs.org')).toEqual('//reactjs.org');
+    expect(
+      withBaseUrl('https://site.com', {forcePrependBaseUrl: true}),
+    ).toEqual('/docusaurus/https://site.com');
+    expect(withBaseUrl('/hello/byebye', {absolute: true})).toEqual(
+      'https://v2.docusaurus.io/docusaurus/hello/byebye',
+    );
+  });
+});

packages/docusaurus/src/client/exports/useBaseUrl.ts

@@ -8,19 +8,17 @@
 import useDocusaurusContext from './useDocusaurusContext';
 import isInternalUrl from './isInternalUrl';
 
-type BaseUrlOptions = {
+type BaseUrlOptions = Partial<{
   forcePrependBaseUrl: boolean;
   absolute: boolean;
-};
+}>;
 
-export default function useBaseUrl(
+function addBaseUrl(
+  siteUrl: string | undefined,
+  baseUrl: string,
   url: string,
-  {forcePrependBaseUrl = false, absolute = false}: Partial<BaseUrlOptions> = {},
+  {forcePrependBaseUrl = false, absolute = false}: BaseUrlOptions = {},
 ): string {
-  const {
-    siteConfig: {baseUrl = '/', url: siteUrl} = {},
-  } = useDocusaurusContext();
-
   if (!url) {
     return url;
   }
@@ -37,3 +35,26 @@ export default function useBaseUrl(
 
   return absolute ? siteUrl + basePath : basePath;
 }
+
+export type BaseUrlUtils = {
+  withBaseUrl: (url: string, options: BaseUrlOptions) => string;
+};
+
+export function useBaseUrlUtils(): BaseUrlUtils {
+  const {
+    siteConfig: {baseUrl = '/', url: siteUrl} = {},
+  } = useDocusaurusContext();
+  return {
+    withBaseUrl: (url, options) => {
+      return addBaseUrl(siteUrl, baseUrl, url, options);
+    },
+  };
+}
+
+export default function useBaseUrl(
+  url: string,
+  options: BaseUrlOptions,
+): string {
+  const {withBaseUrl} = useBaseUrlUtils();
+  return withBaseUrl(url, options);
+}

website/docs/docusaurus-core.md

@@ -169,7 +169,7 @@ type BaseUrlOptions = {
 Example usage:
 
 ```jsx {3,11}
-import React, {useEffect} from 'react';
+import React from 'react';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
@@ -186,6 +186,24 @@ function Help() {
 }
 ```
 
+### `useBaseUrlUtils`
+
+Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
+
+- `withBaseUrl`: useful if you need to add base urls to multiple urls at once
+
+```jsx {2,5,6,7}
+import React from 'react';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+
+function Component() {
+  const urls = ['/a', '/b'];
+  const {withBaseUrl} = useBaseUrlUtils();
+  const urlsWithBaseUrl = urls.map(withBaseUrl);
+  return <div className="col">{/* ... */}</div>;
+}
+```
+
 ## Modules
 
 ### `ExecutionEnvironment`