docs(v2): improve bad static assets doc + remove some useless useBase…

…Url usage (#4158)
facebook · Feb 2, 2021 · e807bff · e807bff
1 parent f5494af
commit e807bff
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 34 deletions.
diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx
@@ -127,8 +127,8 @@ import ThemedImage from '@theme/ThemedImage';
 <ThemedImage
   alt="Docusaurus themed image"
   sources={{
-    light: useBaseUrl('img/docusaurus_light.svg'),
-    dark: useBaseUrl('img/docusaurus_dark.svg'),
+    light: useBaseUrl('/img/docusaurus_light.svg'),
+    dark: useBaseUrl('/img/docusaurus_dark.svg'),
   }}
 />;
 ```
@@ -139,7 +139,7 @@ import ThemedImage from '@theme/ThemedImage';
 <ThemedImage
   alt="Docusaurus themed image"
   sources={{
-    light: useBaseUrl('img/docusaurus_keytar.svg'),
-    dark: useBaseUrl('img/docusaurus_speed.svg'),
+    light: useBaseUrl('/img/docusaurus_keytar.svg'),
+    dark: useBaseUrl('/img/docusaurus_speed.svg'),
   }}
 />
diff --git a/website/docs/introduction.md b/website/docs/introduction.md
@@ -34,7 +34,7 @@ Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immedi
 
 ## A better Docusaurus is coming to town
 
-<img alt="Docusaurus " src={require('@docusaurus/useBaseUrl').default('img/slash-introducing.svg')} />
+![Docusaurus Slash Introduction](/img/slash-introducing.svg)
 
 Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).
 

diff --git a/website/docs/static-assets.md b/website/docs/static-assets.md
@@ -3,28 +3,40 @@ id: static-assets
 title: Static Assets
 ---
 
-In general, every website needs assets: images, stylesheets, favicons and etc. In such cases, you can create a directory named `static` at the root of your project. Every file you put into that directory will be copied into the the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it’ll be copied to `build/sun.jpg`.
+Every website needs assets: images, stylesheets, favicons etc. In such cases, you can create a directory named `static` at the root of your project.
 
-This means that if the site's `baseUrl` is `/`, an image in `/static/img/docusaurus_keytar.svg` is available at `/img/docusaurus_keytar.svg`.
+Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
+
+This means that:
+
+- for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`.
+- for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`.
 
 ## Referencing your static asset
 
-You can reference assets from the `static` folder in your code. You could use hardcoded absolute paths, i.e. starting with a slash /, but remember to include the `baseUrl` if it is not `/`. However, this will break if you change your `baseUrl` in the config.
+You can reference assets from the `static` folder in your code using absolute paths, but this is not ideal because changing the site `baseUrl` will **break those link**s.
 
-A better way would be to use the `useBaseUrl` utility function which appends the `baseUrl` to paths for you.
+You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
 
 ### JSX example
 
+```jsx title="MyComponent.js"
+import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
+
+<img src={DocusaurusImageUrl} />;
+```
+
+```jsx title="MyComponent.js"
+<img src={require('@site/static/img/docusaurus.png').default} />
+```
+
 ```jsx title="MyComponent.js"
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-<img
-  alt="Docusaurus with Keytar"
-  src={useBaseUrl('img/docusaurus_keytar.svg')}
-/>;
+<img src={useBaseUrl('/img/docusaurus.png')} />;
 ```
 
-You can also import SVG images, which will be transformed into React components.
+You can also import SVG files: they will be transformed into React components.
 
 ```jsx title="MyComponent.js"
 import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
@@ -34,7 +46,13 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
 
 ### Markdown example
 
-Thanks to MDX, you can also use `useBaseUrl` utility function in Markdown files! You'd have to use `<img>` tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
+Markdown links and images referencing assets of the static folder will be converted to `require("@site/static/assetName.png")"`, and **the site baseUrl will be automatically prepended** for you.
+
+```md title="my-doc.md"
+![Docusaurus](/img/docusaurus.png)
+```
+
+Thanks to MDX, you can also use `useBaseUrl` utility function in Markdown files! You'd have to use html tags like `<img>` instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
 
 ```jsx title="my-doc.mdx"
 ---
@@ -47,19 +65,13 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 ...
 
-<img alt="Docusaurus with Keytar" src={useBaseUrl('img/docusaurus_keytar.svg')} />
-```
-
-You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.
-
-```md title="my-doc.md"
-![Docusaurus with Keytar](/img/docusaurus_keytar.png)
+<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />
 ```
 
 ### Caveats
 
 Keep in mind that:
 
-- By default, none of the files in `static` folder will be post-processed or minified.
-- Missing files references via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
+- By default, none of the files in `static` folder will be post-processed, hashed or minified.
+- Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
 - By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting.
diff --git a/website/src/pages/index.js b/website/src/pages/index.js
@@ -90,7 +90,7 @@ function Home() {
               <img
                 alt={translate({message: 'Docusaurus with Keytar'})}
                 className={styles.heroLogo}
-                src={useBaseUrl('img/docusaurus_keytar.svg')}
+                src={useBaseUrl('/img/docusaurus_keytar.svg')}
               />
               <span
                 className={styles.heroTitleTextHtml}
@@ -106,9 +106,7 @@ function Home() {
               />
             </h1>
             <div className={styles.indexCtas}>
-              <Link
-                className={styles.indexCtasGetStartedButton}
-                to={useBaseUrl('docs/')}>
+              <Link className={styles.indexCtasGetStartedButton} to="/docs">
                 <Translate>Get Started</Translate>
               </Link>
               <Link
@@ -131,7 +129,7 @@ function Home() {
         <div className={clsx(styles.announcement, styles.announcementDark)}>
           <div className={styles.announcementInner}>
             <Translate>Coming from v1? Check out our</Translate>{' '}
-            <Link to={useBaseUrl('/docs/migration')}>
+            <Link to="/docs/migration">
               <Translate>v1 to v2 migration guide</Translate>
             </Link>
             .
@@ -144,7 +142,7 @@ function Home() {
                 <img
                   className={styles.featureImage}
                   alt="Powered by MDX"
-                  src={useBaseUrl('img/undraw_typewriter.svg')}
+                  src={useBaseUrl('/img/undraw_typewriter.svg')}
                 />
                 <h2 className={clsx(styles.featureHeading)}>
                   <Translate>Powered by Markdown</Translate>
@@ -163,7 +161,7 @@ function Home() {
                 <img
                   alt="Built Using React"
                   className={styles.featureImage}
-                  src={useBaseUrl('img/undraw_react.svg')}
+                  src={useBaseUrl('/img/undraw_react.svg')}
                 />
                 <h2 className={clsx(styles.featureHeading)}>
                   <Translate>Built Using React</Translate>
@@ -180,7 +178,7 @@ function Home() {
                 <img
                   alt="Ready for Translations"
                   className={styles.featureImage}
-                  src={useBaseUrl('img/undraw_around_the_world.svg')}
+                  src={useBaseUrl('/img/undraw_around_the_world.svg')}
                 />
                 <h2 className={clsx(styles.featureHeading)}>
                   <Translate>Ready for Translations</Translate>
@@ -200,7 +198,7 @@ function Home() {
                 <img
                   alt="Document Versioning"
                   className={styles.featureImage}
-                  src={useBaseUrl('img/undraw_version_control.svg')}
+                  src={useBaseUrl('/img/undraw_version_control.svg')}
                 />
                 <h2 className={clsx(styles.featureHeading)}>
                   <Translate>Document Versioning</Translate>
@@ -217,7 +215,7 @@ function Home() {
                 <img
                   alt="Document Search"
                   className={styles.featureImage}
-                  src={useBaseUrl('img/undraw_algolia.svg')}
+                  src={useBaseUrl('/img/undraw_algolia.svg')}
                 />
                 <h2 className={clsx(styles.featureHeading)}>
                   <Translate>Content Search</Translate>