docs(v2): do not recommend using useBaseUrl() hook in most cases

packages/docusaurus/src/server/plugins/index.ts

@@ -195,9 +195,10 @@ export async function loadPlugins({
 
       // TODO remove this deprecated lifecycle soon
       // deprecated since alpha-60
+      // TODO, 1 user reported usage of this lifecycle! https://github.com/facebook/docusaurus/issues/3918
       console.error(
         chalk.red(
-          'plugin routesLoaded lifecycle is deprecated. If you think we should keep this lifecycle, please open a Github issue with your usecase',
+          'plugin routesLoaded lifecycle is deprecated. If you think we should keep this lifecycle, please report here: https://github.com/facebook/docusaurus/issues/3918',
         ),
       );
 

website/docs/docusaurus-core.md

@@ -222,7 +222,20 @@ const MyComponent = () => {
 
 ### `useBaseUrl`
 
-React hook to automatically prepend `baseUrl` to a string automatically. This is particularly useful if you don't want to hardcode your config's `baseUrl`. We highly recommend you to use this.
+React hook to prepend your site `baseUrl` to a string.
+
+:::caution
+
+**Don't use it for regular links!**
+
+The `/baseUrl/` prefix is automatically added to all **absolute paths** by default:
+
+- Markdown: `[link](/my/path)` will link to `/baseUrl/my/path`
+- React: `<Link to="/my/path/">link</Link>` will link to `/baseUrl/my/path`
+
+:::
+
+#### Options
 
 ```ts
 type BaseUrlOptions = {
@@ -231,41 +244,49 @@ type BaseUrlOptions = {
 };
 ```
 
-Example usage:
+#### Example usage:
 
-```jsx {3,11}
+```jsx
 import React from 'react';
-import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-const Help = () => {
-  return (
-    <div className="col">
-      <h2>Browse the docs</h2>
-      <p>
-        Learn more about Docusaurus using the{' '}
-        <Link to={useBaseUrl('docs/introduction')}>official documentation</Link>
-      </p>
-    </div>
-  );
+const SomeImage = () => {
+  // highlight-start
+  const imgSrc = useBaseUrl('/img/myImage.png');
+  // highlight-end
+  return <img src={imgSrc} />;
 };
 ```
 
+:::tip
+
+In most cases, you don't need `useBaseUrl`.
+
+Prefer a `require()` call for [assets](./guides/markdown-features/markdown-features-assets.mdx):
+
+```jsx
+<img src={require('@site/static/img/myImage.png').default} />
+```
+
+:::
+
 ### `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
+- `withBaseUrl`: useful if you need to add base urls to multiple urls at once.
 
-```jsx {2,5-7}
+```jsx
 import React from 'react';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 
 const Component = () => {
   const urls = ['/a', '/b'];
+  // highlight-start
   const {withBaseUrl} = useBaseUrlUtils();
   const urlsWithBaseUrl = urls.map(withBaseUrl);
-  return <div className="col">{/* ... */}</div>;
+  // highlight-end
+  return <div>{/* ... */}</div>;
 };
 ```
 

website/docs/migration/migration-manual.md

@@ -515,15 +515,12 @@ Here's a typical Docusaurus v2 page:
 import React from 'react';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import useBaseUrl from '@docusaurus/useBaseUrl';
 import Layout from '@theme/Layout';
 
 const MyPage = () => {
   const {siteConfig} = useDocusaurusContext();
   return (
-    <Layout
-      title={siteConfig.title}
-      description={siteConfig.tagline}>
+    <Layout title={siteConfig.title} description={siteConfig.tagline}>
       <div className="hero text--center">
         <div className="container ">
           <div className="padding-vert--md">
@@ -532,7 +529,7 @@ const MyPage = () => {
           </div>
           <div>
             <Link
-              to={useBaseUrl('/docs/get-started')}
+              to="/docs/get-started"
               className="button button--lg button--outline button--primary">
               Get started
             </Link>