From 2c9d094a70be340ae6b9fa81c18f70eeac0ee9f5 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Fri, 29 Jan 2021 18:45:43 +0100
Subject: [PATCH 1/2] doc: suggest not using useBaseUrl most of the time

---
 .../docusaurus/src/server/plugins/index.ts    |  3 +-
 website/docs/docusaurus-core.md               | 51 +++++++++++++------
 website/docs/migration/migration-manual.md    |  7 +--
 3 files changed, 39 insertions(+), 22 deletions(-)

diff --git a/packages/docusaurus/src/server/plugins/index.ts b/packages/docusaurus/src/server/plugins/index.ts
index 32bb7ec44a86..16ee8867c348 100644
--- a/packages/docusaurus/src/server/plugins/index.ts
+++ b/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',
         ),
       );
 
diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md
index d7933277ac07..0a27147e522a 100644
--- a/website/docs/docusaurus-core.md
+++ b/website/docs/docusaurus-core.md
@@ -222,7 +222,18 @@ 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.
+:::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`
+
+:::
+
+React hook to automatically prepend `baseUrl` to a string automatically.
 
 ```ts
 type BaseUrlOptions = {
@@ -233,39 +244,47 @@ type BaseUrlOptions = {
 
 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>;
 };
 ```
 
diff --git a/website/docs/migration/migration-manual.md b/website/docs/migration/migration-manual.md
index 3ba179924f88..3774aa86ec6a 100644
--- a/website/docs/migration/migration-manual.md
+++ b/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>

From c1af0e64c22f03c960b513a8a3bcfb9700194482 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Fri, 29 Jan 2021 18:48:53 +0100
Subject: [PATCH 2/2] doc: suggest not using useBaseUrl most of the time

---
 website/docs/docusaurus-core.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md
index 0a27147e522a..50ffe6deb4b1 100644
--- a/website/docs/docusaurus-core.md
+++ b/website/docs/docusaurus-core.md
@@ -222,6 +222,8 @@ const MyComponent = () => {
 
 ### `useBaseUrl`
 
+React hook to prepend your site `baseUrl` to a string.
+
 :::caution
 
 **Don't use it for regular links!**
@@ -233,7 +235,7 @@ The `/baseUrl/` prefix is automatically added to all **absolute paths** by defau
 
 :::
 
-React hook to automatically prepend `baseUrl` to a string automatically.
+#### Options
 
 ```ts
 type BaseUrlOptions = {
@@ -242,7 +244,7 @@ type BaseUrlOptions = {
 };
 ```
 
-Example usage:
+#### Example usage:
 
 ```jsx
 import React from 'react';