From e807bff6669037652e741b046f4b81632d31ddd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Tue, 2 Feb 2021 18:26:51 +0100 Subject: [PATCH] docs(v2): improve bad static assets doc + remove some useless useBaseUrl usage (#4158) --- .../markdown-features-assets.mdx | 8 +-- website/docs/introduction.md | 2 +- website/docs/static-assets.md | 50 ++++++++++++------- website/src/pages/index.js | 18 +++---- 4 files changed, 44 insertions(+), 34 deletions(-) diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx index 142f4fe3a0e5..baa1c1ea2721 100644 --- 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'; ; ``` @@ -139,7 +139,7 @@ import ThemedImage from '@theme/ThemedImage'; diff --git a/website/docs/introduction.md b/website/docs/introduction.md index baae3ba263b5..02c983b68166 100644 --- 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 -Docusaurus +![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 index c3db7c43bb45..fb1d686c268d 100644 --- 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'; + +; +``` + +```jsx title="MyComponent.js" + +``` + ```jsx title="MyComponent.js" import useBaseUrl from '@docusaurus/useBaseUrl'; -Docusaurus with Keytar; +; ``` -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 `` 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 `` 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'; ... -Docusaurus with Keytar -``` - -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) +Docusaurus with Keytar ``` ### 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 index 5cf265a77570..e7b72a25be5a 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -90,7 +90,7 @@ function Home() { {translate({message:
- + Get Started
Coming from v1? Check out our{' '} - + v1 to v2 migration guide . @@ -144,7 +142,7 @@ function Home() { Powered by MDX

Powered by Markdown @@ -163,7 +161,7 @@ function Home() { Built Using React

Built Using React @@ -180,7 +178,7 @@ function Home() { Ready for Translations

Ready for Translations @@ -200,7 +198,7 @@ function Home() { Document Versioning

Document Versioning @@ -217,7 +215,7 @@ function Home() { Document Search

Content Search