diff --git a/project-words.txt b/project-words.txt index a163b0e864..23d43cc5fd 100644 --- a/project-words.txt +++ b/project-words.txt @@ -13,6 +13,7 @@ architecting astro atrule autogen +autogenerating backport backticks bartosz @@ -39,6 +40,7 @@ clsx codesandbox contravariance corejs +crawlable creativecommons csvg customizability @@ -47,6 +49,7 @@ datagit datas dedup deduplicated +dΓ©ja devto dmitry docgen @@ -259,6 +262,7 @@ unprefixed unswizzle unversioned upvotes +userland vannicatte vercel vetter diff --git a/website/_dogfooding/dogfooding.config.js b/website/_dogfooding/dogfooding.config.js index 25635f1a8f..0179dc3599 100644 --- a/website/_dogfooding/dogfooding.config.js +++ b/website/_dogfooding/dogfooding.config.js @@ -60,6 +60,7 @@ const dogfoodingPluginInstances = [ /** @type {import('@docusaurus/types').Plugin} */ function clientModuleTestPlugin() { return { + name: 'client-module-test-plugin', getClientModules() { return [ require.resolve('./clientModuleExample.ts'), diff --git a/website/docs/advanced/architecture.md b/website/docs/advanced/architecture.md new file mode 100644 index 0000000000..778b68eabd --- /dev/null +++ b/website/docs/advanced/architecture.md @@ -0,0 +1,28 @@ +--- +description: How Docusaurus works to build your app +--- + +# Architecture + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Zoom from '@site/src/components/Zoom'; +``` + + + +![Architecture overview](/img/architecture.png) + + + +This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle. + +Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments: + +- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d. +- The theme code is built with Webpack. They can be provided as ESMβ€”following React conventions. + +Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options). + +During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.md#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable. diff --git a/website/docs/advanced/index.md b/website/docs/advanced/index.md new file mode 100644 index 0000000000..afe7f1a570 --- /dev/null +++ b/website/docs/advanced/index.md @@ -0,0 +1,12 @@ +# Advanced Tutorials + +This section is not going to be very structured, but we will cover the following topics: + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` + +We will assume that you have finished the guides, and know the basics like how to configure plugins, how to write React components, etc. These sections will have plugin authors and code contributors in mind, so we may occasionally refer to [plugin APIs](../api/plugin-methods/README.md) or other architecture details. Don't panic if you don't understand everythingπŸ˜‰ diff --git a/website/docs/advanced/plugins.md b/website/docs/advanced/plugins.md new file mode 100644 index 0000000000..c309f4b536 --- /dev/null +++ b/website/docs/advanced/plugins.md @@ -0,0 +1,129 @@ +# Plugins + +Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets. + +## Creating plugins {#creating-plugins} + +A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). + +### Function definition {#function-definition} + +You can use a plugin as a function directly included in the Docusaurus config file: + +```js title="docusaurus.config.js" +module.exports = { + // ... + plugins: [ + // highlight-start + async function myPlugin(context, options) { + // ... + return { + name: 'my-plugin', + async loadContent() { + // ... + }, + async contentLoaded({content, actions}) { + // ... + }, + /* other lifecycle API */ + }; + }, + // highlight-end + ], +}; +``` + +### Module definition {#module-definition} + +You can use a plugin as a module path referencing a separate file or NPM package: + +```js title="docusaurus.config.js" +module.exports = { + // ... + plugins: [ + // without options: + './my-plugin', + // or with options: + ['./my-plugin', options], + ], +}; +``` + +Then in the folder `my-plugin`, you can create an `index.js` such as this: + +```js title="my-plugin.js" +module.exports = async function myPlugin(context, options) { + // ... + return { + name: 'my-plugin', + async loadContent() { + /* ... */ + }, + async contentLoaded({content, actions}) { + /* ... */ + }, + /* other lifecycle API */ + }; +}; +``` + +--- + +You can view all plugins installed in your site using the [debug plugin's metadata panel](/__docusaurus/debug/metadata). + +Plugins come as several types: + +- `package`: an external package you installed +- `project`: a plugin you created in your project, given to Docusaurus as a local file path +- `local`: a plugin created using the function definition +- `synthetic`: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail. + +You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`. + +## Plugin design + +Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page. + +### Theme design + +When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`... + +**Themes provide the set of UI components to render the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy. + +For example, a Docusaurus blog may consist of a blog plugin and a blog theme. + +:::note + +This is a contrived example: in practice, `@docusaurus/theme-classic` provides the theme for docs, blog, and layouts. + +::: + +```js title="docusaurus.config.js" +module.exports = { + // highlight-next-line + themes: ['theme-blog'], + plugins: ['plugin-content-blog'], +}; +``` + +And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme): + +```js title="docusaurus.config.js" +module.exports = { + // highlight-next-line + themes: ['theme-blog-bootstrap'], + plugins: ['plugin-content-blog'], +}; +``` + +Now, although the theme receives the same data from the plugin, how the theme chooses to _render_ the data as UI can be drastically different. + +While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives. + +Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use [`loadContent`](../api/plugin-methods/lifecycle-apis.md#loadContent), since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an `src/theme` directory full of components, which are made known to the core through the [`getThemePath`](../api/plugin-methods/extend-infrastructure.md#getThemePath) lifecycle. + +To summarize: + +- Themes share the same lifecycle methods with Plugins +- Themes are run after all existing Plugins +- Themes add component aliases by providing `getThemePath`. diff --git a/website/docs/advanced/routing.md b/website/docs/advanced/routing.md new file mode 100644 index 0000000000..09bc837490 --- /dev/null +++ b/website/docs/advanced/routing.md @@ -0,0 +1,277 @@ +--- +description: "Docusaurus' routing system follows single-page application conventions: one route, one component." +--- + +# Routing + +```mdx-code-block +import Link from '@docusaurus/Link'; +import {useLatestVersion, useActiveDocContext} from '@docusaurus/plugin-content-docs/client'; +import {useLocation} from '@docusaurus/router'; +import BrowserWindow from '@site/src/components/BrowserWindow'; +``` + +Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system. + +## Routing in content plugins + +Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this: + +![plugin routes model](/img/routes.png#gh-light-mode-only)![plugin routes model](/img/routes-dark.png#gh-dark-mode-only) + +Any route will be matched against this nested route config until a good match is found. For example, when given a route `/docs/configuration`, Docusaurus first enters the `/docs` branch, and then searches among the subroutes created by the docs plugin. + +Changing `routeBasePath` can effectively alter your site's route structure. For example, in [Docs-only mode](../guides/docs/docs-introduction.md#docs-only-mode), we mentioned that configuring `routeBasePath: '/'` for docs means that all routes that the docs plugin create would not have the `/docs` prefix, yet it doesn't prevent you from having more subroutes like `/blog` created by other plugins. + +Next, let's look at how the three plugins structure their own "boxes of subroutes". + +### Pages routing + +Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information. + +The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component. + +### Blog routing + +The blog creates the following routes: + +- **Posts list pages**: `/`, `/page/2`, `/page/3`... + - The component is `@theme/BlogListPage`. +- **Post pages**: `/2021/11/21/algolia-docsearch-migration`, `/2021/05/12/announcing-docusaurus-two-beta`... + - Generated from each Markdown post. + - The routes are fully customizable through the `slug` front matter. + - The component is `@theme/BlogPostPage`. +- **Tags list page**: `/tags` + - The route is customizable through the `tagsBasePath` option. + - The component is `@theme/BlogTagsListPage`. +- **Tag pages**: `/tags/adoption`, `/tags/beta`... + - Generated through the tags defined in each post's front matter. + - The routes always have base defined in `tagsBasePath`, but the subroutes are customizable through the tag's `permalink` field. + - The component is `@theme/BlogTagsPostsPage`. +- **Archive page**: `/archive` + - The route is customizable through the `archiveBasePath` option. + - The component is `@theme/BlogArchivePage`. + +### Docs routing + +The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`. + +```mdx-code-block +export const URLPath = () => {useLocation().pathname}; + +export const FilePath = () => { + const currentVersion = useActiveDocContext('default').activeVersion.name; + return {currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md; +} +``` + +The individual docs are rendered in the remaining space after the navbar, footer, sidebar, etc. have all been provided by the `DocPage` component. For example, this page, , is generated from the file at . The component used is `@theme/DocItem`. + +The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`. + +### File paths and URL paths + +Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure. + +When writing links in Markdown, you could either mean a _file path_, or a _URL path_, which Docusaurus would use several heuristics to determine. + +- If the path doesn't have an extension, it is a URL path. For example, a link `[page](../plugins)` on a page with URL `/docs/advanced/routing` will link to `/docs/plugins`. Docusaurus will only detect broken links when building your site (when it knows the full route structure), but will make no assumptions about the existence of a file. It is exactly equivalent to writing `page` in a JSX file. +- If the path has an `.md(x)` extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path. +- If the path has any other extension, Docusaurus would treat it as [an asset](../guides/markdown-features/markdown-features-assets.mdx) and bundle it. + +The following directory structure may help you visualize this file -> URL mapping. Assume that there's no slug customization in any page. + +
+ +A sample site structure + +```bash +. +β”œβ”€β”€ blog # blog plugin has routeBasePath: '/blog' +β”‚ β”œβ”€β”€ 2019-05-28-first-blog-post.md # -> /blog/2019/05/28/first-blog-post +β”‚ β”œβ”€β”€ 2019-05-29-long-blog-post.md # -> /blog/2019/05/29/long-blog-post +β”‚ β”œβ”€β”€ 2021-08-01-mdx-blog-post.mdx # -> /blog/2021/08/01/mdx-blog-post +β”‚ └── 2021-08-26-welcome +β”‚ β”œβ”€β”€ docusaurus-plushie-banner.jpeg +β”‚ └── index.md # -> /blog/2021/08/26/welcome +β”œβ”€β”€ docs # docs plugin has routeBasePath: '/docs'; current version has base path '/' +β”‚ β”œβ”€β”€ intro.md # -> /docs/intro +β”‚ β”œβ”€β”€ tutorial-basics +β”‚ β”‚ β”œβ”€β”€ _category_.json +β”‚ β”‚ β”œβ”€β”€ congratulations.md # -> /docs/tutorial-basics/congratulations +β”‚ β”‚ └── markdown-features.mdx # -> /docs/tutorial-basics/congratulations +β”‚ └── tutorial-extras +β”‚ β”œβ”€β”€ _category_.json +β”‚ β”œβ”€β”€ manage-docs-versions.md # -> /docs/tutorial-extras/manage-docs-versions +β”‚ └── translate-your-site.md # -> /docs/tutorial-extras/translate-your-site +β”œβ”€β”€ src +β”‚ └── pages # pages plugin has routeBasePath: '/' +β”‚ β”œβ”€β”€ index.module.css +β”‚ β”œβ”€β”€ index.tsx # -> / +β”‚ └── markdown-page.md # -> /markdown-page +└── versioned_docs + └── version-1.0.0 # version has base path '/1.0.0' + β”œβ”€β”€ intro.md # -> /docs/1.0.0/intro + β”œβ”€β”€ tutorial-basics + β”‚ β”œβ”€β”€ _category_.json + β”‚ β”œβ”€β”€ congratulations.md # -> /docs/1.0.0/tutorial-basics/congratulations + β”‚ └── markdown-features.mdx # -> /docs/1.0.0/tutorial-basics/congratulations + └── tutorial-extras + β”œβ”€β”€ _category_.json + β”œβ”€β”€ manage-docs-versions.md # -> /docs/1.0.0/tutorial-extras/manage-docs-versions + └── translate-your-site.md # -> /docs/1.0.0/tutorial-extras/translate-your-site +``` + +
+ +So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general. + +## Routes become HTML files + +Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that. + +The `/docs/advanced/routing` route can correspond to either `/docs/advanced/routing/index.html` or `/docs/advanced/routing.html`. Some hosting providers differentiate between them using the presence of a trailing slash, and may or may not tolerate the other. Read more in the [trailing slash guide](https://github.com/slorber/trailing-slash-guide). + +For example, the build output of the directory above is (ignoring other assets and JS bundle): + +
+ +Output of the above workspace + +```bash +build +β”œβ”€β”€ 404.html # /404/ +β”œβ”€β”€ blog +β”‚ β”œβ”€β”€ archive +β”‚ β”‚ └── index.html # /blog/archive/ +β”‚ β”œβ”€β”€ first-blog-post +β”‚ β”‚ └── index.html # /blog/first-blog-post/ +β”‚ β”œβ”€β”€ index.html # /blog/ +β”‚ β”œβ”€β”€ long-blog-post +β”‚ β”‚ └── index.html # /blog/long-blog-post/ +β”‚ β”œβ”€β”€ mdx-blog-post +β”‚ β”‚ └── index.html # /blog/mdx-blog-post/ +β”‚ β”œβ”€β”€ tags +β”‚ β”‚ β”œβ”€β”€ docusaurus +β”‚ β”‚ β”‚ └── index.html # /blog/tags/docusaurus/ +β”‚ β”‚ β”œβ”€β”€ hola +β”‚ β”‚ β”‚ └── index.html # /blog/tags/hola/ +β”‚ β”‚ └── index.html # /blog/tags/ +β”‚ └── welcome +β”‚ └── index.html # /blog/welcome/ +β”œβ”€β”€ docs +β”‚ β”œβ”€β”€ 1.0.0 +β”‚ β”‚ β”œβ”€β”€ intro +β”‚ β”‚ β”‚ └── index.html # /docs/1.0.0/intro/ +β”‚ β”‚ β”œβ”€β”€ tutorial-basics +β”‚ β”‚ β”‚ β”œβ”€β”€ congratulations +β”‚ β”‚ β”‚ β”‚ └── index.html # /docs/1.0.0/tutorial-basics/congratulations/ +β”‚ β”‚ β”‚ └── markdown-features +β”‚ β”‚ β”‚ └── index.html # /docs/1.0.0/tutorial-basics/markdown-features/ +β”‚ β”‚ └── tutorial-extras +β”‚ β”‚ β”œβ”€β”€ manage-docs-versions +β”‚ β”‚ β”‚ └── index.html # /docs/1.0.0/tutorial-extras/manage-docs-versions/ +β”‚ β”‚ └── translate-your-site +β”‚ β”‚ └── index.html # /docs/1.0.0/tutorial-extras/translate-your-site/ +β”‚ β”œβ”€β”€ intro +β”‚ β”‚ └── index.html # /docs/1.0.0/intro/ +β”‚ β”œβ”€β”€ tutorial-basics +β”‚ β”‚ β”œβ”€β”€ congratulations +β”‚ β”‚ β”‚ └── index.html # /docs/tutorial-basics/congratulations/ +β”‚ β”‚ └── markdown-features +β”‚ β”‚ └── index.html # /docs/tutorial-basics/markdown-features/ +β”‚ └── tutorial-extras +β”‚ β”œβ”€β”€ manage-docs-versions +β”‚ β”‚ └── index.html # /docs/tutorial-extras/manage-docs-versions/ +β”‚ └── translate-your-site +β”‚ └── index.html # /docs/tutorial-extras/translate-your-site/ +β”œβ”€β”€ index.html # / +└── markdown-page + └── index.html # /markdown-page/ +``` + +
+ +If `trailingSlash` is set to `false`, the build would emit `intro.html` instead of `intro/index.html`. + +All HTML files will reference its JS assets using absolute URLs, so in order for the correct assets to be located, you have to configure the `baseUrl` field. Note that `baseUrl` doesn't affect the emitted bundle's file structure: the base URL is one level above the Docusaurus routing system. You can see the aggregate of `url` and `baseUrl` as the actual location of your Docusaurus site. + +For example, the emitted HTML would contain links like ``. Because absolute URLs are resolved from the host, if the bundle placed under the path `https://example.com/base/`, the link will point to `https://example.com/assets/js/runtime~main.7ed5108a.js`, which is, well, non-existent. By specifying `/base/` as base URL, the link will correctly point to `/base/assets/js/runtime~main.7ed5108a.js`. + +Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`. + +## Generating and accessing routes + +The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files. + +All routes are aggregated in `.docusaurus/routes.js`, which you can view with the debug plugin's [routes panel](/__docusaurus/debug/routes). + +On the client side, we offer `@docusaurus/router` to access the page's route. `@docusaurus/router` is a re-export of the [`react-router-dom`](https://www.npmjs.com/package/react-router-dom/v/5.3.0) package. For example, you can use `useLocation` to get the current page's [location](https://developer.mozilla.org/en-US/docs/Web/API/Location), and `useHistory` to access the [history object](https://developer.mozilla.org/en-US/docs/Web/API/History). (They are not the same as the browser API, although similar in functionality. Refer to the React Router documentation for specific APIs.) + +This API is **SSR safe**, as opposed to the browser-only `window.location`. + +```jsx title="myComponent.js" +import React from 'react'; +import {useLocation} from '@docusaurus/router'; + +export function PageRoute() { + // React router provides the current component's route, even in SSR + const location = useLocation(); + return ( + + We are currently on {location.pathname} + + ); +} +``` + +```mdx-code-block +export function PageRoute() { + const location = useLocation(); + return ( + + We are currently on {location.pathname} + + ); +} + + + + + + +``` + +## Escaping from SPA redirects + +Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead. + +If you put some HTML pages under the `static` folder, they will be copied to the build output and therefore become accessible as part of your website, yet it's not part of the Docusaurus route system. We provide a `pathname://` protocol that allows you to redirect to another part of your domain in a non-SPA fashion, as if this route is an external link. Try the following two links: + +```md +- [/pure-html](/pure-html) +- [pathname:///pure-html](pathname:///pure-html) +``` + + + +- /pure-html +- [pathname:///pure-html](pathname:///pure-html) + + + +:::tip + +The first link will trigger a "broken links detected" check during the production build. + +::: + +The `pathname://` protocol is useful for referencing any content in the static folder. For example, Docusaurus would convert [all Markdown static assets to require() calls](../guides/markdown-features/markdown-features-assets.mdx#static-assets). You can use `pathname://` to keep it a regular link instead of being hashed by Webpack. + +```md title="my-doc.md" +![An image from the static](pathname:///img/docusaurus.png) + +[An asset from the static](pathname:///files/asset.pdf) +``` + +Docusaurus will only strip the `pathname://` prefix without processing the content. diff --git a/website/docs/advanced/ssg.md b/website/docs/advanced/ssg.md new file mode 100644 index 0000000000..6c478e67e5 --- /dev/null +++ b/website/docs/advanced/ssg.md @@ -0,0 +1,206 @@ +--- +sidebar_label: Static site generation +description: Docusaurus statically renders your React code into HTML, allowing faster load speed and better SEO. +--- + +# Static site generation (SSG) + +In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice: + +- During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages. +- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript. + +:::info SSR or SSG? + +_Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably. + +::: + +Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either. + +```jsx +import React from 'react'; + +export default function WhereAmI() { + return {window.location.href}; +} +``` + +This looks like idiomatic React, but if you run `docusaurus build`, you will get an error: + +``` +ReferenceError: window is not defined +``` + +This is because during server-side rendering, the Docusaurus app isn't actually run in browser, and it doesn't know what `window` is. + +
+ +What about process.env.NODE_ENV? + +One exception to the "no Node globals" rule is `process.env.NODE_ENV`. In fact, you can use it in React, because Webpack injects this variable as a global: + +```jsx +import React from 'react'; + +export default function expensiveComp() { + if (process.env.NODE_ENV === 'development') { + return <>This component is not shown in development; + } + const res = someExpensiveOperationThatLastsALongTime(); + return <>{res}; +} +``` + +During Webpack build, the `process.env.NODE_ENV` will be replaced with the value, either `'development'` or `'production'`. You will then get different build results after dead code elimination: + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + + + + +```diff +import React from 'react'; + +export default function expensiveComp() { + // highlight-next-line + if ('development' === 'development') { ++ return <>This component is not shown in development; + } +- const res = someExpensiveOperationThatLastsALongTime(); +- return <>{res}; +} +``` + + + + +```diff +import React from 'react'; + +export default function expensiveComp() { + // highlight-next-line +- if ('production' === 'development') { +- return <>This component is not shown in development; +- } ++ const res = someExpensiveOperationThatLastsALongTime(); ++ return <>{res}; +} +``` + + + +
+ +## Understanding SSR + +React is not just a dynamic UI runtimeβ€”it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs. + +These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your siteβ€”anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading. + +In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app. + +## Escape hatches + +If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example: + +- Our [live codeblock](../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor), which runs in the browser's JS runtime +- Our [themed image](../guides/markdown-features/markdown-features-assets.mdx#themed-images) that detects the user's color scheme to display different images +- The JSON viewer of our debug panel which uses the `window` global for styling + +You may need to escape from SSR since static HTML can't display anything useful without knowing the client state. + +:::caution + +It is important for the first client-side render to produce the exact same DOM structure as server-side rendering, otherwise, React will correlate virtual DOM with the wrong DOM elements. + +Therefore, the naΓ―ve attempt of `if (typeof window !== 'undefined) {/* render something */}` won't work appropriately as a browser vs. server detection, because the first client render would instantly render different markup from the server-generated one. + +You can read more about this pitfall in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). + +::: + +We provide several more reliable ways to escape SSR. + +### `` + +If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [``](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR. + +```jsx +import BrowserOnly from '@docusaurus/BrowserOnly'; + +function MyComponent(props) { + return ( + // highlight-start + Loading...}> + {() => { + const LibComponent = + require('some-lib-that-accesses-window').LibComponent; + return ; + }} + + // highlight-end + ); +} +``` + +It's important to realize that the children of `` is not a JSX element, but a function that _returns_ an element. This is a design decision. Consider this code: + +```jsx +import BrowserOnly from '@docusaurus/BrowserOnly'; + +function MyComponent() { + return ( + + {/* highlight-start */} + {/* DON'T DO THIS - doesn't actually work */} + page url = {window.location.href} + {/* highlight-end */} + + ); +} +``` + +While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed. + +### `useIsBrowser` + +You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI. + +```jsx +import useIsBrowser from '@docusaurus/useIsBrowser'; + +function MyComponent() { + const isBrowser = useIsBrowser(); + const location = isBrowser ? window.location.href : 'fetching location...'; + return {location}; +} +``` + +### `useEffect` + +Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state. + +```jsx +function MyComponent() { + useEffect(() => { + // Only logged in the browser console; nothing is logged during server-side rendering + console.log("I'm now in the browser"); + }, []); + return Some content...; +} +``` + +### `ExecutionEnvironment` + +The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment. + +Beware that it essentially checked `typeof window !== 'undefined'` under the hood, so you should not use it for rendering-related logic, but only imperative code, like reacting to user input by sending web requests, or dynamically importing libraries, where DOM isn't updated at all. + +```js title="a-client-module.js" +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; + +if (ExecutionEnvironment.canUseDOM) { + document.title = "I'm loaded!"; +} +``` diff --git a/website/docs/advanced/swizzling.md b/website/docs/advanced/swizzling.md new file mode 100644 index 0000000000..4163bb6e63 --- /dev/null +++ b/website/docs/advanced/swizzling.md @@ -0,0 +1,195 @@ +--- +description: Customize your site's appearance through creating your own theme components +--- + +# Swizzling + +In this section, we will introduce how customization of layout is done in Docusaurus. + +> DΓ©ja vu...? + +This section is similar to [Styling and Layout](../styling-layout.md), but this time, we are going to write more code and go deeper into the internals instead of playing with stylesheets. We will talk about a central concept in Docusaurus customization: **swizzling**, from how to swizzle, to how it works under the hood. + +We know you are busy, so we will start with the "how" before going into the "why". + +## Swizzling + +```mdx-code-block +import SwizzleWarning from "../_partials/swizzleWarning.mdx" + + +``` + +Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, method swizzling is the process of changing the implementation of an existing selector (method). **In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** (To gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`. + +### Ejecting theme components + +To eject a component provided by the theme, run the following command in your doc site: + +```bash npm2yarn +npm run swizzle [theme name] [component name] +``` + +As an example, to swizzle the `