- -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
-
-
-
-
-## Themes design {#themes-design}
-
-While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.
-
-Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by a `src/theme` directory full of components.
-
-To summarize:
-
-- Themes share the same lifecycle methods with Plugins
-- Themes are run after all existing Plugins
-- Themes exist to add component aliases by extending the webpack config
-
-## Writing customized Docusaurus themes {#writing-customized-docusaurus-themes}
-
-A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:
-
-```shell {5-7}
-website
-├── package.json
-└── src
- ├── index.js
- └── theme
- ├── MyThemeComponent
- └── AnotherThemeComponent.js
-```
-
-There are two lifecycle methods that are essential to theme implementation:
-
-- [`getThemePath()`](./api/plugin-methods/extend-infrastructure.md#getThemePath)
-- [`getClientModules()`](./api/plugin-methods/lifecycle-apis.md#getClientModules)
-
-These lifecycle methods are not essential but recommended:
-
-- [`validateThemeConfig({themeConfig, validate})`](./api/plugin-methods/static-methods.md#validateThemeConfig)
-- [`validateOptions({options, validate})`](./api/plugin-methods/static-methods.md#validateOptions)
diff --git a/website/versioned_docs/version-2.0.0-beta.13/_partials/swizzleWarning.mdx b/website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.13/_partials/swizzleWarning.mdx
rename to website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md
new file mode 100644
index 0000000000..778b68eabd
--- /dev/null
+++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md
@@ -0,0 +1,28 @@
+---
+description: How Docusaurus works to build your app
+---
+
+# Architecture
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Zoom from '@site/src/components/Zoom';
+```
+
+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
+
+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
+
+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
+
+React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs.
+
+These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your site—anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading.
+
+In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app.
+
+## Escape hatches
+
+If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example:
+
+- Our [live codeblock](../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor), which runs in the browser's JS runtime
+- Our [themed image](../guides/markdown-features/markdown-features-assets.mdx#themed-images) that detects the user's color scheme to display different images
+- The JSON viewer of our debug panel which uses the `window` global for styling
+
+You may need to escape from SSR since static HTML can't display anything useful without knowing the client state.
+
+:::caution
+
+It is important for the first client-side render to produce the exact same DOM structure as server-side rendering, otherwise, React will correlate virtual DOM with the wrong DOM elements.
+
+Therefore, the naïve attempt of `if (typeof window !== 'undefined) {/* render something */}` won't work appropriately as a browser vs. server detection, because the first client render would instantly render different markup from the server-generated one.
+
+You can read more about this pitfall in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
+
+:::
+
+We provide several more reliable ways to escape SSR.
+
+### `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';
+
+Before footer
+
+
+
## 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.13/api/plugin-methods/README.md b/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
similarity index 93%
rename from website/versioned_docs/version-2.0.0-beta.13/api/plugin-methods/README.md
rename to website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
index 5b046d9a74..b764d726d5 100644
--- a/website/versioned_docs/version-2.0.0-beta.13/api/plugin-methods/README.md
+++ b/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
@@ -17,7 +17,7 @@ Every plugin is imported as a module. The module is expected to have the followi
## 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. |
@@ -56,8 +62,8 @@ Accepted fields:
| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. |
| `readingTime` | `ReadingTimeFunctionOption` | The default reading time | A callback to customize the reading time number displayed. |
| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file. |
-| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. |
-| `feedOptions.type` | 'rss' \| 'atom' \| 'all' (or array of multiple options) | **Required** | Type of feed to be generated. |
+| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. |
+| `feedOptions.type` | FeedType \| FeedType[] \| 'all' \| null | **Required** | Type of feed to be generated. Use `null` to disable generation. |
| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
| `feedOptions.description` | `string` | \`${siteConfig.title} Blog\` | Description of the feed. |
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
@@ -66,7 +72,7 @@ Accepted fields:
-```typescript
+```ts
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
@@ -90,29 +96,31 @@ type ReadingTimeFunctionOption = (params: {
frontMatter: BlogPostFrontMatter & RecordTip: 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 +77,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 +94,7 @@ type SidebarGenerator = (generatorArgs: { sidebarPosition?: number | undefined; }>; // all the docs of that version (unfiltered) numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin + isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus }) => Promise
'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' \| 'light' | `'light'` | The color theme of the footer component. |
-| `items` | `FooterItem[]` | `[]` | The link groups to be present. |
+| `links` | (Column \| FooterLink)[] | `[]` | The link groups to be present. |
+
+ `,
+ },
+ ],
+ // highlight-end
+ },
+};
+```
+
## Table of Contents {#table-of-contents}
You can adjust the default table of contents via `themeConfig.tableOfContents`.
@@ -805,20 +905,20 @@ module.exports = {
## Hooks {#hooks}
-### `useThemeContext` {#usethemecontext}
+### `useColorMode` {#use-color-mode}
-React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
+A React hook to access the color context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
-import useThemeContext from '@theme/hooks/useThemeContext';
+import {useColorMode} from '@docusaurus/theme-common';
const Example = () => {
// highlight-next-line
- const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
+ const {isDarkTheme, setLightTheme, setDarkTheme} = useColorMode();
return Dark mode is now {isDarkTheme ? 'on' : 'off'}
; }; @@ -826,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() { @@ -846,7 +946,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Translation files location {#translation-files-location} -- **Base path**: `website/i18n/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` -- ... +| 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.13/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.15/deployment.mdx
similarity index 91%
rename from website/versioned_docs/version-2.0.0-beta.13/deployment.mdx
rename to website/versioned_docs/version-2.0.0-beta.15/deployment.mdx
index 649151e36e..197934d35e 100644
--- a/website/versioned_docs/version-2.0.0-beta.13/deployment.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.15/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
@@ -70,8 +70,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 +124,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 +194,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 +230,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 +300,7 @@ cmd /C 'set "GIT_USER=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/{type}-{name}` -- `docusaurus-{type}-{name}`, - -where `type` 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` | - -+ {/* 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/).
:::
@@ -396,7 +421,7 @@ const MyComponent = () => {
};
```
-### `useBaseUrl` {#usebaseurl}
+### `useBaseUrl` {#useBaseUrl}
React hook to prepend your site `baseUrl` to a string.
@@ -446,11 +471,11 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
:::
-### `useBaseUrlUtils` {#usebaseurlutils}
+### `useBaseUrlUtils` {#useBaseUrlUtils}
Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
-- `withBaseUrl`: useful if you need to add base urls to multiple urls at once.
+- `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once.
```jsx
import React from 'react';
@@ -466,15 +491,15 @@ const Component = () => {
};
```
-### `useGlobalData` {#useglobaldata}
+### `useGlobalData` {#useGlobalData}
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
};
```
@@ -507,31 +535,34 @@ Inspect your site's global data at `./docusaurus/globalData.json`
:::
-### `usePluginData` {#useplugindata}
+### `usePluginData` {#usePluginData}
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
};
```
-### `useAllPluginInstancesData` {#useallplugininstancesdata}
+### `useAllPluginInstancesData` {#useAllPluginInstancesData}
Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
@@ -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 (
`
-- `/src/pages/foo.js` → `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.15/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md new file mode 100644 index 0000000000..426186a72b --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md @@ -0,0 +1,163 @@ +--- +id: introduction +title: Docs Introduction +sidebar_label: Introduction +slug: /docs-introduction +--- + +The docs feature provides users with a way to organize Markdown files in a hierarchical format. + +:::info + +Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options. + +::: + +## Document ID {#document-id} + +Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. + +For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. + +```bash +website # Root directory of your site +└── docs + ├── greeting.md + └── guide + └── hello.md +``` + +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`. + +```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`). + +```md +--- +id: part1 +slug: part1.html +--- + +Lorem ipsum +``` + +:::note + +It is possible to use: + +- absolute slugs: `slug: /mySlug`, `slug: /`... +- relative slugs: `slug: mySlug`, `slug: ./../mySlug`... + +::: + +## 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 front matter: + +```md +--- +id: my-home-doc +slug: / +--- + +Lorem ipsum +``` + +## Docs-only mode {#docs-only-mode} + +A freshly initialized Docusaurus site has the following structure: + +``` +example.com/ -> generated from `src/pages/index.js` + +example.com/docs/intro -> generated from `docs/intro.md` +example.com/docs/tutorial-basics/... -> generated from `docs/tutorial-basics/...` +... + +example.com/blog/2021/08/26/welcome -> generated from `blog/2021-08-26-welcome/index.md` +example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-mdx-blog-post.mdx` +... +``` + +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: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + '@docusaurus/preset-classic', + { + docs: { + /* docs plugin options */ + }, + blog: { + /* blog plugin options */ + }, + // ... + }, + ], +}; +``` + +To enter docs-only mode, change it to like this: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-next-line + routeBasePath: '/', // Serve the docs at the site's root + /* other docs plugin options */ + }, + // highlight-next-line + blog: false, // Optional: disable the blog plugin + // ... + }, + ], +}; +``` + +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: + +```md title="docs/intro.md" +--- +# highlight-next-line +slug: / +--- + +This page will be the home page when users visit https://example.com/. +``` + +:::caution + +If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route! + +::: + +Now, the site's structure will be like the following: + +``` +example.com/ -> generated from `docs/intro.md` +example.com/tutorial-basics/... -> generated from `docs/tutorial-basics/...` +... +``` + +:::tip + +There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode). + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-markdown-features.mdx similarity index 83% rename from website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-markdown-features.mdx rename to website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-markdown-features.mdx index eb5b7732a0..fe2660b212 100644 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-markdown-features.mdx +++ b/website/versioned_docs/version-2.0.0-beta.15/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} diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-multi-instance.mdx b/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-multi-instance.mdx similarity index 92% rename from website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-multi-instance.mdx rename to website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-multi-instance.mdx index 5962be207f..1ab708b4c9 100644 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-multi-instance.mdx +++ b/website/versioned_docs/version-2.0.0-beta.15/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 @@ -150,9 +150,9 @@ The default plugin instance will use these paths: The other plugin instances (with an `id` attribute) will use these paths: -- `website/
+
+
+## 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.
+
+:::
+
+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 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.
+
+```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()); +} +``` + +-
+
- 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.
+
+
+
+
+ );
+}
+```
+
+The types that are accepted are the same as above: `note`, `tip`, `danger`, `info`, `caution`. Optionally, you can specify an icon by passing a JSX element or a string, or a title:
+
+```jsx title="MyReactPage.jsx"
+Some information
++ 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})
+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.15/guides/markdown-features/markdown-features-math-equations.mdx b/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx new file mode 100644 index 0000000000..f329431be2 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx @@ -0,0 +1,193 @@ +--- +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 + +Please read [KaTeX](https://katex.org) documentation for more details. + +### 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 + +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
+
+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
+
+
{ThemeClassNamesCode
// remove source comments
.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g,'')
+ .replace(/^ *\n/gm,'')
.trim()}
```
-### CSS modules {#css-modules}
+
+
+### Styling your site with Infima {#styling-your-site-with-infima}
+
+`@docusaurus/preset-classic` uses [Infima](https://infima.dev/) as the underlying styling framework. Infima provides a flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://infima.dev/).
+
+When you scaffold your Docusaurus project with `create-docusaurus`, the website will be generated with basic Infima stylesheets and default styling. You can override Infima CSS variables globally.
+
+```css title="/src/css/custom.css"
+:root {
+ --ifm-color-primary: #25c2a0;
+ --ifm-code-font-size: 95%;
+}
+```
+
+Infima uses 7 shades of each color. We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color.
+
+Alternatively, use the following tool to generate the different shades for your website and copy the variables into `/src/css/custom.css`.
+
+