-
-
-#### Category index convention {#category-index-convention}
-
-Docusaurus can automatically link a category to its index document.
-
-A category index document is a document following one of those filename conventions:
-
-- Named as `index` (case-insensitive): `docs/Guides/index.md`
-- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
-- Same name as parent folder: `docs/Guides/Guides.md`
-
-This is equivalent to using a category with a [doc link](#category-doc-link):
-
-```js title="sidebars.js"
-module.exports = {
- docs: [
- // highlight-start
- {
- type: 'category',
- label: 'Guides',
- link: {type: 'doc', id: 'Guides/index'},
- items: [],
- },
- // highlight-end
- ],
-};
-```
-
-:::tip
-
-Naming your introductory document `README.md` makes it show up when browsing the folder using the GitHub interface, while using `index.md` makes the behavior more in line with how HTML files are served.
-
-:::
-
-#### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
-
-For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
-
-**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter.
-
-```yaml title="docs/tutorials/tutorial-easy.md"
----
-# highlight-start
-sidebar_position: 2
-sidebar_label: Easy
-sidebar_class_name: green
-# highlight-end
----
-# Easy Tutorial
-
-This is the easy tutorial!
-```
-
-**For categories**: add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata.
-
-A real world example
-Consider this file structure: - -```bash -docs -βββ api -β βββ product1-api -β β βββ api.md -β βββ product2-api -β βββ basic-api.md -β βββ pro-api.md -βββ intro.md -βββ tutorials - βββ advanced - β βββ advanced1.md - β βββ advanced2.md - β βββ read-more - β βββ resource1.md - β βββ resource2.md - βββ easy - β βββ easy1.md - β βββ easy2.md - βββ tutorial-end.md - βββ tutorial-intro.md - βββ tutorial-medium.md -``` - -And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - 'intro', - { - type: 'category', - label: 'Tutorials', - items: [ - 'tutorial-intro', - // highlight-start - { - type: 'autogenerated', - dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy - }, - // highlight-end - 'tutorial-medium', - // highlight-start - { - type: 'autogenerated', - dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard - }, - // highlight-end - 'tutorial-end', - ], - }, - // highlight-start - { - type: 'autogenerated', - dirName: 'api', // Generate sidebar slice from docs/api - }, - // highlight-end - { - type: 'category', - label: 'Community', - items: ['team', 'chat'], - }, - ], -}; -``` - -It would be resolved as: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - 'intro', - { - type: 'category', - label: 'Tutorials', - items: [ - 'tutorial-intro', - // highlight-start - // Two files in docs/tutorials/easy - 'easy1', - 'easy2', - // highlight-end - 'tutorial-medium', - // highlight-start - // Two files and a folder in docs/tutorials/hard - 'advanced1', - 'advanced2', - { - type: 'category', - label: 'read-more', - items: ['resource1', 'resource2'], - }, - // highlight-end - 'tutorial-end', - ], - }, - // highlight-start - // Two folders in docs/api - { - type: 'category', - label: 'product1-api', - items: ['api'], - }, - { - type: 'category', - label: 'product2-api', - items: ['basic-api', 'pro-api'], - }, - // highlight-end - { - type: 'category', - label: 'Community', - items: ['team', 'chat'], - }, - ], -}; -``` - -Note how the autogenerate source directories themselves don't become categories: only the items they contain do. This is what we mean by "sidebar slice". - -- -You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. - -:::caution - -Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx). - -::: - -## Importing code snippets {#importing-code-snippets} - -You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, first you need to install it in your project: - -```bash npm2yarn -npm install --save raw-loader -``` - -Now you can import code snippets from another file as it is: - - -```jsx title="myMarkdownFile.mdx" -import CodeBlock from '@theme/CodeBlock'; -import MyComponentSource from '!!raw-loader!./myComponent'; - -
-``` - -You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock: - -```jsx -
-``` - -This way, you can reuse contents among multiple pages and avoid duplicating materials. - -:::caution - -The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)). - -::: - -## Available exports - -Within the MDX page, the following variables are available as globals: - -- `frontMatter`: the front matter as a record of string keys and values; -- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case. -- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter). - -```jsx -import TOCInline from '@theme/TOCInline'; -import CodeBlock from '@theme/CodeBlock'; - -The table of contents for this page, serialized: - -
-
- {Object.entries(frontMatter).map(([key, value]) =>
- {key}: {value} )} -
The title of this page is: {contentTitle}
-``` - -```mdx-code-block -import TOCInline from '@theme/TOCInline'; - --
- {Object.entries(frontMatter).map(([key, value]) =>
- {key}: {value} )} -
The title of this page is: {contentTitle}
- -
- {/* highlight-start */}
- Welcome to my website
- {/* highlight-end */}
-
- 
` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
-
-You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
-
-:::info
-
-In Markdown, things are different: you can stick to use absolute paths because Docusaurus actually handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
-
-:::
-
-### Examples {#examples}
-
-```jsx title="MyComponent.js"
-import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
-
-.default})
-```
-
-```jsx title="MyComponent.js"
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
-})
;
-```
-
-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';
-
-Before footer
-
-
-
-
-## Wrapping your site with `How are theme aliases resolved?
- -It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup where three themes/plugins and the site itself all try to define the same component. Internally, Docusaurus loads these themes as a "stack". - -```text -+-------------------------------------------------+ -| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top -+-------------------------------------------------+ -| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component -+-------------------------------------------------+ -| `plugin-awesome-codeblock/theme/CodeBlock.js` | -+-------------------------------------------------+ -| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom -+-------------------------------------------------+ -``` - -The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last. - -`@theme/*` always points to the topmost componentβwhen code block is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version. - -`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled componentβit points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import. - -`@theme-init/*` always points to the bottommost componentβusually this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at allβDocusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases! - -{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,
+
+
+
+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 {#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):
+
+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 +``` + +
+
+
+
+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 {#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 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/ +``` + +{location.pathname}
+
+ );
+}
+```
+
+```mdx-code-block
+export function PageRoute() {
+ const location = useLocation();
+ return (
+
+ We are currently on {location.pathname}
+
+ );
+}
+
+
+
+What about
+
+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 {#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 {#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.
+
+### `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';
+
+
+
+
## Required fields {#required-fields}
### `title` {#title}
@@ -41,7 +76,7 @@ module.exports = {
- Type: `string`
-Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
+Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
```js title="docusaurus.config.js"
module.exports = {
@@ -55,9 +90,7 @@ module.exports = {
- Type: `string | undefined`
-Path to your site favicon
-
-Example, if your favicon is in `static/img/favicon.ico`:
+Path to your site favicon. For example, if your favicon is in `static/img/favicon.ico`:
```js title="docusaurus.config.js"
module.exports = {
@@ -77,7 +110,7 @@ Allow to customize the presence/absence of a trailing slash at the end of URLs/l
:::tip
-Each static hosting provider serve static files differently (this behavior may even change over time).
+Each static hosting provider serves static files differently (this behavior may even change over time).
Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting.
@@ -100,10 +133,12 @@ module.exports = {
en: {
label: 'English',
direction: 'ltr',
+ htmlLang: 'en-US',
},
fr: {
label: 'Français',
direction: 'ltr',
+ htmlLang: 'fr-FR',
},
},
},
@@ -112,6 +147,7 @@ module.exports = {
- `label`: the label to use for this locale
- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Arabic, Hebrew, etc.)
+- `htmlLang`: BCP 47 language tag to use in `` and in ``
### `noIndex` {#noindex}
@@ -243,6 +279,7 @@ Example:
module.exports = {
themeConfig: {
hideableSidebar: false,
+ autoCollapseSidebarCategories: false,
colorMode: {
defaultMode: 'light',
disableSwitch: false,
@@ -306,33 +343,45 @@ module.exports = {
### `plugins` {#plugins}
-
+- Type: `PluginConfig[]`
-- Type: `any[]`
+```ts
+type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
+```
+
+See [plugin method references](./plugin-methods/README.md) for the shape of a `PluginModule`.
```js title="docusaurus.config.js"
module.exports = {
- plugins: [],
+ plugins: [
+ 'docusaurus-plugin-awesome',
+ ['docusuarus-plugin-confetti', {fancy: false}],
+ () => ({
+ postBuild() {
+ console.log('Build finished');
+ },
+ }),
+ ],
};
```
### `themes` {#themes}
-
-
-- Type: `any[]`
+- Type: `PluginConfig[]`
```js title="docusaurus.config.js"
module.exports = {
- themes: [],
+ themes: ['@docusaurus/theme-classic'],
};
```
### `presets` {#presets}
-
+- Type: `PresetConfig[]`
-- Type: `any[]`
+```ts
+type PresetConfig = string | [string, any];
+```
```js title="docusaurus.config.js"
module.exports = {
@@ -355,7 +404,7 @@ module.exports = {
};
```
-Attempting to add unknown field in the config will lead to error in build time:
+Attempting to add unknown fields in the config will lead to errors during build time:
```bash
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
@@ -513,7 +562,7 @@ module.exports = {
:::caution
-This banner need to inline CSS / JS.
+This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL.
If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it.
diff --git a/website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/README.md b/website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/README.md
similarity index 91%
rename from website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/README.md
rename to website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/README.md
index 5b046d9a74..0e9d816c6f 100644
--- a/website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/README.md
+++ b/website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/README.md
@@ -8,16 +8,16 @@ This section is a work in progress. Anchor links or even URLs are not guaranteed
Plugin APIs are shared by themes and pluginsβthemes are loaded just like plugins.
-## Plugin module
+## Plugin module {#plugin-module}
Every plugin is imported as a module. The module is expected to have the following members:
- A **default export**: the constructor function for the plugin.
- **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized.
-## Plugin constructor
+## Plugin constructor {#plugin-constructor}
-The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin`.
+The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | PromiseConfig files also support config creator functions and async code.
+ +```js title="docusaurus.config.js" +module.exports = function configCreator() { + return { + // site config... + }; +}; +``` + +```js title="docusaurus.config.js" +module.exports = async function configCreatorAsync() { + return { + // site config... + }; +}; +``` + +```js title="docusaurus.config.js" +module.exports = Promise.resolve({ + // site config... +}); +``` + +string \| null | `'/archive'` | URL route for the archive blog section of your site. It is prepended to the `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to disable generation of archive. |
| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
| `postsPerPage` | number \| 'ALL' | `10` | Number of posts to show per page in the listing page. Use `'ALL'` to display all posts on one listing page. |
@@ -48,6 +54,7 @@ Accepted fields:
| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. |
| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page |
| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. |
+| `blogArchiveComponent` | `string` | `'@theme/BlogArchivePage'` | Root component of the blog archive page. |
| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
@@ -66,7 +73,7 @@ Accepted fields:
-```typescript
+```ts
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
@@ -94,27 +101,27 @@ type ReadingTimeFunctionOption = (params: {
type FeedType = 'rss' | 'atom' | 'json';
```
-## Example configuration {#ex-config}
+### Example configuration {#ex-config}
-Here's an example configuration object.
-
-You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
+You can configure this plugin through preset options or plugin options.
:::tip
-Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
+Most Docusaurus users configure this plugin through the preset options.
:::
-```js
+```js config-tabs
+// Preset Options: blog
+// Plugin Options: @docusaurus/plugin-content-blog
+
const config = {
path: 'blog',
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Advanced use-case: functional editUrl
- editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
- return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
- },
+ editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
+ `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
editLocalizedFiles: false,
blogTitle: 'Blog title',
blogDescription: 'Blog',
@@ -149,51 +156,9 @@ const config = {
};
```
-### Preset options {#ex-config-preset}
+## Markdown front matter {#markdown-front-matter}
-If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
-
-```js title="docusaurus.config.js"
-module.exports = {
- presets: [
- [
- '@docusaurus/preset-classic',
- {
- // highlight-start
- blog: {
- path: 'blog',
- // ... configuration object here
- },
- // highlight-end
- },
- ],
- ],
-};
-```
-
-### Plugin options {#ex-config-plugin}
-
-If you are using a standalone plugin, provide options directly to the plugin:
-
-```js title="docusaurus.config.js"
-module.exports = {
- plugins: [
- [
- '@docusaurus/plugin-content-blog',
- // highlight-start
- {
- path: 'blog',
- // ... configuration object here
- },
- // highlight-end
- ],
- ],
-};
-```
-
-## Markdown Frontmatter {#markdown-frontmatter}
-
-Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
+Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.
Accepted fields:
@@ -201,7 +166,7 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
-| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. |
+| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` front matter fields, even for single author blog posts. |
| `author` | `string` | `undefined` | β οΈ Prefer using `authors`. The blog post author's name. |
| `author_url` | `string` | `undefined` | β οΈ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
| `author_image_url` | `string` | `undefined` | β οΈ Prefer using `authors`. The URL to the author's thumbnail image. |
@@ -220,7 +185,7 @@ Accepted fields:
-```typescript
+```ts
type Tag = string | {label: string; permalink: string};
// An author key references an author from the global plugin authors.yml file
@@ -234,13 +199,13 @@ type Author = {
image_url?: string;
};
-// The FrontMatter authors field allows various possible shapes
+// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];
```
Example:
-```yml
+```md
---
title: Welcome Docusaurus v2
authors:
@@ -255,6 +220,7 @@ description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
+
A Markdown blog post
```
diff --git a/website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-docs.md
similarity index 82%
rename from website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-docs.md
rename to website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-docs.md
index 47c241b821..2c97cd4ab7 100644
--- a/website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-docs.md
+++ b/website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-docs.md
@@ -19,7 +19,7 @@ npm install --save @docusaurus/plugin-content-docs
If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
-You can configure this plugin through the [preset options](#ex-config-preset).
+You can configure this plugin through the preset options.
:::
@@ -32,6 +32,7 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. |
+| `breadcrumbs` | `boolean` | `true` | To enable or disable the breadcrumbs on docs pages. |
| `editUrl` | string \| EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
| `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. |
@@ -55,15 +56,15 @@ Accepted fields:
| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. |
| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. |
-| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). |
-| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory). Tip: turn it off if the current version is a work-in-progress, not ready to be published. | -| `lastVersion` | `string` | `current` (alias for the first version to appear in `versions.json` and at the "root" (docs have `path=/docs/myDoc`)) | Set the version navigated to in priority on versioned sites and the one displayed by default in docs navbar items.
Note: the path and label of the last version are configurable.
Tip: `lastVersion: 'current'` makes sense in many cases. | +| `disableVersioning` | `boolean` | `false` | Explicitly disable versioning even with versions. This will make the site only include the current version. | +| `includeCurrentVersion` | `boolean` | `true` | Include the current version of your docs. | +| `lastVersion` | `string` | First version in `versions.json` | Set the version navigated to in priority and displayed by default for docs navbar items. | +| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. | | `versions` | `Versions` | `{}` | Independent customization of each version's properties. | -| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions.
Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. | -```typescript +```ts type EditUrlFunction = (params: { version: string; versionDocsDirPath: string; @@ -77,6 +78,12 @@ type PrefixParser = (filename: string) => { numberPrefix?: number; }; +type CategoryIndexMatcher = (doc: { + fileName: string; + directories: string[]; + extension: string; +}) => boolean; + type SidebarGenerator = (generatorArgs: { item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated" version: {contentPath: string; versionName: string}; // the current version @@ -88,6 +95,8 @@ type SidebarGenerator = (generatorArgs: { sidebarPosition?: number | undefined; }>; // all the docs of that version (unfiltered) numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin + categoriesMetadata: Record
'left' \| 'right' | `'left'` | The side of the navbar this item should appear on. |
+| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the sidebar belongs to. |
+
+Dark mode is now {isDarkTheme ? 'on' : 'off'}
; }; @@ -860,7 +926,7 @@ const Example = () => { :::note -The component calling `useThemeContext` must be a child of the `Layout` component. +The component calling `useColorMode` must be a child of the `Layout` component. ```jsx function ExamplePage() { diff --git a/website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-live-codeblock.md b/website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-live-codeblock.md similarity index 95% rename from website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-live-codeblock.md rename to website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-live-codeblock.md index 71e04a33ae..75e803499e 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-live-codeblock.md +++ b/website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-live-codeblock.md @@ -13,7 +13,7 @@ npm install --save @docusaurus/theme-live-codeblock ### Configuration {#configuration} -```jsx title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { plugins: ['@docusaurus/theme-live-codeblock'], themeConfig: { diff --git a/website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-search-algolia.md b/website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-search-algolia.md similarity index 79% rename from website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-search-algolia.md rename to website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-search-algolia.md index e0cee6d8f9..05e2f767fe 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-search-algolia.md +++ b/website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-search-algolia.md @@ -11,7 +11,7 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia npm install --save @docusaurus/theme-search-algolia ``` -This theme also adds search page available at `/search` (as swizzleable `SearchPage` component) path with OpenSearch support. +This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support. You can this default path via `themeConfig.algolia.searchPagePath`. Use `false` to disable search page. :::tip diff --git a/website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example-banner.png b/website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example-banner.png similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example-banner.png rename to website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example-banner.png diff --git a/website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.docx b/website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.docx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.docx rename to website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.docx diff --git a/website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.xyz b/website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.xyz similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.xyz rename to website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.xyz diff --git a/website/versioned_docs/version-2.0.0-beta.14/blog.mdx b/website/versioned_docs/version-2.0.0-beta.16/blog.mdx similarity index 81% rename from website/versioned_docs/version-2.0.0-beta.14/blog.mdx rename to website/versioned_docs/version-2.0.0-beta.16/blog.mdx index b71d166197..bdee3fcb35 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/blog.mdx +++ b/website/versioned_docs/version-2.0.0-beta.16/blog.mdx @@ -16,7 +16,7 @@ Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content ## Initial setup {#initial-setup} -To setup your site's blog, start by creating a `blog` directory. +To set up your site's blog, start by creating a `blog` directory. Then, add an item link to your blog within `docusaurus.config.js`: @@ -41,7 +41,7 @@ To publish in the blog, create a Markdown file within the blog directory. For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`: -```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md" +```md title="website/blog/2019-09-05-hello-docusaurus-v2.md" --- title: Welcome Docusaurus v2 description: This is my first post on Docusaurus 2. @@ -59,6 +59,7 @@ tags: [hello, docusaurus-v2] image: https://i.imgur.com/mErPwqL.png hide_table_of_contents: false --- + Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/). @@ -68,35 +69,7 @@ This is my first post on Docusaurus 2. A whole bunch of exploration to follow. ``` -:::note - -Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`. - -This naming convention is optional, and you can provide the date as FrontMatter. - -
-
-
-:::
-
-:::tip
-
-Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
-
-:::
-
-The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter).
+The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
## Blog list {#blog-list}
@@ -104,10 +77,11 @@ The blog's index page (by default, it is at `/blog`) is the _blog list page_, wh
Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. For example:
-```yml
+```md
---
title: Truncation Example
---
+
All these will be part of the blog post summary.
Even this.
@@ -121,7 +95,7 @@ Not this.
Or this.
```
-By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add meta description to the blog list page for better SEO:
+By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add a meta description to the blog list page for better SEO:
```js title="docusaurus.config.js"
module.exports = {
@@ -147,7 +121,7 @@ module.exports = {
The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed.
-You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts":
+You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may rather make it say "All posts":
```js title="docusaurus.config.js"
module.exports = {
@@ -167,19 +141,61 @@ module.exports = {
};
```
+## Blog post date {#blog-post-date}
+
+Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
+
+Example supported patterns
- -- `2021-05-28-my-blog-post-title.md` -- `2021-05-28-my-blog-post-title.mdx` -- `2021-05-28-my-blog-post-title/index.md` -- `2021-05-28/my-blog-post-title.md` -- `2021/05/28/my-blog-post-title.md` -- `2021/05-28-my-blog-post-title.md` -- `2021/05/28/my-blog-post-title/index.md` -- ... - -
+
+
+:::tip
+
+Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
+
+:::
+
+This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:
+
+```md title="earlier-post.md"
+---
+date: 2021-09-13T10:00
+---
+```
+
+```md title="later-post.md"
+---
+date: 2021-09-13T18:00
+---
+```
+
## Blog post authors {#blog-post-authors}
-Use the `authors` FrontMatter field to declare blog post authors.
+Use the `authors` front matter field to declare blog post authors.
### Inline authors {#inline-authors}
-Blog post authors can be declared directly inside the FrontMatter:
+Blog post authors can be declared directly inside the front matter:
````mdx-code-block
-Example supported patterns
+ +| Pattern | Example | +| --- | --- | +| Single file | `2021-05-28-my-blog-post-title.md` | +| MDX file | `2021-05-28-my-blog-post-title.mdx` | +| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` | +| Folder named by date | `2021-05-28/my-blog-post-title.md` | +| Nested folders by date | `2021/05/28/my-blog-post-title.md` | +| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` | +| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` | +| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` | + +The date will be excised from the path and appended to the beginning of the URL slug. + +
-
-
-
:::
They can also be loaded from local directories:
@@ -165,7 +120,7 @@ The `presets: [['classic', {...}]]` shorthand works as well.
:::
-For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
+For further help configuring themes, plugins, and presets, see [Using Plugins](./using-plugins.md).
### Custom configurations {#custom-configurations}
@@ -215,7 +170,7 @@ If you just want to use those fields on the client side, you could create your o
## Customizing Babel Configuration {#customizing-babel-configuration}
-For new Docusaurus projects, we automatically generated a `babel.config.js` in project root.
+For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root.
```js title="babel.config.js"
module.exports = {
@@ -223,4 +178,4 @@ module.exports = {
};
```
-Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.
+Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.
diff --git a/website/versioned_docs/version-2.0.0-beta.14/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.16/deployment.mdx
similarity index 83%
rename from website/versioned_docs/version-2.0.0-beta.14/deployment.mdx
rename to website/versioned_docs/version-2.0.0-beta.16/deployment.mdx
index 649151e36e..17176a9d08 100644
--- a/website/versioned_docs/version-2.0.0-beta.14/deployment.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.16/deployment.mdx
@@ -25,7 +25,7 @@ A Docusaurus site is statically rendered, and it can generally work without Java
## Configuration {#configuration}
-The following parameters are required in `docusaurus.config.js` in order for Docusaurus to optimize routing and serve files from the correct location:
+The following parameters are required in `docusaurus.config.js` to optimize routing and serve files from the correct location:
| Name | Description |
| --- | --- |
@@ -34,7 +34,7 @@ The following parameters are required in `docusaurus.config.js` in order for Doc
## Testing your Build Locally {#testing-build-locally}
-It is important to test your build locally before deploying to production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
+It is important to test your build locally before deploying it for production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
```bash npm2yarn
npm run serve
@@ -54,7 +54,38 @@ Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-gui
:::
-## Choosing a hosting provider
+## Using environment variables {#using-environment-variables}
+
+Putting potentially sensitive information in the environment is common practice. However, in a typical Docusaurus website, the `docusaurus.config.js` file is the only interface to the Node.js environment (see [our architecture overview](advanced/architecture.md)), while everything elseβMDX pages, React components... are client side and do not have direct access to the `process` global. In this case, you can consider using [`customFields`](api/docusaurus.config.js.md#customfields) to pass environment variables to the client side.
+
+```js title="docusaurus.config.js"
+// If you are using dotenv (https://www.npmjs.com/package/dotenv)
+require('dotenv').config();
+
+module.exports = {
+ title: '...',
+ url: process.env.URL, // You can use environment variables to control site specifics as well
+ // highlight-start
+ customFields: {
+ // Put your custom environment here
+ teamEmail: process.env.EMAIL,
+ },
+ // highlight-end
+};
+```
+
+```jsx title="home.jsx"
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export default function Home() {
+ const {
+ siteConfig: {customFields},
+ } = useDocusaurusContext();
+ return How are shorthands resolved?
- -When it sees a plugin / theme / preset name, it tries to load one of the following, in that order: - -- `[name]` -- `@docusaurus/[moduleType]-[name]` -- `docusaurus-[moduleType]-[name]`, - -where `moduleType` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded. - -If the name is scoped (beginning with `@`), the name is first split into scope and package name by the first slash: - -``` -@scope -^----^ - scope (no name!) - -@scope/awesome -^----^ ^-----^ - scope name - -@scope/awesome/main -^----^ ^----------^ - scope name -``` - -If the name is not specified, `{scope}/docusaurus-{type}` is loaded. Otherwise, the following are attempted: - -- `{scope}/{name}` -- `{scope}/docusaurus-{type}-{name}` - -Below are some examples, for a plugin registered in the `plugins` field. Note that unlike [ESLint](https://eslint.org/docs/user-guide/configuring/plugins#configuring-plugins) or [Babel](https://babeljs.io/docs/en/options#name-normalization) where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above. - -| Declaration | May be resolved as | -| --- | --- | -| `awesome` | `docusaurus-plugin-awesome` | -| `sitemap` | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) | -| `@mycompany` | `@mycompany/docusaurus-plugin` (the only possible resolution!) | -| `@mycompany/awesome` | `@mycompany/docusaurus-plugin-awesome` | -| `@mycompany/awesome/web` | `@mycompany/docusaurus-plugin-awesome/web` | - -Contact us through {customFields.teamEmail}!
;
+}
+```
+
+## Choosing a hosting provider {#choosing-a-hosting-provider}
There are a few common hosting options:
@@ -70,8 +101,8 @@ If you are unsure of which one to choose, ask the following questions:
How much resource (person-hours, money) am I willing to invest in this?
-- π΄ Self-hosting is the hardest to set upβyou would usually need an experienced person to manage this. Cloud services is almost never free, and setting up an on-site server and connecting it to the WAN can be more costly.
-- π’ Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quota even for free plans that you would almost never exceed. However, it's still ultimately limitedβyou would need to pay once you hit the limit. Check the pricing page of your provider for details.
+- π΄ Self-hosting is the hardest to set upβyou would usually need an experienced person to manage this. Cloud services are almost never free, and setting up an on-site server and connecting it to the WAN can be even more costly.
+- π’ Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quotas even for free plans that you would almost never exceed. However, it's still ultimately limitedβyou would need to pay once you hit the limit. Check the pricing page of your provider for details.
- π‘ The GitHub Pages deployment workflow can be tedious to set up. (Evidence: see the length of [Deploying to GitHub Pages](#deploying-to-github-pages)!) However, this service (including build and deployment) is always free for public repositories, and we have detailed instructions to help you make it work.
@@ -124,10 +155,12 @@ For the same concern of up-to-datedness, we have stopped accepting PRs adding ne
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
-```js {2-3} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
module.exports = {
+ // highlight-start
url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
+ // highlight-end
// ...
};
```
@@ -192,7 +225,7 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu
### Overview {#github-pages-overview}
-Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively.
+Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial, they will be referred to as **"source"** and **"deployment"**, respectively.
Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
@@ -228,14 +261,16 @@ GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommen
Example:
-```jsx {3-6} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
+ // highlight-start
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
+ // highlight-end
// ...
};
```
@@ -296,7 +331,7 @@ cmd /C 'set "GIT_USER=+ {/* highlight-next-line */} Check out my blog!
+ {/* highlight-next-line */} Follow me on Twitter!
+ {/* highlight-start */}
);
};
```
+:::note
+
+The `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side.
+
+:::
+
### `useIsBrowser` {#useIsBrowser}
Returns `true` when the React app has successfully hydrated in the browser.
@@ -376,9 +403,7 @@ Returns `true` when the React app has successfully hydrated in the browser.
Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic.
-The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js).
-
-Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
+The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
:::
@@ -450,7 +475,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
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
import React from 'react';
@@ -470,11 +495,11 @@ const Component = () => {
React hook to access Docusaurus global data created by all the plugins.
-Global data is namespaced by plugin name, and plugin id.
+Global data is namespaced by plugin name then by plugin ID.
:::info
-Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
+Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
:::
@@ -490,14 +515,17 @@ type GlobalData = Record<
Usage example:
-```jsx {2,5-7}
+```jsx
import React from 'react';
+// highlight-next-line
import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {
+ // highlight-start
const globalData = useGlobalData();
const myPluginData = globalData['my-plugin']['default'];
return {siteConfig.title}
{siteMetadata.siteVersion}
{siteMetadata.docusaurusVersion}
+ {/* highlight-end */}
{myPluginData.someAttribute}
;
+ // highlight-end
};
```
@@ -511,23 +539,26 @@ Inspect your site's global data at `./docusaurus/globalData.json`
Access global data created by a specific plugin instance.
-This is the most convenient hook to access plugin global data, and should be used most of the time.
+This is the most convenient hook to access plugin global data and should be used most of the time.
`pluginId` is optional if you don't use multi-instance plugins.
```ts
-usePluginData(pluginName: string, pluginId?: string)
+function usePluginData(pluginName: string, pluginId?: string);
```
Usage example:
-```jsx {2,5-6}
+```jsx
import React from 'react';
+// highlight-next-line
import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
+ // highlight-start
const myPluginData = usePluginData('my-plugin');
return {myPluginData.someAttribute}
;
+ // highlight-end
};
```
@@ -541,14 +572,17 @@ useAllPluginInstancesData(pluginName: string)
Usage example:
-```jsx {2,5-7}
+```jsx
import React from 'react';
+// highlight-next-line
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
+ // highlight-start
const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
const myPluginData = allPluginInstancesData['default'];
return {myPluginData.someAttribute}
;
+ // highlight-end
};
```
@@ -573,10 +607,9 @@ function interpolate(
#### Example {#example-1}
-```jsx
-// highlight-start
+```js
+// highlight-next-line
import {interpolate} from '@docusaurus/Interpolate';
-// highlight-end
const message = interpolate('Welcome {firstName}', {firstName: 'SΓ©bastien'});
```
@@ -610,17 +643,14 @@ function translate(
import React from 'react';
import Layout from '@theme/Layout';
-// highlight-start
+// highlight-next-line
import {translate} from '@docusaurus/Translate';
-// highlight-end
export default function Home() {
return (
+Hello from Docusaurus
@@ -69,9 +69,9 @@ will show up on the table of contents on the upper right So that your users will know what this page is all about without scrolling down or even without reading too much. -Only h2 and h3 will be in the toc by default.
+Only h2 and h3 will be in the TOC by default.
-You can configure the TOC heading levels either per-document or in the theme configuration. +You can configure the TOC heading levels either per document or in the theme configuration. The headers are well-spaced so that the hierarchy is clear. @@ -98,9 +98,9 @@ Read more about [importing partial pages](../markdown-features/markdown-features ## Doc tags {#doc-tags} -Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels: +Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels: -```yml "your-doc-page.md" +```md "your-doc-page.md" --- id: doc-with-tags title: A doc with tags diff --git a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-introduction.md similarity index 85% rename from website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-introduction.md rename to website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-introduction.md index 793c5468f7..426186a72b 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-introduction.md +++ b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-introduction.md @@ -27,22 +27,24 @@ website # Root directory of your site βββ hello.md ``` -However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. +However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. -```yml +```md --- id: part1 --- + Lorem ipsum ``` If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`). -```yml +```md --- id: part1 slug: part1.html --- + Lorem ipsum ``` @@ -57,13 +59,14 @@ It is possible to use: ## Home page docs {#home-page-docs} -If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter: +If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter: -```yml +```md --- id: my-home-doc slug: / --- + Lorem ipsum ``` @@ -83,7 +86,7 @@ example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-m ... ``` -All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root? +All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting them at the root? Assume that you have the following in your configuration: @@ -126,15 +129,16 @@ module.exports = { }; ``` -Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute. +Note that you **don't necessarily have to give up on using the blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute. Don't forget to put some page at the root (`https://example.com/`) through adding the front matter: -```yml title="docs/intro.md" +```md title="docs/intro.md" --- # highlight-next-line slug: / --- + This page will be the home page when users visit https://example.com/. ``` diff --git a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-markdown-features.mdx similarity index 76% rename from website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-markdown-features.mdx rename to website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-markdown-features.mdx index eb5b7732a0..40be16cb9e 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-markdown-features.mdx +++ b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-markdown-features.mdx @@ -5,11 +5,11 @@ description: Docusaurus Markdown features that are specific to the docs plugin slug: /docs-markdown-features --- -Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional docs-specific Markdown features. +Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features. -## Markdown frontmatter {#markdown-frontmatter} +## Markdown front matter {#markdown-front-matter} -Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter) +Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter). ## Referencing other documents {#referencing-other-documents} @@ -29,7 +29,7 @@ Reference to another [document in a subfolder](subfolder/doc3.md). :::tip -It is better to use relative file paths links instead of relative links: +Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits: - links will keep working on the GitHub interface - you can customize the document slugs without having to update all the links diff --git a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-multi-instance.mdx b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-multi-instance.mdx similarity index 94% rename from website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-multi-instance.mdx rename to website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-multi-instance.mdx index 9b6d144a84..1ab708b4c9 100644 --- a/website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-multi-instance.mdx +++ b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-multi-instance.mdx @@ -9,7 +9,7 @@ The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../ :::note -This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. +This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar/multiple-sidebars.md), you can do so within one plugin. ::: @@ -26,7 +26,7 @@ If you build a cross-platform mobile SDK, you may have 2 documentations: - Android SDK documentation (`v1.0`, `v1.1`) - iOS SDK documentation (`v1.0`, `v2.0`) -In such case, you can use a distinct docs plugin instance per mobile SDK documentation. +In this case, you can use a distinct docs plugin instance per mobile SDK documentation. :::caution diff --git a/website/versioned_docs/version-2.0.0-beta.16/guides/docs/sidebar/autogenerated.md b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/sidebar/autogenerated.md new file mode 100644 index 0000000000..807de81571 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.16/guides/docs/sidebar/autogenerated.md @@ -0,0 +1,487 @@ +--- +slug: /sidebar/autogenerated +--- + +# Autogenerated + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category, and each file creates a doc link. + +```ts +type SidebarItemAutogenerated = { + type: 'autogenerated'; + dirName: string; // Source folder to generate the sidebar slice from (relative to docs) +}; +``` + +Docusaurus can generate a full sidebar from your docs folder: + +```js title="sidebars.js" +module.exports = { + myAutogeneratedSidebar: [ + // highlight-start + { + type: 'autogenerated', + dirName: '.', // '.' means the current docs folder + }, + // highlight-end + ], +}; +``` + +An `autogenerated` item is converted by Docusaurus to a **sidebar slice** (also discussed in [category shorthands](items.md#category-shorthand)): a list of items of type `doc` or `category`, so you can splice **multiple `autogenerated` items** from multiple directories, interleaving them with regular sidebar items, in one sidebar level. + +
+
+
+## Category index convention {#category-index-convention}
+
+Docusaurus can automatically link a category to its index document.
+
+A category index document is a document following one of those filename conventions:
+
+- Named as `index` (case-insensitive): `docs/Guides/index.md`
+- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
+- Same name as parent folder: `docs/Guides/Guides.md`
+
+This is equivalent to using a category with a [doc link](items.md#category-doc-link):
+
+```js title="sidebars.js"
+module.exports = {
+ docs: [
+ // highlight-start
+ {
+ type: 'category',
+ label: 'Guides',
+ link: {type: 'doc', id: 'Guides/index'},
+ items: [],
+ },
+ // highlight-end
+ ],
+};
+```
+
+:::tip
+
+Naming your introductory document `README.md` makes it show up when browsing the folder using the GitHub interface, while using `index.md` makes the behavior more in line with how HTML files are served.
+
+:::
+
+:::tip
+
+If a folder only has one index page, it will be turned into a link instead of a category. This is useful for **asset collocation**:
+
+```
+some-doc
+βββ index.md
+βββ img1.png
+βββ img2.png
+```
+
+:::
+
+A real-world example
+Consider this file structure: + +```bash +docs +βββ api +β βββ product1-api +β β βββ api.md +β βββ product2-api +β βββ basic-api.md +β βββ pro-api.md +βββ intro.md +βββ tutorials + βββ advanced + β βββ advanced1.md + β βββ advanced2.md + β βββ read-more + β βββ resource1.md + β βββ resource2.md + βββ easy + β βββ easy1.md + β βββ easy2.md + βββ tutorial-end.md + βββ tutorial-intro.md + βββ tutorial-medium.md +``` + +And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this: + +```js title="sidebars.js" +module.exports = { + mySidebar: [ + 'intro', + { + type: 'category', + label: 'Tutorials', + items: [ + 'tutorial-intro', + // highlight-start + { + type: 'autogenerated', + dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy + }, + // highlight-end + 'tutorial-medium', + // highlight-start + { + type: 'autogenerated', + dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard + }, + // highlight-end + 'tutorial-end', + ], + }, + // highlight-start + { + type: 'autogenerated', + dirName: 'api', // Generate sidebar slice from docs/api + }, + // highlight-end + { + type: 'category', + label: 'Community', + items: ['team', 'chat'], + }, + ], +}; +``` + +It would be resolved as: + +```js title="sidebars.js" +module.exports = { + mySidebar: [ + 'intro', + { + type: 'category', + label: 'Tutorials', + items: [ + 'tutorial-intro', + // highlight-start + // Two files in docs/tutorials/easy + 'easy1', + 'easy2', + // highlight-end + 'tutorial-medium', + // highlight-start + // Two files and a folder in docs/tutorials/hard + 'advanced1', + 'advanced2', + { + type: 'category', + label: 'read-more', + items: ['resource1', 'resource2'], + }, + // highlight-end + 'tutorial-end', + ], + }, + // highlight-start + // Two folders in docs/api + { + type: 'category', + label: 'product1-api', + items: ['api'], + }, + { + type: 'category', + label: 'product2-api', + items: ['basic-api', 'pro-api'], + }, + // highlight-end + { + type: 'category', + label: 'Community', + items: ['team', 'chat'], + }, + ], +}; +``` + +Note how the autogenerate source directories themselves don't become categories: only the items they contain do. This is what we mean by "sidebar slice". + +
+
+
+
+## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
+
+For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names).
+
+**For docs**: use additional front matter. The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter.
+
+```md title="docs/tutorials/tutorial-easy.md"
+---
+# highlight-start
+sidebar_position: 2
+sidebar_label: Easy
+sidebar_class_name: green
+# highlight-end
+---
+
+# Easy Tutorial
+
+This is the easy tutorial!
+```
+
+**For categories**: add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata.
+
+Customizing category index matching
+ +It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index. + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + async sidebarItemsGenerator({ + ...args, + isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below + defaultSidebarItemsGenerator, + }) { + return defaultSidebarItemsGenerator({ + ...args, + // highlight-start + isCategoryIndex(doc) { + return ( + // Also pick intro.md in addition to the default ones + doc.fileName.toLowerCase() === 'intro' || + defaultCategoryIndexMatcher(doc) + ); + }, + // highlight-end + }); + }, + }, + ], + ], +}; +``` + +Or choose to not have any category index convention. + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + async sidebarItemsGenerator({ + ...args, + isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below + defaultSidebarItemsGenerator, + }) { + return defaultSidebarItemsGenerator({ + ...args, + // highlight-start + isCategoryIndex() { + // No doc will be automatically picked as category index + return false; + }, + // highlight-end + }); + }, + }, + ], + ], +}; +``` + +The `isCategoryIndex` matcher will be provided with three fields: + +- `fileName`, the file's name without extension and with casing preserved +- `directories`, the list of directory names _from the lowest level to the highest level_, relative to the docs root directory +- `extension`, the file's extension, with a leading dot. + +For example, for a doc file at `guides/sidebar/autogenerated.md`, the props the matcher receives are + +```js +const props = { + fileName: 'autogenerated', + directories: ['sidebar', 'guides'], + extension: '.md', +}; +``` + +The default implementation is: + +```js +function isCategoryIndex({fileName, directories}) { + const eligibleDocIndexNames = [ + 'index', + 'readme', + directories[0].toLowerCase(), + ]; + return eligibleDocIndexNames.includes(fileName.toLowerCase()); +} +``` + +
', // The HTML to be rendered
+ defaultStyle: true, // Use the default menu item styling
+ },
+ // highlight-end
+ ],
+};
+```
+
+:::tip
+
+The menu item is already wrapped in an `-
+
- Current version +
- The version placed in the
./docsfolder.
+ - Latest version / last version +
- The version served by default for docs navbar items. Usually has path
/docs.
+
Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.
-+ Use plugins to introduce shorter syntax for the most commonly used JSX + elements in your project. +
+.default})
+
`, without any processing or file existence checking.
diff --git a/website/versioned_docs/version-2.0.0-beta.14/guides/markdown-features/markdown-features-code-blocks.mdx b/website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-code-blocks.mdx
similarity index 67%
rename from website/versioned_docs/version-2.0.0-beta.14/guides/markdown-features/markdown-features-code-blocks.mdx
rename to website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-code-blocks.mdx
index 5c355f1e46..7934b6ebaa 100644
--- a/website/versioned_docs/version-2.0.0-beta.14/guides/markdown-features/markdown-features-code-blocks.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-code-blocks.mdx
@@ -5,11 +5,14 @@ description: Handling code blocks in Docusaurus Markdown
slug: /markdown-features/code-blocks
---
+import BrowserWindow from '@site/src/components/BrowserWindow';
+import CodeBlock from '@theme/CodeBlock';
+
Code blocks within documentation are super-powered πͺ.
## Code title {#code-title}
-You can add a title to the code block by adding `title` key after the language (leave a space between them).
+You can add a title to the code block by adding a `title` key after the language (leave a space between them).
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
@@ -17,44 +20,53 @@ You can add a title to the code block by adding `title` key after the language (
}
```
+Hello, {props.name}
; } ``` +Bar
;
- }
-
- return Foo
;
- }
-
- export default MyComponent;
- ```
-
-```jsx {1,4-6,11}
-import React from 'react';
-
-function MyComponent(props) {
- if (props.isBar) {
- return Bar
;
- }
-
- return Foo
;
-}
-
-export default MyComponent;
-```
-
### Highlighting with comments {#highlighting-with-comments}
-You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
+You can use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
- ```jsx
+ ```js
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
@@ -205,7 +148,10 @@ You can also use comments with `highlight-next-line`, `highlight-start`, and `hi
}
```
-```jsx
+````mdx-code-block
+Bar
;
+ }
+
+ return Foo
;
+ }
+
+ export default MyComponent;
+ ```
+
+Bar
;
+ }
+
+ return Foo
;
+}
+
+export default MyComponent;
+```
+
+``` :::note diff --git a/website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-math-equations.mdx b/website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-math-equations.mdx new file mode 100644 index 0000000000..d785f3d027 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.16/guides/markdown-features/markdown-features-math-equations.mdx @@ -0,0 +1,208 @@ +--- +id: math-equations +title: Math Equations +description: Writing LaTeX Math Equations +slug: /markdown-features/math-equations +--- + +import BrowserWindow from '@site/src/components/BrowserWindow'; + +Mathematical equations can be rendered using [KaTeX](https://katex.org). + +## Usage {#usage} + +Please read [KaTeX](https://katex.org) documentation for more details. + +### Inline {#inline} + +Write inline math equations by wrapping LaTeX equations between `$`: + +```mdx +Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x)= +\int_{a}^{x} f(t)\,dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$. +``` + +
How are remark-math and rehype-katex different?
-In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transforms that to the JSX `...` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin.
+In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transform that to the JSX `...` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin.
-Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class, and uses $\KaTeX$ to parse and render the content to actual HTML.
+Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class and uses $\KaTeX$ to parse and render the content to actual HTML.
+
+
+
+
+
+
+Use JSX for the rest of the line, or prefix the line with some plain text:
+
+
+
+
+**Markdown within a JSX tag never works:**
+
+
+
+
+
+
+Use JSX within JSX tag, or move the Markdown to the outer layer:
+
+
+
+
+**Text immediately below a JSX tag will be seen as JSX text:**
+
+
+
+
+
+
+Add an empty new line:
+
+
+
+
+**Markdown text indented by four spaces will be seen as a code block:**
+
+
+
+
+
+
+Don't indent:
+
+
+
+
+````
+
+## Importing code snippets {#importing-code-snippets}
+
+You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, you first need to install it in your project:
+
+```bash npm2yarn
+npm install --save raw-loader
+```
+
+Now you can import code snippets from another file as it is:
+
+
+```jsx title="myMarkdownFile.mdx"
+import CodeBlock from '@theme/CodeBlock';
+import MyComponentSource from '!!raw-loader!./myComponent';
+
+Samples of parsing failures
+ +**A paragraph starting with a JSX tag will be seen entirely as a JSX string:** + +
+
+```jsx
+Highlighted text but afterwards _Markdown_ **doesn't work**
+```
+
+
+
+
+
+Highlighted text but afterwards _Markdown_ **doesn't work**
+
+
+
+
+
+```jsx
+Use JSX for the paragraph to stop worrying about Markdown
+
+β This is a zero-width space and afterwards Markdown works
+```
+
+
+
+
+
+Use JSX for the paragraph to stop worrying about Markdown
+
+β This is a zero-width space and afterwards Markdown works
+
+
+
+
+
+```jsx
+**Bold doesn't work**
+```
+
+
+
+
+
+**Bold doesn't work**
+
+
+
+
+
+
+```jsx
+Bold now works
+
+**Bold now works**
+```
+
+
+
+
+
+Bold now works
+
+**Bold now works**
+
+
+
+
+
+```jsx
+
+
+**Bold still doesn't work**
+
+```
+
+
+
+
+
+
+
+**Bold still doesn't work**
+
+
+
+
+```jsx
+
+
+
+**Bold now works**
+
+
+```
+
+
+
+
+
+
+
+**Bold now works**
+
+
+
+
+```jsx
+
+
+
+ You may think I'm just some text...
+
+
+```
+
+
+
+
+
+
+
+
+ You may think I'm just some text...
+
+
+
+
+
+```jsx
+
+
+
+Now I'm actually just text
+
+
+```
+
+
+
+
+
+
+
+Now I'm actually just text
+
+
++``` + +See [using code blocks in JSX](./markdown-features-code-blocks.mdx#usage-in-jsx) for more details of the `
+``` + +This way, you can reuse content among multiple pages and avoid duplicating materials. + +:::caution + +The table of contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)). + +::: + +## Available exports {#available-exports} + +Within the MDX page, the following variables are available as globals: + +- `frontMatter`: the front matter as a record of string keys and values; +- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case. +- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter). + +```jsx +import TOCInline from '@theme/TOCInline'; +import CodeBlock from '@theme/CodeBlock'; + +The table of contents for this page, serialized: + +
-
+ {Object.entries(frontMatter).map(([key, value]) =>
- {key}: {value} )} +
The title of this page is: {contentTitle}
+``` + +```mdx-code-block +import TOCInline from '@theme/TOCInline'; + +-
+ {Object.entries(frontMatter).map(([key, value]) =>
- {key}: {value} )} +
The title of this page is: {contentTitle}
+ +``` -For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change. +For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group is chosen a value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups don't change. ```jsx
Welcome to my website
+
+
+ {/* highlight-next-line */}
+ Welcome to my website
+
+
+ -
+ {/* DON'T DO THIS: doesn't work with the write-translations command */}
+ {items.map((item) => (
+
-
+
{item.title} +
+ ))}
+ - {item.title} + ))} +
-
+ );
+}
+```
+
+This still behaves correctly at runtime. However, in the future, we may provide a "no-runtime" mechanism, allowing the translations to be directly inlined in the React code through Babel transformations, instead of calling the APIs at runtime. Therefore, to be future-proof, you should always prefer statically analyzable messages. For example, we can refactor the code above to:
+
+```tsx
+const items = [
+ {id: 1, title:
-
+ {/* The titles are now already translated when rendering! */}
+ {items.map((item) => (
+
-
+ );
+}
+```
+
+You can see the calls to the translation APIs as purely _markers_ that tell Docusaurus that "here's a text label to be replaced with a translated message".
+
+:::
+
+### Translate plugin data {#translate-plugin-data}
+
+JSON translation files are used for everything that is interspersed in your code:
+
+- React code, including the translated labels you have marked above
+- Navbar and footer labels in theme config
+- Docs sidebar category labels in `sidebars.js`
+- Blog sidebar title in plugin options
+- ...
+
+Run the [write-translations](../cli.md#docusaurus-write-translations-sitedir) command:
+
+```bash npm2yarn
+npm run write-translations -- --locale fr
+```
+
+It will extract and initialize the JSON translation files that you need to translate. The `code.json` file at the root includes all translation API calls extracted from the source code, which could either be written by you or provided by the themes, some of which may already be translated by default.
+
+```json title="i18n/fr/code.json"
+{
+ // No ID for the
+
+
+
+```bash
+npm init docusaurus website classic
+```
+
+
+
+
+```bash
+yarn create docusaurus website classic
+```
+
+
+
+
+```bash
+pnpm create docusaurus website classic
+```
+
+
+
+````
+
+
+
+Docusaurus makes best efforts to select a package manager to install dependencies for you, based on the command you are using and the project you are in. You can override this behavior by using `--package-manager [npm/yarn/pnpm]`.
+
+```bash
+# Use Yarn to install dependencies even when the command is npx
+npx create-docusaurus@latest my-website classic --package-manager yarn
+```
+
+If you want to skip installing dependencies, use the `--skip-install` option.
+
+```bash
+npx create-docusaurus@latest my-website classic --skip-install
+```
+
## Project structure {#project-structure}
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`:
-```sh
+```bash
my-website
βββ blog
β βββ 2019-05-28-hola.md
@@ -95,6 +146,28 @@ my-website
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
+### Monorepos {#monorepos}
+
+If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:
+
+```bash
+my-monorepo
+βββ package-a # Another package, your actual project
+β βββ src
+β βββ package.json # Package A's dependencies
+βββ website # Docusaurus root
+β βββ docs
+β βββ src
+β βββ package.json # Docusaurus' dependencies
+βββ package.json # Monorepo's shared dependencies
+```
+
+In this case, you should run `npx create-docusaurus` within the `./my-monorepo` folder.
+
+If you're using a hosting provider such as Netlify or Vercel, you will need to change the `Base directory` of the site to where your Docusaurus root is. In this case, that would be `./website`. Read more about configuring ignore commands in the [deployment docs](./deployment.mdx#deploying-to-netlify).
+
+Read more about monorepos in the [Yarn documentation](https://yarnpkg.com/features/workspaces) (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout [Docusaurus](https://github.com/facebook/docusaurus) and [Jest](https://github.com/facebook/jest) for some real-world examples.
+
## Running the development server {#running-the-development-server}
To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.
@@ -154,4 +227,4 @@ Use new unreleased features of Docusaurus with the [`@canary` npm dist tag](/com
## Problems? {#problems}
-Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus) or [Twitter](https://twitter.com/docusaurus).
+Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus), our [Discord server](https://discordapp.com/invite/docusaurus), or [Twitter](https://twitter.com/docusaurus).
diff --git a/website/versioned_docs/version-2.0.0-beta.14/introduction.md b/website/versioned_docs/version-2.0.0-beta.16/introduction.md
similarity index 54%
rename from website/versioned_docs/version-2.0.0-beta.14/introduction.md
rename to website/versioned_docs/version-2.0.0-beta.16/introduction.md
index b56532a2f5..36c26cfe15 100644
--- a/website/versioned_docs/version-2.0.0-beta.14/introduction.md
+++ b/website/versioned_docs/version-2.0.0-beta.16/introduction.md
@@ -13,7 +13,7 @@ slug: /
π
Check the **[best Docusaurus sites](/showcase?tags=favorite)** for inspiration and read some **[testimonials](https://twitter.com/sebastienlorber/timelines/1392048416872706049)**.
-π§ Docusaurus is a **static-site generator**. It builds a **single-page application** with a fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features**, but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
+π§ Docusaurus is a **static-site generator**. It builds a **single-page application** with fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features** but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
@@ -46,6 +46,22 @@ Or read the **[5-minute tutorial](https://tutorial.docusaurus.io)** online.
:::
+## Docusaurus: Documentation Made Easy
+
+In this presentation at [Algolia Community Event](https://www.algolia.com/), [Meta Open Source team](https://opensource.facebook.com/) shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
+
+Alternative installation commands
+ +You can also initialize a new project using your preferred project manager: + +````mdx-code-block +
+
+
+
## Disclaimer {#disclaimer}
Docusaurus v2 is **beta** but already quite stable and widely used.
@@ -70,45 +86,45 @@ A [lot of users](/showcase) are already using Docusaurus v2 ([trends](https://ww
Docusaurus is built with high attention to the developer and contributor experience.
-- βοΈ **Built with π and React**
+- βοΈ **Built with π and React**:
- Extend and customize with React
- Gain full control of your site's browsing experience by providing your own React components
-- **Pluggable**
+- **Pluggable**:
- Bootstrap your site with a basic template, then use advanced features and plugins
- Open source your plugins to share with the community
-- βοΈ **Developer experience**
+- βοΈ **Developer experience**:
- Start writing your docs right now
- Universal configuration entry point to make it more maintainable by contributors
- - Hot reloading with lightning fast incremental build on changes
+ - Hot reloading with lightning-fast incremental build on changes
- Route-based code and data splitting
- - Publish to GitHub Pages, Netlify, Vercel and other deployment services with ease
+ - Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease
-Our shared goal β to help your users find what they need fast, and understand your products better. We share with you our best practices helping you build your doc site right and well.
+Our shared goalβto help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.
-- π― **SEO friendly**
- - HTML files are statically generated for every possible path
- - page-specific SEO to help your users land on your official docs directly relating their problems at hand
-- π **Powered by MDX**
- - Write interactive components via JSX and React embedded in markdown
- - Share your code in live editors to get your users love your products on the spot
-- π **Search** - Your full site is searchable
-- πΎ **Document Versioning** - Helps you keep documentation in sync with project releases.
-- π **i18n** - Translate your site in multiple locales
+- π― **SEO friendly**:
+ - HTML files are statically generated for every possible path.
+ - Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
+- π **Powered by MDX**:
+ - Write interactive components via JSX and React embedded in markdown.
+ - Share your code in live editors to get your users to love your products on the spot.
+- π **Search**: Your full site is searchable.
+- πΎ **Document Versioning**: Helps you keep documentation in sync with project releases.
+- π **Internationalization (i18n)**: Translate your site in multiple locales.
-Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.
+Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.
-- β‘οΈ **Lightning fast** - Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
-- π¦ **Accessible** - Attention to accessibility, making your site equally accessible to all users
+- β‘οΈ **Lightning-fast**. Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast.
+- π¦ **Accessible**. Attention to accessibility, making your site equally accessible to all users.
## Design principles {#design-principles}
-- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
-- **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
-- **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
-- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
-- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users.
+- **Little to learn**. Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talkβ[Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
+- **Intuitive**. Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
+- **Layered architecture**. The separations of concerns between each layer of our stack (content/theming/styling) should be clearβwell-abstracted and modular.
+- **Sensible defaults**. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
+- **No vendor lock-in**. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users.
-We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
+We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
+### Mobile View {#mobile-view}
+
+Docusaurus uses `966px` as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.
+
+```css
+.banner {
+ padding: 4rem;
+}
+/** In mobile view, reduce the padding */
+@media screen and (max-width: 966px) {
+ .heroBanner {
+ padding: 2rem;
+ }
+}
+```
## CSS modules {#css-modules}
@@ -150,7 +174,7 @@ function MyComponent() {
}
```
-The class names which will be processed by webpack into a globally unique class name during build.
+The class names will be processed by webpack into a globally unique class name during build.
## CSS-in-JS {#css-in-js}
@@ -172,9 +196,10 @@ npm install --save docusaurus-plugin-sass sass
2. Include the plugin in your `docusaurus.config.js` file:
-```jsx {3} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
module.exports = {
// ...
+ // highlight-next-line
plugins: ['docusaurus-plugin-sass'],
// ...
};
@@ -186,7 +211,7 @@ module.exports = {
You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
-```jsx {8} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
module.exports = {
presets: [
[
@@ -194,6 +219,7 @@ module.exports = {
{
// ...
theme: {
+ // highlight-next-line
customCss: [require.resolve('./src/css/custom.scss')],
},
// ...
diff --git a/website/versioned_docs/version-2.0.0-beta.16/swizzling.md b/website/versioned_docs/version-2.0.0-beta.16/swizzling.md
new file mode 100644
index 0000000000..d1cf3347a6
--- /dev/null
+++ b/website/versioned_docs/version-2.0.0-beta.16/swizzling.md
@@ -0,0 +1,324 @@
+---
+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 will write actual React code instead of playing with stylesheets. We will talk about a central concept in Docusaurus: **swizzling**, which allows **deeper site customizations**.
+
+In practice, swizzling permits to **swap a theme component with your own implementation**, and it comes in 2 patterns:
+
+- [**Ejecting**](#ejecting): creates a **copy** of the original theme component, which you can fully **customize**
+- [**Wrapping**](#wrapping): creates a **wrapper** around the original theme component, which you can **enhance**
+
+
+
+
+
+## Swizzling Process
+
+### Overview
+
+Docusaurus provides an convenient **interactive CLI** to swizzle components. You generally only need to remember the following command:
+
+```bash npm2yarn
+npm run swizzle
+```
+
+It will generate a new component your `src/theme` directory, which should look like this example:
+
+````mdx-code-block
+Why is it called swizzling?
+ +**The name comes from Objective-C and Swift-UI**: [method swizzling](https://pspdfkit.com/blog/2019/swizzling-in-swift/) is the process of changing the implementation of an existing selector (method). + +**For Docusaurus, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** + +You can think of it as [Monkey Patching](https://en.wikipedia.org/wiki/Monkey_patch) for React components, enabling you to override the default implementation. Gatsby has a similar concept called [theme shadowing](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/). + +To gain a deeper understanding of this, you have to understand [how theme components are resolved](./advanced/client.md#theme-aliases). + +
+
+ );
+}
+```
+
+Some Component
+Some component implementation details
+