mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +02:00
chore: release Docusaurus 3.1.1 docs (#9794)
This commit is contained in:
Sébastien Lorber
GitHub
parent
3d8b70e0b3
commit
ed88097f63
100 changed files with 40 additions and 1 deletions
13
website/versioned_docs/version-3.1.1/migration/index.mdx
Normal file
13
website/versioned_docs/version-3.1.1/migration/index.mdx
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
slug: /migration
|
||||
---
|
||||
|
||||
# Upgrading Docusaurus
|
||||
|
||||
Docusaurus versioning is based on the `major.minor.patch` scheme and respects [**Semantic Versioning**](https://semver.org/).
|
||||
|
||||
**Breaking changes** are only released on major version upgrades, and thoroughly documented in the following upgrade guides.
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
<DocCardList />
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
slug: /migration/v2/automated
|
||||
---
|
||||
|
||||
# Automated migration
|
||||
|
||||
The migration CLI automatically migrates your v1 website to a v2 website.
|
||||
|
||||
:::info
|
||||
|
||||
Manual work is still required after using the migration CLI, as we can't automate a full migration
|
||||
|
||||
:::
|
||||
|
||||
The migration CLI migrates:
|
||||
|
||||
- Site configurations (from `siteConfig.js` to `docusaurus.config.js`)
|
||||
- `package.json`
|
||||
- `sidebars.json`
|
||||
- `/docs`
|
||||
- `/blog`
|
||||
- `/static`
|
||||
- `versioned_sidebar.json` and `/versioned_docs` if your site uses versioning
|
||||
|
||||
To use the migration CLI, follow these steps:
|
||||
|
||||
1. Before using the migration CLI, ensure that `/docs`, `/blog`, `/static`, `sidebars.json`, `siteConfig.js`, `package.json` follow the expected structure.
|
||||
|
||||
2. To migrate your v1 website, run the migration CLI with the appropriate filesystem paths:
|
||||
|
||||
```bash
|
||||
# migration command format
|
||||
npx @docusaurus/migrate migrate <v1 website directory> <desired v2 website directory>
|
||||
|
||||
# example
|
||||
npx @docusaurus/migrate migrate ./v1-website ./v2-website
|
||||
```
|
||||
|
||||
3. To view your new website locally, go into your v2 website's directory and start your development server.
|
||||
|
||||
```bash npm2yarn
|
||||
cd ./v2-website
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
:::danger
|
||||
|
||||
The migration CLI updates existing files. Be sure to have committed them first!
|
||||
|
||||
:::
|
||||
|
||||
#### Options {#options}
|
||||
|
||||
You can add option flags to the migration CLI to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.
|
||||
|
||||
| Name | Description |
|
||||
| -------- | ------------------------------------------------------ |
|
||||
| `--mdx` | Add this flag to convert Markdown to MDX automatically |
|
||||
| `--page` | Add this flag to migrate pages automatically |
|
||||
|
||||
```bash
|
||||
# example using options
|
||||
npx @docusaurus/migrate migrate --mdx --page ./v1-website ./v2-website
|
||||
```
|
||||
|
||||
:::danger
|
||||
|
||||
The migration of pages and MDX is still a work in progress.
|
||||
|
||||
We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the `--page` and `--mdx` options.
|
||||
|
||||
This way, you'd be able to easily inspect and fix the diff.
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,634 @@
|
|||
---
|
||||
slug: /migration/v2/manual
|
||||
toc_max_heading_level: 4
|
||||
---
|
||||
|
||||
# Manual migration
|
||||
|
||||
This manual migration process should be run after the [automated migration process](./migration-automated.mdx), to complete the missing parts, or debug issues in the migration CLI output.
|
||||
|
||||
## Project setup {#project-setup}
|
||||
|
||||
### `package.json` {#packagejson}
|
||||
|
||||
#### Scoped package names {#scoped-package-names}
|
||||
|
||||
In Docusaurus 2, we use scoped package names:
|
||||
|
||||
- `docusaurus` → `@docusaurus/core`
|
||||
|
||||
This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under `@docusaurus/`.
|
||||
|
||||
Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by `@docusaurus/preset-classic`. Therefore, we need to add this dependency as well:
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
dependencies: {
|
||||
- "docusaurus": "^1.x.x",
|
||||
+ "@docusaurus/core": "^2.0.0-beta.0",
|
||||
+ "@docusaurus/preset-classic": "^2.0.0-beta.0",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Please use the most recent Docusaurus 2 version, which you can check out [here](https://www.npmjs.com/package/@docusaurus/core) (using the `latest` tag).
|
||||
|
||||
:::
|
||||
|
||||
#### CLI commands {#cli-commands}
|
||||
|
||||
Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
|
||||
|
||||
The `"scripts"` section of your `package.json` should be updated as follows:
|
||||
|
||||
```json {3-6} title="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"start": "docusaurus start",
|
||||
"build": "docusaurus build",
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"deploy": "docusaurus deploy"
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A typical Docusaurus 2 `package.json` may look like this:
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"docusaurus": "docusaurus",
|
||||
"start": "docusaurus start",
|
||||
"build": "docusaurus build",
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"deploy": "docusaurus deploy",
|
||||
"serve": "docusaurus serve",
|
||||
"clear": "docusaurus clear"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "^2.0.0-beta.0",
|
||||
"@docusaurus/preset-classic": "^2.0.0-beta.0",
|
||||
"clsx": "^1.1.1",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
},
|
||||
"browserslist": {
|
||||
"production": [">0.5%", "not dead", "not op_mini all"],
|
||||
"development": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update references to the `build` directory {#update-references-to-the-build-directory}
|
||||
|
||||
In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`.
|
||||
|
||||
In Docusaurus 2, it is now moved to just `website/build`. Make sure that you update your deployment configuration to read the generated files from the correct `build` directory.
|
||||
|
||||
If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script.
|
||||
|
||||
### `.gitignore` {#gitignore}
|
||||
|
||||
The `.gitignore` in your `website` should contain:
|
||||
|
||||
```bash title=".gitignore"
|
||||
# dependencies
|
||||
/node_modules
|
||||
|
||||
# production
|
||||
/build
|
||||
|
||||
# generated files
|
||||
.docusaurus
|
||||
.cache-loader
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
```
|
||||
|
||||
### `README` {#readme}
|
||||
|
||||
The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/templates/shared/README.md).
|
||||
|
||||
## Site configurations {#site-configurations}
|
||||
|
||||
### `docusaurus.config.js` {#docusaurusconfigjs}
|
||||
|
||||
Rename `siteConfig.js` to `docusaurus.config.js`.
|
||||
|
||||
In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a `@docusaurus/preset-classic` preset which bundles most of the essential plugins present in Docusaurus 1.
|
||||
|
||||
Add the following preset configuration to your `docusaurus.config.js`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// Docs folder path relative to website dir.
|
||||
path: '../docs',
|
||||
// Sidebars file relative to website dir.
|
||||
sidebarPath: require.resolve('./sidebars.json'),
|
||||
},
|
||||
// ...
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
We recommend moving the `docs` folder into the `website` folder and that is also the default directory structure in v2. [Vercel](https://vercel.com) supports [Docusaurus project deployments out-of-the-box](https://github.com/vercel/vercel/tree/main/examples/docusaurus) if the `docs` directory is within the `website`. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one `website` directory.
|
||||
|
||||
If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the `/docs` folder to its original place, to avoid producing conflicts.
|
||||
|
||||
Refer to migration guide below for each field in `siteConfig.js`.
|
||||
|
||||
### Updated fields {#updated-fields}
|
||||
|
||||
#### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets` {#baseurl-tagline-title-url-favicon-organizationname-projectname-githubhost-scripts-stylesheets}
|
||||
|
||||
No actions needed, these configuration fields were not modified.
|
||||
|
||||
#### `colors` {#colors}
|
||||
|
||||
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`:
|
||||
|
||||
```js {7-9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
theme: {
|
||||
customCss: [require.resolve('./src/css/custom.css')],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Infima uses 7 shades of each color.
|
||||
|
||||
```css title="/src/css/custom.css"
|
||||
/**
|
||||
* You can override the default Infima variables here.
|
||||
* Note: this is not a complete list of --ifm- variables.
|
||||
*/
|
||||
:root {
|
||||
--ifm-color-primary: #25c2a0;
|
||||
--ifm-color-primary-dark: rgb(33, 175, 144);
|
||||
--ifm-color-primary-darker: rgb(31, 165, 136);
|
||||
--ifm-color-primary-darkest: rgb(26, 136, 112);
|
||||
--ifm-color-primary-light: rgb(70, 203, 174);
|
||||
--ifm-color-primary-lighter: rgb(102, 212, 189);
|
||||
--ifm-color-primary-lightest: rgb(146, 224, 208);
|
||||
}
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
import ColorGenerator from '@site/src/components/ColorGenerator';
|
||||
|
||||
<ColorGenerator />
|
||||
|
||||
#### `footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible` {#footericon-copyright-ogimage-twitterimage-docssidenavcollapsible}
|
||||
|
||||
Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
footer: {
|
||||
logo: {
|
||||
alt: 'Meta Open Source Logo',
|
||||
src: '/img/meta_oss_logo.png',
|
||||
href: 'https://opensource.facebook.com/',
|
||||
},
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here.
|
||||
},
|
||||
image: 'img/docusaurus.png',
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `headerIcon`, `headerLinks` {#headericon-headerlinks}
|
||||
|
||||
In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
|
||||
|
||||
```js title="siteConfig.js"
|
||||
headerIcon: 'img/docusaurus.svg',
|
||||
headerLinks: [
|
||||
{ doc: "doc1", label: "Getting Started" },
|
||||
{ page: "help", label: "Help" },
|
||||
{ href: "https://github.com/", label: "GitHub" },
|
||||
{ blog: true, label: "Blog" },
|
||||
],
|
||||
```
|
||||
|
||||
Now, these two fields are both handled by the theme:
|
||||
|
||||
```js {6-19} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
title: 'Docusaurus',
|
||||
logo: {
|
||||
alt: 'Docusaurus Logo',
|
||||
src: 'img/docusaurus.svg',
|
||||
},
|
||||
items: [
|
||||
{to: 'docs/doc1', label: 'Getting Started', position: 'left'},
|
||||
{to: 'help', label: 'Help', position: 'left'},
|
||||
{
|
||||
href: 'https://github.com/',
|
||||
label: 'GitHub',
|
||||
position: 'right',
|
||||
},
|
||||
{to: 'blog', label: 'Blog', position: 'left'},
|
||||
],
|
||||
},
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `algolia` {#algolia}
|
||||
|
||||
```js {4-8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
algolia: {
|
||||
apiKey: '47ecd3b21be71c5822571b9f59e52544',
|
||||
indexName: 'docusaurus-2',
|
||||
algoliaOptions: { //... },
|
||||
},
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Your Algolia DocSearch v1 config (found [here](https://github.com/algolia/docsearch-configs/blob/master/configs)) should be updated for Docusaurus v2 ([example](https://github.com/algolia/docsearch-configs/tree/master/configs/docusaurus-2.json)).
|
||||
|
||||
You can contact the DocSearch team (@shortcuts, @s-pace) for support. They can update it for you and trigger a recrawl of your site to restore the search (otherwise you will have to wait up to 24h for the next scheduled crawl)
|
||||
|
||||
:::
|
||||
|
||||
#### `blogSidebarCount` {#blogsidebarcount}
|
||||
|
||||
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
|
||||
|
||||
```js {8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
blog: {
|
||||
postsPerPage: 10,
|
||||
},
|
||||
// ...
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### `cname` {#cname}
|
||||
|
||||
Deprecated. Create a `CNAME` file in your `static` folder instead with your custom domain. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command.
|
||||
|
||||
#### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` {#customdocspath-docsurl-editurl-enableupdateby-enableupdatetime}
|
||||
|
||||
**BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory.
|
||||
|
||||
Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
|
||||
|
||||
```js {8-20} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// Equivalent to `customDocsPath`.
|
||||
path: 'docs',
|
||||
// Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
|
||||
// Equivalent to `docsUrl`.
|
||||
routeBasePath: 'docs',
|
||||
// Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
|
||||
remarkPlugins: [],
|
||||
rehypePlugins: [],
|
||||
// Equivalent to `enableUpdateBy`.
|
||||
showLastUpdateAuthor: true,
|
||||
// Equivalent to `enableUpdateTime`.
|
||||
showLastUpdateTime: true,
|
||||
},
|
||||
// ...
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### `gaTrackingId` {#gatrackingid}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// ...
|
||||
// highlight-start
|
||||
googleAnalytics: {
|
||||
trackingID: 'UA-141789564-1',
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### `gaGtag` {#gagtag}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// ...
|
||||
// highlight-start
|
||||
gtag: {
|
||||
trackingID: 'UA-141789564-1',
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Removed fields {#removed-fields}
|
||||
|
||||
The following fields are all deprecated, you may remove from your configuration file.
|
||||
|
||||
- `blogSidebarTitle`
|
||||
- `cleanUrl` - Clean URL is used by default now.
|
||||
- `defaultVersionShown` - Versioning is not ported yet. You'd be unable to migration to Docusaurus 2 if you are using versioning. Stay tuned.
|
||||
- `disableHeaderTitle`
|
||||
- `disableTitleTagline`
|
||||
- `docsSideNavCollapsible` is available at `docsPluginOptions.sidebarCollapsible`, and this is turned on by default now.
|
||||
- `facebookAppId`
|
||||
- `facebookComments`
|
||||
- `facebookPixelId`
|
||||
- `fonts`
|
||||
- `highlight` - We now use [Prism](https://prismjs.com/) instead of [highlight.js](https://highlightjs.org/).
|
||||
- `markdownOptions` - We use MDX in v2 instead of Remarkable. Your Markdown options have to be converted to Remark/Rehype plugins.
|
||||
- `markdownPlugins` - We use MDX in v2 instead of Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins.
|
||||
- `manifest`
|
||||
- `onPageNav` - This is turned on by default now.
|
||||
- `separateCss` - It can imported in the same manner as `custom.css` mentioned above.
|
||||
- `scrollToTop`
|
||||
- `scrollToTopOptions`
|
||||
- `translationRecruitingLink`
|
||||
- `twitter`
|
||||
- `twitterUsername`
|
||||
- `useEnglishUrl`
|
||||
- `users`
|
||||
- `usePrism` - We now use [Prism](https://prismjs.com/) instead of [highlight.js](https://highlightjs.org/)
|
||||
- `wrapPagesHTML`
|
||||
|
||||
We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
|
||||
|
||||
## Urls {#urls}
|
||||
|
||||
In v1, all pages were available with or without the `.html` extension.
|
||||
|
||||
For example, these 2 pages exist:
|
||||
|
||||
- [`https://v1.docusaurus.io/docs/en/installation`](https://v1.docusaurus.io/docs/en/installation)
|
||||
- [`https://v1.docusaurus.io/docs/en/installation.html`](https://v1.docusaurus.io/docs/en/installation.html)
|
||||
|
||||
If [`cleanUrl`](https://v1.docusaurus.io/docs/en/site-config#cleanurl-boolean) was:
|
||||
|
||||
- `true`: links would target `/installation`
|
||||
- `false`: links would target `/installation.html`
|
||||
|
||||
In v2, by default, the canonical page is `/installation`, and not `/installation.html`.
|
||||
|
||||
If you had `cleanUrl: false` in v1, it's possible that people published links to `/installation.html`.
|
||||
|
||||
For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.
|
||||
|
||||
As an escape hatch, you could use [@docusaurus/plugin-client-redirects](../../api/plugins/plugin-client-redirects.mdx) to create client-side redirects from `/installation.html` to `/installation`.
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-client-redirects',
|
||||
{
|
||||
fromExtensions: ['html'],
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
If you want to keep the `.html` extension as the canonical URL of a page, docs can declare a `slug: installation.html` front matter.
|
||||
|
||||
## Components {#components}
|
||||
|
||||
### Sidebar {#sidebar}
|
||||
|
||||
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../../guides/docs/sidebar/items.mdx) other than document.
|
||||
|
||||
You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`.
|
||||
|
||||
```diff title="sidebars.json"
|
||||
{
|
||||
- type: 'subcategory',
|
||||
+ type: 'category',
|
||||
label: 'My Example Subcategory',
|
||||
+ items: ['doc1'],
|
||||
- ids: ['doc1']
|
||||
},
|
||||
```
|
||||
|
||||
### Footer {#footer}
|
||||
|
||||
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../../swizzling.mdx) it:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-classic Footer
|
||||
```
|
||||
|
||||
This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, you may then edit this component for customization.
|
||||
|
||||
Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in `docusaurus.config.js` with `themeConfig.footer`:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
logo: {
|
||||
alt: 'Meta Open Source Logo',
|
||||
src: '/img/meta_oss_logo.png',
|
||||
href: 'https://opensource.facebook.com',
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Pages {#pages}
|
||||
|
||||
Please refer to [creating pages](guides/creating-pages.mdx) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead.
|
||||
|
||||
In Docusaurus v1, pages received the `siteConfig` object as props.
|
||||
|
||||
In Docusaurus v2, get the `siteConfig` object from `useDocusaurusContext` instead.
|
||||
|
||||
In v2, you have to apply the theme layout around each page. The Layout component takes metadata props.
|
||||
|
||||
`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://infima.dev/ to see what styles are available).
|
||||
|
||||
You can migrate CommonJS to ES6 imports/exports.
|
||||
|
||||
Here's a typical Docusaurus v2 page:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
import Link from '@docusaurus/Link';
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
const MyPage = () => {
|
||||
const {siteConfig} = useDocusaurusContext();
|
||||
return (
|
||||
<Layout title={siteConfig.title} description={siteConfig.tagline}>
|
||||
<div className="hero text--center">
|
||||
<div className="container ">
|
||||
<div className="padding-vert--md">
|
||||
<h1 className="hero__title">{siteConfig.title}</h1>
|
||||
<p className="hero__subtitle">{siteConfig.tagline}</p>
|
||||
</div>
|
||||
<div>
|
||||
<Link
|
||||
to="/docs/get-started"
|
||||
className="button button--lg button--outline button--primary">
|
||||
Get started
|
||||
</Link>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</Layout>
|
||||
);
|
||||
};
|
||||
|
||||
export default MyPage;
|
||||
```
|
||||
|
||||
The following code could be helpful for migration of various pages:
|
||||
|
||||
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/main/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/main/website/src/pages/index.js/)
|
||||
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/main/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
|
||||
|
||||
## Content {#content}
|
||||
|
||||
### Replace AUTOGENERATED_TABLE_OF_CONTENTS {#replace-autogenerated_table_of_contents}
|
||||
|
||||
This feature is replaced by [inline table of content](../../guides/markdown-features/markdown-features-toc.mdx#inline-table-of-contents)
|
||||
|
||||
### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
|
||||
|
||||
In Docusaurus 2, the Markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `<img>` and `<br>` which are valid in HTML would have to be explicitly closed now ( `<img/>` and `<br/>`). All tags in MDX documents have to be valid JSX.
|
||||
|
||||
Front matter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your front matter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` → `title: "Part 1: my part1 title"`.
|
||||
|
||||
**Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
|
||||
|
||||
### Language-specific code tabs {#language-specific-code-tabs}
|
||||
|
||||
Refer to the [multi-language support code blocks](../../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section.
|
||||
|
||||
### Front matter {#front-matter}
|
||||
|
||||
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
|
||||
|
||||
The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `authors` field.
|
||||
|
||||
## Deployment {#deployment}
|
||||
|
||||
The `CNAME` file used by GitHub Pages is not generated anymore, so be sure you have created it in `/static/CNAME` if you use a custom domain.
|
||||
|
||||
The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`. You may want to configure server-side redirects so that users' subscriptions keep working.
|
||||
|
||||
## Test your site {#test-your-site}
|
||||
|
||||
After migration, your folder structure should look like this:
|
||||
|
||||
```bash
|
||||
my-project
|
||||
├── docs
|
||||
└── website
|
||||
├── blog
|
||||
├── src
|
||||
│ ├── css
|
||||
│ │ └── custom.css
|
||||
│ └── pages
|
||||
│ └── index.js
|
||||
├── package.json
|
||||
├── sidebars.json
|
||||
├── .gitignore
|
||||
├── docusaurus.config.js
|
||||
└── static
|
||||
```
|
||||
|
||||
Start the development server and fix any errors:
|
||||
|
||||
```bash npm2yarn
|
||||
cd website
|
||||
npm start
|
||||
```
|
||||
|
||||
You can also try to build the site for production:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
|
@ -0,0 +1,105 @@
|
|||
---
|
||||
slug: /migration/v2
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
|
||||
|
||||
We try to make this as easy as possible, and provide a migration CLI.
|
||||
|
||||
## Main differences {#main-differences}
|
||||
|
||||
Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.
|
||||
|
||||
Docusaurus 2, rebuilt from the ground up, generates a single-page-application, using the full power of React in the browser. It allows for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n.
|
||||
|
||||
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.
|
||||
|
||||
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
|
||||
|
||||
## Docusaurus 1 structure {#docusaurus-1-structure}
|
||||
|
||||
Your Docusaurus 1 site should have the following structure:
|
||||
|
||||
```bash
|
||||
├── docs
|
||||
└── website
|
||||
├── blog
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
└── static
|
||||
```
|
||||
|
||||
## Docusaurus 2 structure {#docusaurus-2-structure}
|
||||
|
||||
After the migration, your Docusaurus 2 site could look like:
|
||||
|
||||
```sh
|
||||
├── docs
|
||||
└── website
|
||||
├── blog
|
||||
├── src
|
||||
│ ├── components
|
||||
│ ├── css
|
||||
│ └── pages
|
||||
├── static
|
||||
├── package.json
|
||||
├── sidebars.json
|
||||
├── docusaurus.config.js
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
This migration does not change the `/docs` folder location, but Docusaurus v2 sites generally have the `/docs` folder inside `/website`
|
||||
|
||||
You are free to put the `/docs` folder anywhere you want after having migrated to v2.
|
||||
|
||||
:::
|
||||
|
||||
## Migration process {#migration-process}
|
||||
|
||||
There are multiple things to migrate to obtain a fully functional Docusaurus 2 website:
|
||||
|
||||
- packages
|
||||
- CLI commands
|
||||
- site configuration
|
||||
- Markdown files
|
||||
- sidebars file
|
||||
- pages, components and CSS
|
||||
- versioned docs
|
||||
- i18n support 🚧
|
||||
|
||||
## Automated migration process {#automated-migration-process}
|
||||
|
||||
The [migration CLI](./migration-automated.mdx) will handle many things of the migration for you.
|
||||
|
||||
However, some parts can't easily be automated, and you will have to fallback to the manual process.
|
||||
|
||||
:::note
|
||||
|
||||
We recommend running the migration CLI, and complete the missing parts thanks to the manual migration process.
|
||||
|
||||
:::
|
||||
|
||||
## Manual migration process {#manual-migration-process}
|
||||
|
||||
Some parts of the migration can't be automated (particularly the pages), and you will have to migrate them manually.
|
||||
|
||||
The [manual migration guide](./migration-manual.mdx) will give you all the manual steps.
|
||||
|
||||
## Support {#support}
|
||||
|
||||
For any questions, you can ask in the [`#migration-v1-to-v2` Discord channel](https://discord.gg/C3P6CxMMxY).
|
||||
|
||||
Feel free to tag [@slorber](https://github.com/slorber) in any migration PRs if you would like us to have a look.
|
||||
|
||||
We also have volunteers willing to [help you migrate your v1 site](https://github.com/facebook/docusaurus/issues/1834).
|
||||
|
||||
## Example migration PRs {#example-migration-prs}
|
||||
|
||||
You might want to refer to our migration PRs for [Create React App](https://github.com/facebook/create-react-app/pull/7785) and [Flux](https://github.com/facebook/flux/pull/471) as examples of how a migration for a basic Docusaurus v1 site can be done.
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
---
|
||||
slug: /migration/v2/translated-sites
|
||||
---
|
||||
|
||||
# Translated sites
|
||||
|
||||
This page explains how migrate a translated Docusaurus v1 site to Docusaurus v2.
|
||||
|
||||
## i18n differences {#i18n-differences}
|
||||
|
||||
Docusaurus v2 i18n is conceptually quite similar to Docusaurus v1 i18n with a few differences.
|
||||
|
||||
It is not tightly coupled to Crowdin, and you can use Git or another SaaS instead.
|
||||
|
||||
### Different filesystem paths {#different-filesystem-paths}
|
||||
|
||||
On Docusaurus v2, localized content is generally found at `website/i18n/[locale]`.
|
||||
|
||||
Docusaurus v2 is modular based on a plugin system, and each plugin is responsible to manage its own translations.
|
||||
|
||||
Each plugin has its own i18n subfolder, like: `website/i18n/fr/docusaurus-plugin-content-blog`
|
||||
|
||||
### Updated translation APIs {#updated-translation-apis}
|
||||
|
||||
With Docusaurus v1, you translate your pages with `<translate>`:
|
||||
|
||||
```jsx
|
||||
const translate = require('../../server/translate.js').translate;
|
||||
|
||||
<h2>
|
||||
<translate desc="the header description">
|
||||
This header will be translated
|
||||
</translate>
|
||||
</h2>;
|
||||
```
|
||||
|
||||
On Docusaurus v2, you translate your pages with `<Translate>`
|
||||
|
||||
```jsx
|
||||
import Translate from '@docusaurus/Translate';
|
||||
|
||||
<h2>
|
||||
<Translate id="header.translation.id" description="the header description">
|
||||
This header will be translated
|
||||
</Translate>
|
||||
</h2>;
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
The `write-translations` CLI still works to extract translations from your code.
|
||||
|
||||
The code translations are now added to `i18n/[locale]/code.json` using Chrome i18n JSON format.
|
||||
|
||||
:::
|
||||
|
||||
### Stricter Markdown parser {#stricter-markdown-parser}
|
||||
|
||||
Docusaurus v2 is using [MDX](https://mdxjs.com/) to parse Markdown files.
|
||||
|
||||
MDX compiles Markdown files to React components, is stricter than the Docusaurus v1 parser, and will make your build fail on error instead of rendering some bad content.
|
||||
|
||||
Also, the HTML elements must be replaced by JSX elements.
|
||||
|
||||
This is particularly important for i18n because if your translations are not good on Crowdin and use invalid Markup, your v2 translated site might fail to build: you may need to do some translation cleanup to fix the errors.
|
||||
|
||||
## Migration strategies {#migration-strategies}
|
||||
|
||||
This section will help you figure out how to **keep your existing v1 translations after you migrate to v2**.
|
||||
|
||||
There are **multiple possible strategies** to migrate a Docusaurus v1 site using Crowdin, with different tradeoffs.
|
||||
|
||||
:::warning
|
||||
|
||||
This documentation is a best-effort to help you migrate, please help us improve it if you find a better way!
|
||||
|
||||
:::
|
||||
|
||||
Before all, we recommend to:
|
||||
|
||||
- Migrate your v1 Docusaurus site to v2 without the translations
|
||||
- Get familiar with the [new i18n system of Docusaurus v2](../../i18n/i18n-introduction.mdx) an
|
||||
- Make Crowdin work for your v2 site, using a new and untranslated Crowdin project and the [Crowdin tutorial](../../i18n/i18n-crowdin.mdx)
|
||||
|
||||
:::danger
|
||||
|
||||
Don't try to migrate without understanding both Crowdin and Docusaurus v2 i18n.
|
||||
|
||||
:::
|
||||
|
||||
### Create a new Crowdin project {#create-a-new-crowdin-project}
|
||||
|
||||
To avoid any **risk of breaking your v1 site in production**, one possible strategy is to duplicate the original v1 Crowdin project.
|
||||
|
||||
:::info
|
||||
|
||||
This strategy was used to [upgrade the Jest website](https://jestjs.io/blog/2021/03/09/jest-website-upgrade).
|
||||
|
||||
:::
|
||||
|
||||
Unfortunately, Crowdin does not have any "Duplicate/clone Project" feature, which makes things complicated.
|
||||
|
||||
- Download the translation memory of your original project in `.tmx` format (`https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm` > `View Records`)
|
||||
- Upload the translation memory to your new project (`https://crowdin.com/project/<NEW_PROJECT>/settings#tm` > `View Records`)
|
||||
- Reconfigure `crowdin.yml` for Docusaurus v2 according to the i18n docs
|
||||
- Upload the Docusaurus v2 source files with the Crowdin CLI to the new project
|
||||
- Mark sensitive strings like `id` or `slug` as "hidden string" on Crowdin
|
||||
- On the "Translations" tab, click on "Pre-Translation > via TM" (`https://crowdin.com/project/<NEW_PROJECT>/settings#translations`)
|
||||
- Try first with "100% match" (more content will be translated than "Perfect"), and pre-translate your sources
|
||||
- Download the Crowdin translations locally
|
||||
- Try to run/build your site and see if there are any errors
|
||||
|
||||
You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated MD files might be invalid for the MDX parser.
|
||||
|
||||
You will have to fix all the errors until your site builds. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`.
|
||||
|
||||
There is no ultimate guide we could write to fix these errors, but common errors are due to:
|
||||
|
||||
- Not marking enough strings as "hidden strings" in Crowdin, leading to pre-translation trying to translate these strings.
|
||||
- Having bad v1 translations, leading to invalid markup in v2: bad HTML elements inside translations and unclosed tags
|
||||
- Anything rejected by the MDX parser, like using HTML elements instead of JSX elements (use the [MDX playground](https://mdxjs.com/playground/) for debugging)
|
||||
|
||||
You might want to repeat this pre-translation process, eventually trying the "Perfect" option and limiting pre-translation only some languages/files.
|
||||
|
||||
:::tip
|
||||
|
||||
Use [`mdx-code-block`](../../i18n/i18n-crowdin.mdx#mdx-solutions) around problematic Markdown elements: Crowdin is less likely mess things up with code blocks.
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
You will likely notice that some things were translated on your old project, but are now untranslated in your new project.
|
||||
|
||||
The Crowdin Markdown parser is evolving other time and each Crowdin project has a different parser version, which can lead to pre-translation not being able to pre-translate all the strings.
|
||||
|
||||
This parser version is undocumented, and you will have to ask the Crowdin support to know your project's parser version and fix one specific version.
|
||||
|
||||
Using the same CLI version and parser version across the 2 Crowdin projects might give better results.
|
||||
|
||||
:::
|
||||
|
||||
:::danger
|
||||
|
||||
Crowdin has an "upload translations" feature, but in our experience it does not give very good results for Markdown
|
||||
|
||||
:::
|
||||
|
||||
### Use the existing Crowdin project {#use-the-existing-crowdin-project}
|
||||
|
||||
If you don't mind modifying your existing Crowdin project and risking to mess things up, it may be possible to use the Crowdin branch system.
|
||||
|
||||
:::warning
|
||||
|
||||
This workflow has not been tested in practice, please report us how good it is.
|
||||
|
||||
:::
|
||||
|
||||
This way, you wouldn't need to create a new Crowdin project, transfer the translation memory, apply pre-translations, and try to fix the pre-translations errors.
|
||||
|
||||
You could create a Crowdin branch for Docusaurus v2, where you upload the v2 sources, and merge the Crowdin branch to main once ready.
|
||||
|
||||
### Use Git instead of Crowdin {#use-git-instead-of-crowdin}
|
||||
|
||||
It is possible to migrate away of Crowdin, and add the translation files to Git instead.
|
||||
|
||||
Use the Crowdin CLI to download the v1 translated files, and put these translated files at the correct Docusaurus v2 filesystem location.
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
slug: /migration/v2/versioned-sites
|
||||
---
|
||||
|
||||
# Versioned sites
|
||||
|
||||
Read up https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
|
||||
|
||||
:::note
|
||||
|
||||
The versioned docs should normally be migrated correctly by the [migration CLI](./migration-automated.mdx)
|
||||
|
||||
:::
|
||||
|
||||
## Migrate your `versioned_docs` front matter {#migrate-your-versioned_docs-front-matter}
|
||||
|
||||
Unlike v1, The Markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual ID field. See scenario below for better explanation.
|
||||
|
||||
For example, if you have a `docs/hello.md`.
|
||||
|
||||
```md
|
||||
---
|
||||
id: hello
|
||||
title: Hello, World !
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
When you cut a new version 1.0.0, in Docusaurus v1, `website/versioned_docs/version-1.0.0/hello.md` looks like this:
|
||||
|
||||
```md
|
||||
---
|
||||
id: version-1.0.0-hello
|
||||
title: Hello, World !
|
||||
original_id: hello
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` looks like this (exactly same as original)
|
||||
|
||||
```md
|
||||
---
|
||||
id: hello
|
||||
title: Hello, World !
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The `id` front matter is no longer altered and will remain the same. Internally, it is set as `version-${version}/${id}`.
|
||||
|
||||
Essentially, here are the necessary changes in each versioned_docs file:
|
||||
|
||||
```diff {2-3,5}
|
||||
---
|
||||
- id: version-1.0.0-hello
|
||||
+ id: hello
|
||||
title: Hello, World !
|
||||
- original_id: hello
|
||||
---
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
## Migrate your `versioned_sidebars` {#migrate-your-versioned_sidebars}
|
||||
|
||||
- Refer to `versioned_docs` ID as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
|
||||
|
||||
Because in v1 there is a good chance someone created a new file with front matter ID `"version-${version}-${id}"` that can conflict with `versioned_docs` ID.
|
||||
|
||||
For example, Docusaurus 1 can't differentiate `docs/xxx.md`
|
||||
|
||||
```md
|
||||
---
|
||||
id: version-1.0.0-hello
|
||||
---
|
||||
|
||||
Another content
|
||||
```
|
||||
|
||||
vs `website/versioned_docs/version-1.0.0/hello.md`
|
||||
|
||||
```md
|
||||
---
|
||||
id: version-1.0.0-hello
|
||||
title: Hello, World !
|
||||
original_id: hello
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
Since we don't allow `/` in v1 & v2 for front matter, conflicts are less likely to occur.
|
||||
|
||||
So v1 users need to migrate their versioned_sidebars file
|
||||
|
||||
Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
||||
|
||||
```diff {2-3,5-6,9-10} title="versioned_sidebars/version-1.0.0-sidebars.json"
|
||||
{
|
||||
+ "version-1.0.0/docs": {
|
||||
- "version-1.0.0-docs": {
|
||||
"Test": [
|
||||
+ "version-1.0.0/foo/bar",
|
||||
- "version-1.0.0-foo/bar",
|
||||
],
|
||||
"Guides": [
|
||||
+ "version-1.0.0/hello",
|
||||
- "version-1.0.0-hello"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Populate your `versioned_sidebars` and `versioned_docs` {#populate-your-versioned_sidebars-and-versioned_docs}
|
||||
|
||||
In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality).
|
||||
|
||||
For example, if your `versions.json` looks like this in v1
|
||||
|
||||
```json title="versions.json"
|
||||
["1.1.0", "1.0.0"]
|
||||
```
|
||||
|
||||
Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`.
|
||||
|
||||
```bash
|
||||
website
|
||||
├── versioned_docs
|
||||
│ ├── version-1.1.0
|
||||
│ │ └── hello.md
|
||||
│ └── version-1.0.0
|
||||
│ ├── foo
|
||||
│ │ └── bar.md
|
||||
│ └── hello.md
|
||||
├── versioned_sidebars
|
||||
│ └── version-1.0.0-sidebars.json
|
||||
```
|
||||
|
||||
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right front matter and ID reference too).
|
||||
|
||||
```bash {3-5,12}
|
||||
website
|
||||
├── versioned_docs
|
||||
│ ├── version-1.1.0
|
||||
│ │ ├── foo
|
||||
│ │ │ └── bar.md
|
||||
│ │ └── hello.md
|
||||
│ └── version-1.0.0
|
||||
│ ├── foo
|
||||
│ │ └── bar.md
|
||||
│ └── hello.md
|
||||
├── versioned_sidebars
|
||||
│ ├── version-1.1.0-sidebars.json
|
||||
│ └── version-1.0.0-sidebars.json
|
||||
```
|
||||
|
||||
## Convert style attributes to style objects in MDX {#convert-style-attributes-to-style-objects-in-mdx}
|
||||
|
||||
Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:
|
||||
|
||||
```diff
|
||||
---
|
||||
id: demo
|
||||
title: Demo
|
||||
---
|
||||
|
||||
## Section
|
||||
|
||||
hello world
|
||||
|
||||
- pre style="background: black">zzz</pre>
|
||||
+ pre style={{background: 'black'}}>zzz</pre>
|
||||
```
|
||||
919
website/versioned_docs/version-3.1.1/migration/v3.mdx
Normal file
919
website/versioned_docs/version-3.1.1/migration/v3.mdx
Normal file
|
|
@ -0,0 +1,919 @@
|
|||
---
|
||||
slug: /migration/v3
|
||||
sidebar_label: To Docusaurus v3
|
||||
---
|
||||
|
||||
# Upgrading to Docusaurus v3
|
||||
|
||||
This documentation will help you upgrade your site from Docusaurus v2 to Docusaurus v3.
|
||||
|
||||
Docusaurus v3 is a new **major version**, including **breaking changes** requiring you to adjust your site accordingly. We will guide to during this process, and also mention a few optional recommendations.
|
||||
|
||||
This is not a full rewrite, and the breaking changes are relatively easy to handle. The simplest sites will eventually upgrade by simply updating their npm dependencies.
|
||||
|
||||
The main breaking change is the upgrade from MDX v1 to MDX v3. Read the [**MDX v2**](https://mdxjs.com/blog/v2/) and [**MDX v3**](https://mdxjs.com/blog/v3/) release notes for details. MDX will now compile your Markdown content **more strictly** and with **subtle differences**.
|
||||
|
||||
:::tip Before upgrading
|
||||
|
||||
Before upgrading, we recommend [**preparing your site for Docusaurus v3**](/blog/preparing-your-site-for-docusaurus-v3). There are changes that you can already **handle incrementally, under Docusaurus v2**. Doing so will help reduce the work needed to finally upgrade to Docusaurus v3.
|
||||
|
||||
For complex sites, we also recommend to set up [**visual regression tests**](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing), a good way to ensure your site stays visually identical. Docusaurus v3 mainly upgrades dependencies, and is not expected to produce any visual changes.
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
Check the release notes for [**Docusaurus v3.0.0**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0), and browse the pull-requests for additional useful information and the motivation behind each change mentioned here.
|
||||
|
||||
:::
|
||||
|
||||
## Upgrading Dependencies
|
||||
|
||||
Upgrading to Docusaurus v3 requires upgrading core Docusaurus dependencies (`@docusaurus/name`), but also other related packages.
|
||||
|
||||
Docusaurus v3 now uses the following dependencies:
|
||||
|
||||
- Node.js v18.0+
|
||||
- React v18.0+
|
||||
- MDX v3.0+
|
||||
- TypeScript v5.0+
|
||||
- prism-react-renderer v2.0+
|
||||
- react-live v4.0+
|
||||
- remark-emoji v4.0+
|
||||
- mermaid v10.4+
|
||||
|
||||
:::warning Upgrading community plugins
|
||||
|
||||
If your site uses third-party community plugins and themes, you might need to upgrade them.
|
||||
|
||||
Make sure those plugins are compatible with Docusaurus v3 before attempting an upgrade.
|
||||
|
||||
:::
|
||||
|
||||
A typical `package.json` dependency upgrade example:
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"dependencies": {
|
||||
// upgrade to Docusaurus v3
|
||||
- "@docusaurus/core": "2.4.3",
|
||||
- "@docusaurus/preset-classic": "2.4.3",
|
||||
+ "@docusaurus/core": "3.0.0",
|
||||
+ "@docusaurus/preset-classic": "3.0.0",
|
||||
// upgrade to MDX v2
|
||||
- "@mdx-js/react": "^1.6.22",
|
||||
+ "@mdx-js/react": "^3.0.0",
|
||||
// upgrade to prism-react-renderer v2.0+
|
||||
- "prism-react-renderer": "^1.3.5",
|
||||
+ "prism-react-renderer": "^2.1.0",
|
||||
// upgrade to React v18.0+
|
||||
- "react": "^17.0.2",
|
||||
- "react-dom": "^17.0.2"
|
||||
+ "react": "^18.2.0",
|
||||
+ "react-dom": "^18.2.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
// upgrade Docusaurus dev dependencies to v3
|
||||
- "@docusaurus/module-type-aliases": "2.4.3",
|
||||
- "@docusaurus/types": "2.4.3"
|
||||
+ "@docusaurus/module-type-aliases": "3.0.0",
|
||||
+ "@docusaurus/types": "3.0.0"
|
||||
}
|
||||
"engines": {
|
||||
// require Node.js 18.0+
|
||||
- "node": ">=16.14"
|
||||
+ "node": ">=18.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For TypeScript users:
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"devDependencies": {
|
||||
// swap the external TypeScript config package for the new official one
|
||||
- "@tsconfig/docusaurus": "^1.0.7",
|
||||
+ "@docusaurus/tsconfig": "3.0.0",
|
||||
// upgrade React types to v18.0+
|
||||
- "@types/react": "^17.0.69",
|
||||
+ "@types/react": "^18.2.29",
|
||||
// upgrade TypeScript to v5.0+
|
||||
- "typescript": "~4.7.4"
|
||||
+ "typescript": "~5.2.2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Upgrading MDX
|
||||
|
||||
MDX is a major dependency of Docusaurus responsible for compiling your `.md` and `.mdx` files to React components.
|
||||
|
||||
The transition from MDX v1 to MDX v3 is the **main challenge** to the adoption of Docusaurus v3. Most breaking changes come from MDX v2, and MDX v3 is a relatively small release.
|
||||
|
||||
Some documents that compiled successfully under Docusaurus v2 might now **fail to compile** under Docusaurus v3.
|
||||
|
||||
:::tip Find problematic content ahead of time
|
||||
|
||||
Run [`npx docusaurus-mdx-checker`](https://github.com/slorber/docusaurus-mdx-checker) on your site to get a list of files that will now fail to compile under Docusaurus v3.
|
||||
|
||||
This command is also a good way to estimate the amount of work to be done to make your content compatible. Remember most of this work can be executed ahead of the upgrade by [preparing your content for Docusaurus v3](/blog/preparing-your-site-for-docusaurus-v3).
|
||||
|
||||
:::
|
||||
|
||||
Other documents might also **render differently**.
|
||||
|
||||
:::tip Use visual regression tests
|
||||
|
||||
For large sites where a manual review of all pages is complicated, we recommend you to setup [visual regression tests](https://docusaurus.io/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing).
|
||||
|
||||
:::
|
||||
|
||||
Upgrading MDX comes with all the breaking changes documented on the [MDX v2](https://mdxjs.com/blog/v2/) and [MDX v3](https://mdxjs.com/blog/v3/) release blog posts. Most breaking changes come from MDX v2. The [MDX v2 migration guide](https://mdxjs.com/migrating/v2/) has a section on how to [update MDX files](https://mdxjs.com/migrating/v2/#update-mdx-files) that will be particularly relevant to us. Also make sure to read the [Troubleshooting MDX](https://mdxjs.com/docs/troubleshooting-mdx/) page that can help you interpret common MDX error messages.
|
||||
|
||||
Make sure to also read our updated [**MDX and React**](../guides/markdown-features/markdown-features-react.mdx) documentation page.
|
||||
|
||||
### Using the MDX playground
|
||||
|
||||
The MDX playground is your new best friend. It permits to understand how your content is **compiled to React components**, and troubleshoot compilation or rendering issues in isolation.
|
||||
|
||||
- [MDX playground - current version](https://mdxjs.com/playground/)
|
||||
- [MDX playground - v1](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/)
|
||||
|
||||
<details>
|
||||
<summary>Configuring the MDX playground options for Docusaurus</summary>
|
||||
|
||||
To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the [MDX playground](https://mdxjs.com/playground/):
|
||||
|
||||
- Use `MDX`
|
||||
- Use `remark-gfm`
|
||||
- Use `remark-directive`
|
||||
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v2.
|
||||
|
||||
:::tip Making your content future-proof
|
||||
|
||||
The goal will be to refactor your problematic content so that it **works fine with both versions of MDX**. This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box.
|
||||
|
||||
:::
|
||||
|
||||
### Using the MDX checker CLI
|
||||
|
||||
We provide a [docusaurus-mdx-checker](https://github.com/slorber/docusaurus-mdx-checker) CLI that permits to easily spot problematic content. Run this command on your site to obtain a list of files that will fail to compile under MDX v3.
|
||||
|
||||
```bash
|
||||
npx docusaurus-mdx-checker
|
||||
```
|
||||
|
||||
For each compilation issue, the CLI will log the file path and a line number to look at.
|
||||
|
||||
|
||||
|
||||
:::tip
|
||||
|
||||
Use this CLI to estimate of how much work will be required to make your content compatible with MDX v3.
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
This CLI is a best effort, and will **only report compilation errors**.
|
||||
|
||||
It will not report subtle compilation changes that do not produce errors but can affect how your content is displayed. To catch these problems, we recommend using [visual regression tests](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing).
|
||||
|
||||
:::
|
||||
|
||||
### Common MDX problems
|
||||
|
||||
Docusaurus cannot document exhaustively all the changes coming with MDX. That's the responsibility of the [MDX v2](https://mdxjs.com/migrating/v2/) and [MDX v3](https://mdxjs.com/migrating/v3/) migration guides.
|
||||
|
||||
However, by upgrading a few Docusaurus sites, we noticed that most of the issues come down to only a few cases that we have documented for you.
|
||||
|
||||
#### Bad usage of `{`
|
||||
|
||||
The `{` character is used for opening [JavaScript expressions](https://mdxjs.com/docs/what-is-mdx/#expressions). MDX will now fail if what you put inside `{expression}` is not a valid expression.
|
||||
|
||||
```md title="example.md"
|
||||
The object shape looks like {username: string, age: number}
|
||||
```
|
||||
|
||||
:::danger Error message
|
||||
|
||||
> Could not parse expression with acorn: Unexpected content after expression
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Available options to fix this error:
|
||||
|
||||
- Use inline code: `{username: string, age: number}`
|
||||
- Use the HTML code: `{`
|
||||
- Escape it: `\{`
|
||||
|
||||
:::
|
||||
|
||||
#### Bad usage of `<`
|
||||
|
||||
The `<` character is used for opening [JSX tags](https://mdxjs.com/docs/what-is-mdx/#jsx). MDX will now fail if it thinks your JSX is invalid.
|
||||
|
||||
```md title="example.md"
|
||||
Use Android version <5
|
||||
|
||||
You can use a generic type like Array<T>
|
||||
|
||||
Follow the template "Road to <YOUR_MINOR_VERSION>"
|
||||
```
|
||||
|
||||
:::danger Error messages
|
||||
|
||||
> Unexpected character `5` (U+0035) before name, expected a character that can start a name, such as a letter, `$`, or `_`
|
||||
|
||||
> Expected a closing tag for `<T>` (1:6-1:9) before the end of `paragraph` end-tag-mismatch mdast-util-mdx-jsx
|
||||
|
||||
> Expected a closing tag for `<YOUR_MINOR_VERSION>` (134:19-134:39) before the end of `paragraph`
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Available options to fix this error:
|
||||
|
||||
- Use inline code: `Array<T>`
|
||||
- Use the HTML code: `<` or `<`
|
||||
- Escape it: `\<`
|
||||
|
||||
:::
|
||||
|
||||
#### Bad usage of GFM Autolink
|
||||
|
||||
Docusaurus supports [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/), but [autolink](https://github.github.com/gfm/#autolinks) using the `<link>` syntax is not supported anymore by MDX.
|
||||
|
||||
```md title="example.md"
|
||||
<sebastien@thisweekinreact.com>
|
||||
|
||||
<http://localhost:3000>
|
||||
```
|
||||
|
||||
:::danger Error messages
|
||||
|
||||
> Unexpected character `@` (U+0040) in name, expected a name character such as letters, digits, `$`, or `_`; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use `[text](url)`)
|
||||
|
||||
> Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Use regular Markdown links, or remove the `<` and `>`. MDX and GFM are able to autolink literals already.
|
||||
|
||||
{/* prettier-ignore */}
|
||||
```md title="example.md"
|
||||
sebastien@thisweekinreact.com
|
||||
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)
|
||||
|
||||
http://localhost:3000
|
||||
[http://localhost:3000](http://localhost:3000)
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Lower-case MDXComponent mapping
|
||||
|
||||
For users providing a [custom `MDXComponent`mapping](../guides/markdown-features/markdown-features-react.mdx#mdx-component-scope), components are now "sandboxed":
|
||||
|
||||
- a `MDXComponent` mapping for `h1` only gets used for `# hi` but not for `<h1>hi</h1>`
|
||||
- a **lower-cased** custom element name will not be substituted by its respective `MDXComponent` component anymore
|
||||
|
||||
:::danger visual difference
|
||||
|
||||
Your [`MDXComponent` component mapping](../guides/markdown-features/markdown-features-react.mdx#mdx-component-scope) might not be applied as before, and your custom components might no longer be used.
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
For native Markdown elements, you can keep using **lower-case**: `p`, `h1`, `img`, `a`...
|
||||
|
||||
For any other element, **use upper-case names**.
|
||||
|
||||
```diff title="src/theme/MDXComponents.js"
|
||||
import MDXComponents from '@theme-original/MDXComponents';
|
||||
|
||||
export default {
|
||||
...MDXComponents,
|
||||
p: (props) => <p {...props} className="my-paragraph"/>
|
||||
- myElement: (props) => <div {...props} className="my-class" />,
|
||||
+ MyElement: (props) => <div {...props} className="my-class" />,
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Unintended extra paragraphs
|
||||
|
||||
In MDX v3, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected `<p>` tags.
|
||||
|
||||
:::danger visual difference
|
||||
|
||||
See how this content is rendered differently by MDX v1 and v3.
|
||||
|
||||
```md title="example.md"
|
||||
<div>Some **Markdown** content</div>
|
||||
<div>
|
||||
Some **Markdown** content
|
||||
</div>
|
||||
```
|
||||
|
||||
{/* prettier-ignore */}
|
||||
```html title="MDX v1 output"
|
||||
<div>Some **Markdown** content</div>
|
||||
<div>Some **Markdown** content</div>
|
||||
```
|
||||
|
||||
{/* prettier-ignore */}
|
||||
```html title="MDX v3 output"
|
||||
<div>Some <strong>Markdown</strong> content</div>
|
||||
<div><p>Some <strong>Markdown</strong> content</p></div>
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
If you don't want an extra `<p>` tag, refactor content on a case by case basis to use a single-line JSX tag.
|
||||
|
||||
```diff
|
||||
<figure>
|
||||
<img src="/img/myImage.png" alt="My alt" />
|
||||
- <figcaption>
|
||||
- My image caption
|
||||
- </figcaption>
|
||||
+ <figcaption>My image caption</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Unintended usage of directives
|
||||
|
||||
Docusaurus v3 now uses [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.
|
||||
|
||||
```md title="example.md"
|
||||
This is a :textDirective
|
||||
|
||||
::leafDirective
|
||||
|
||||
:::containerDirective
|
||||
|
||||
Container directive content
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
:::danger Visual change
|
||||
|
||||
Directives are parsed with the purpose of being handled by other Remark plugins. Unhandled directives will be ignored, and won't be rendered back in their original form.
|
||||
|
||||
```md title="example.md"
|
||||
The AWS re:Invent conf is great
|
||||
```
|
||||
|
||||
Due to `:Invent` being parsed as a text directive, this will now be rendered as:
|
||||
|
||||
```
|
||||
The AWS re
|
||||
conf is great
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
- Use the HTML code: `:`
|
||||
- Add a space after `:` (if it makes sense): `: text`
|
||||
- Escape it: `\:`
|
||||
|
||||
:::
|
||||
|
||||
#### Unsupported indented code blocks
|
||||
|
||||
MDX does not transform indented text as code blocks anymore.
|
||||
|
||||
```md title="example.md"
|
||||
console.log("hello");
|
||||
```
|
||||
|
||||
:::danger Visual change
|
||||
|
||||
The upgrade does not generally produce new MDX compilation errors, but can lead to content being rendered in an unexpected way because there isn't a code block anymore.
|
||||
|
||||
:::
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Use the regular code block syntax instead of indentation:
|
||||
|
||||
````md title="example.md"
|
||||
```js
|
||||
console.log('hello');
|
||||
```
|
||||
````
|
||||
|
||||
:::
|
||||
|
||||
### MDX plugins
|
||||
|
||||
All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and do not support [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) anymore.
|
||||
|
||||
In practice this means that you can't do `require("remark-plugin")` anymore.
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Docusaurus v3 now supports [**ES Modules**](https://flaviocopes.com/es-modules/) configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
import remarkPlugin from 'remark-plugin';
|
||||
|
||||
export default {
|
||||
title: 'Docusaurus',
|
||||
/* site config using remark plugins here */
|
||||
};
|
||||
```
|
||||
|
||||
If you want to keep using CommonJS modules, you can use dynamic imports as a workaround that enables you to import ES modules inside a CommonJS module. Fortunately, the [Docusaurus config supports the usage of an async function](/docs/configuration#syntax-to-declare-docusaurus-config) to let you do so.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = async function () {
|
||||
const myPlugin = (await import('remark-plugin')).default;
|
||||
return {
|
||||
// site config...
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
:::info For plugin authors
|
||||
|
||||
If you created custom Remark or Rehype plugins, you may need to refactor those, or eventually rewrite them completely, due to how the new AST is structured. We have created a [dedicated support discussion](https://github.com/facebook/docusaurus/discussions/9337) to help plugin authors upgrade their code.
|
||||
|
||||
:::
|
||||
|
||||
## Other Breaking Changes
|
||||
|
||||
Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.
|
||||
|
||||
### Node.js v18.0
|
||||
|
||||
Node.js 16 [reached End-of-Life](https://nodejs.org/en/blog/announcements/nodejs16-eol), and Docusaurus v3 now requires **Node.js >= 18.0**.
|
||||
|
||||
:::tip How to upgrade
|
||||
|
||||
Install Node.js 18.0+ on your computer.
|
||||
|
||||
Eventually, configure your continuous integration, CDN or host to use this new Node.js version.
|
||||
|
||||
You can also update your site `package.json` to prevent usage of an older unsupported version:
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"engines": {
|
||||
- "node": ">=16.14"
|
||||
+ "node": ">=18.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.
|
||||
|
||||
:::
|
||||
|
||||
### React v18.0+
|
||||
|
||||
Docusaurus v3 now requires **React >= 18.0**.
|
||||
|
||||
React 18 comes with its own breaking changes that should be relatively easy to handle, depending on the amount of custom React code you created for your site. The official themes and plugins are compatible with React 18.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Read the official [React v18.0](https://react.dev/blog/2022/03/29/react-v18) and [How to Upgrade to React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide), and look at your own React code to figure out which components might be affected this upgrade.
|
||||
|
||||
We recommend to particularly look for:
|
||||
|
||||
- Automatic batching for stateful components
|
||||
- New React hydration errors reported to the console
|
||||
|
||||
:::
|
||||
|
||||
:::danger Experimental support for React 18 features
|
||||
|
||||
React 18 comes with new features:
|
||||
|
||||
- `<Suspense>`
|
||||
- `React.lazy()`
|
||||
- `startTransition`
|
||||
|
||||
Their Docusaurus support is considered as experimental. We might have to adjust the integration in the future, leading to a different runtime behavior.
|
||||
|
||||
:::
|
||||
|
||||
### Prism-React-Renderer v2.0+
|
||||
|
||||
Docusaurus v3 upgrades [`prism-react-renderer`](https://github.com/FormidableLabs/prism-react-renderer) to v2.0+. This library is used for code block syntax highlighting.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
This is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. The [`prism-react-renderer` v2 release notes](https://github.com/FormidableLabs/prism-react-renderer/releases/tag/prism-react-renderer%402.0.0) are not super exhaustive, but there are 3 major changes to be aware of for Docusaurus users.
|
||||
|
||||
The dependency should be upgraded:
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"dependencies": {
|
||||
- "prism-react-renderer": "^1.3.5",
|
||||
+ "prism-react-renderer": "^2.1.0",
|
||||
}
|
||||
```
|
||||
|
||||
The API to import themes in your Docusaurus config file has been updated:
|
||||
|
||||
```diff title="docusaurus.config.js"
|
||||
- const lightTheme = require('prism-react-renderer/themes/github');
|
||||
- const darkTheme = require('prism-react-renderer/themes/dracula');
|
||||
+ const {themes} = require('prism-react-renderer');
|
||||
+ const lightTheme = themes.github;
|
||||
+ const darkTheme = themes.dracula;
|
||||
```
|
||||
|
||||
Previously, `react-prism-render` v1 [included more languages by default](https://github.com/FormidableLabs/prism-react-renderer/blob/v1.3.5/src/vendor/prism/includeLangs.js). From v2.0+, [less languages are included by default](https://github.com/FormidableLabs/prism-react-renderer/blob/prism-react-renderer%402.1.0/packages/generate-prism-languages/index.ts#L9). You may need to add extra languages to your Docusaurus config:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
const siteConfig = {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
// highlight-next-line
|
||||
additionalLanguages: ['bash', 'diff', 'json'],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### React-Live v4.0+
|
||||
|
||||
For users of the `@docusaurus/theme-live-codeblock` package, Docusaurus v3 upgrades [`react-live`](https://github.com/FormidableLabs/react-live) to v4.0+.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
In theory, you have nothing to do, and your existing interactive code blocks should keep working as before.
|
||||
|
||||
However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the [v3](https://github.com/FormidableLabs/react-live/releases/tag/v3.0.0) and [v4](https://github.com/FormidableLabs/react-live/releases/tag/v4.0.0) changelogs in case of problems.
|
||||
|
||||
:::
|
||||
|
||||
### remark-emoji v4.0+
|
||||
|
||||
Docusaurus v3 upgrades [`remark-emoji`](https://github.com/rhysd/remark-emoji) to v4.0+. This library is to support `:emoji:` shortcuts in Markdown.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Most Docusaurus users have nothing to do. Users of emoji shortcodes should read the [changelog](https://github.com/rhysd/remark-emoji/blob/master/CHANGELOG.md) and double-check their emojis keep rendering as expected.
|
||||
|
||||
> **Breaking Change** Update [node-emoji](https://www.npmjs.com/package/node-emoji) from v1 to v2. This change introduces support for many new emojis and removes old emoji short codes which are no longer valid on GitHub.
|
||||
|
||||
:::
|
||||
|
||||
### Mermaid v10.4+
|
||||
|
||||
For users of the `@docusaurus/theme-mermaid` package, Docusaurus v3 upgrades [`mermaid`](https://github.com/mermaid-js/mermaid) to v10.4+.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
In theory, you have nothing to do, and your existing diagrams should keep working as before.
|
||||
|
||||
However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the [v10](https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0) changelog in case of problem.
|
||||
|
||||
:::
|
||||
|
||||
### TypeScript v5.0+
|
||||
|
||||
Docusaurus v3 now requires **TypeScript >= 5.0**.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Upgrade your dependencies to use TypeScript 5+
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"devDependencies": {
|
||||
- "typescript": "~4.7.4"
|
||||
+ "typescript": "~5.2.2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### TypeScript base config
|
||||
|
||||
The official Docusaurus TypeScript config has been re-internalized from the external package [`@tsconfig/docusaurus`](https://www.npmjs.com/package/@tsconfig/docusaurus) to our new monorepo package [`@docusaurus/tsconfig`](https://www.npmjs.com/package/@docusaurus/tsconfig).
|
||||
|
||||
This new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Swap the external TypeScript config package for the new official one
|
||||
|
||||
```diff title="package.json"
|
||||
{
|
||||
"devDependencies": {
|
||||
- "@tsconfig/docusaurus": "^1.0.7",
|
||||
+ "@docusaurus/tsconfig": "3.0.0",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use it in your `tsconfig.json` file:
|
||||
|
||||
```diff title="tsconfig.json"
|
||||
{
|
||||
- "extends": "@tsconfig/docusaurus/tsconfig.json",
|
||||
+ "extends": "@docusaurus/tsconfig",
|
||||
"compilerOptions": {
|
||||
"baseUrl": "."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### New Config Loader
|
||||
|
||||
Docusaurus v3 changes its internal config loading library from [`import-fresh`](https://github.com/sindresorhus/import-fresh) to [`jiti`](https://github.com/unjs/jiti). It is responsible for loading files such as `docusaurus.config.js` or `sidebars.js`, and Docusaurus plugins.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
In theory, you have nothing to do, and your existing config files should keep working as before.
|
||||
|
||||
However, this is a major dependency swap and subtle behavior changes could occur.
|
||||
|
||||
:::
|
||||
|
||||
### Admonition Warning
|
||||
|
||||
For historical reasons, we support an undocumented admonition `:::warning` that renders with a red color.
|
||||
|
||||
:::danger Warning
|
||||
|
||||
This is a Docusaurus v2 `:::warning` admonition.
|
||||
|
||||
:::
|
||||
|
||||
However, the color and icon have always been wrong. Docusaurus v3 re-introduces `:::warning` admonition officially, documents it, and fix the color and icon.
|
||||
|
||||
:::warning
|
||||
|
||||
This is a Docusaurus v3 `:::warning` admonition.
|
||||
|
||||
:::
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
If you previously used the undocumented `:::warning` admonition, make sure to verify for each usage if yellow is now an appropriate color. If you want to keep the red color, use `:::danger` instead.
|
||||
|
||||
Docusaurus v3 also [deprecated the `:::caution`](https://github.com/facebook/docusaurus/pull/9308) admonition. Please refactor `:::caution` (yellow) to either `:::warning` (yellow) or `:::danger` (red).
|
||||
|
||||
:::
|
||||
|
||||
### Versioned Sidebars
|
||||
|
||||
This breaking change will only affect **Docusaurus v2 early adopters** who versioned their docs before `v2.0.0-beta.10` (December 2021).
|
||||
|
||||
When creating version `v1.0.0`, the sidebar file contained a prefix `version-v1.0.0/` that [Docusaurus v3 does not support anymore](https://github.com/facebook/docusaurus/pull/9310).
|
||||
|
||||
```json title="versioned_sidebars/version-v1.0.0-sidebars.json"
|
||||
{
|
||||
"version-v1.0.0/docs": [
|
||||
"version-v1.0.0/introduction",
|
||||
"version-v1.0.0/prerequisites"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Remove the useless versioned prefix from your versioned sidebars.
|
||||
|
||||
```json title="versioned_sidebars/version-v1.0.0-sidebars.json"
|
||||
{
|
||||
"docs": ["introduction", "prerequisites"]
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Blog Feed Limit
|
||||
|
||||
The `@docusaurus/plugin-content-blog` now limits the RSS feed to the last 20 entries by default. For large Docusaurus blogs, this is a more sensible default value to avoid an increasingly large RSS file.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
In case you don't like this new default behavior, you can revert to the former "unlimited feed" behavior with the new `limit: false` feed option:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
const blogOptions = {
|
||||
feedOptions: {
|
||||
// highlight-next-line
|
||||
limit: false,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Docs Theme Refactoring
|
||||
|
||||
For users that swizzled docs-related theme components (like `@theme/DocPage`), these components have been significantly refactor to make it easier to customize.
|
||||
|
||||
Technically, **this is not a breaking change** because these components are **flagged as unsafe to swizzle**, however many Docusaurus sites ejected docs-related components, and will be interested to know their customizations might break Docusaurus.
|
||||
|
||||
:::info How to upgrade
|
||||
|
||||
Delete all your swizzled components, re-swizzle them, and re-apply your customizations on top of the newly updated components.
|
||||
|
||||
Alternatively, you can look at the [pull-request notes](https://github.com/facebook/docusaurus/pull/7966) to understand the new theme component tree structure, and eventually try to patch your swizzled components manually.
|
||||
|
||||
:::
|
||||
|
||||
## Optional Changes
|
||||
|
||||
Some changes are not mandatory, but remain useful to be aware of to plainly leverage Docusaurus v3.
|
||||
|
||||
### Automatic JSX runtime
|
||||
|
||||
Docusaurus v3 now uses the React 18 ["automatic" JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
|
||||
|
||||
It is not needed anymore to import React in JSX files that do not use any React API.
|
||||
|
||||
```diff title="src/components/MyComponent.js"
|
||||
- import React from 'react';
|
||||
|
||||
export default function MyComponent() {
|
||||
return <div>Hello</div>;
|
||||
}
|
||||
```
|
||||
|
||||
### ESM and TypeScript Configs
|
||||
|
||||
Docusaurus v3 supports ESM and TypeScript config files, and it might be a good idea to adopt those new options.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
export default {
|
||||
title: 'Docusaurus',
|
||||
url: 'https://docusaurus.io',
|
||||
// your site config ...
|
||||
};
|
||||
```
|
||||
|
||||
```ts title="docusaurus.config.ts"
|
||||
import type {Config} from '@docusaurus/types';
|
||||
import type * as Preset from '@docusaurus/preset-classic';
|
||||
|
||||
const config: Config = {
|
||||
title: 'My Site',
|
||||
favicon: 'img/favicon.ico',
|
||||
presets: [
|
||||
[
|
||||
'classic',
|
||||
{
|
||||
/* Your preset config here */
|
||||
} satisfies Preset.Options,
|
||||
],
|
||||
],
|
||||
|
||||
themeConfig: {
|
||||
/* Your theme config here */
|
||||
} satisfies Preset.ThemeConfig,
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
### Using the `.mdx` extension
|
||||
|
||||
We recommend using the `.mdx` extension whenever you use JSX, `import`, or `export` (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.).
|
||||
|
||||
In future versions of Docusaurus, `.md` files will be parsed as standard [CommonMark](https://commonmark.org/), which does not support these features. In Docusaurus v3, `.md` files keep being compiled as MDX files, but it will be possible to [opt-in for CommonMark](https://github.com/facebook/docusaurus/issues/3018).
|
||||
|
||||
### Upgrading math packages
|
||||
|
||||
If you use Docusaurus to render [Math Equations](../guides/markdown-features/markdown-features-math-equations.mdx), you should upgrade the MDX plugins.
|
||||
|
||||
Make sure to use `remark-math 6` and `rehype-katex 7` for Docusaurus v3 (using MDX v3). We can't guarantee other versions will work.
|
||||
|
||||
```diff package.json
|
||||
{
|
||||
- "remark-math": "^3.0.0",
|
||||
+ "remark-math": "^6.0.0",
|
||||
- "rehype-katex": "^5.0.0"
|
||||
+ "rehype-katex": "^7.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Turn off MDX v1 compat
|
||||
|
||||
Docusaurus v3 comes with [MDX v1 compatibility options](../api/docusaurus.config.js.mdx#markdown), that are turned on by default.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
export default {
|
||||
markdown: {
|
||||
mdx1Compat: {
|
||||
comments: true,
|
||||
admonitions: true,
|
||||
headingIds: true,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `comments` option
|
||||
|
||||
This option allows the usage of HTML comments inside MDX, while HTML comments are officially not supported anymore.
|
||||
|
||||
For MDX files, we recommend to progressively use MDX `{/* comments */}` instead of HTML `<!-- comments -->`, and then turn this compatibility option off.
|
||||
|
||||
:::info Blog truncate marker
|
||||
|
||||
The default blog truncate marker now supports both `<!-- truncate -->` and `{/* truncate */}`.
|
||||
|
||||
:::
|
||||
|
||||
#### `admonitions` option
|
||||
|
||||
This option allows the usage of the Docusaurus v2 [admonition title](../guides/markdown-features/markdown-features-admonitions.mdx#specifying-title) syntax:
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
|
||||
content
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
Docusaurus now implements admonitions with [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)), and the syntax to provide a directive label requires square brackets:
|
||||
|
||||
```md
|
||||
:::note[Your Title]
|
||||
|
||||
content
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
We recommend to progressively use the new Markdown directive label syntax, and then turn this compatibility option off.
|
||||
|
||||
#### `headingIds` option
|
||||
|
||||
This option allows the usage of the Docusaurus v2 [explicit heading id](../guides/markdown-features/markdown-features-toc.mdx#heading-ids) syntax:
|
||||
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
This syntax is now invalid MDX, and would require to escape the `{` character: `\{#my-explicit-id}`.
|
||||
|
||||
We recommend to keep this compatibility option on for now, until we provide a new syntax compatible with newer versions of MDX.
|
||||
|
||||
## Ask For Help
|
||||
|
||||
In case of any upgrade problem, the first things to try are:
|
||||
|
||||
- make sure all your docs compile in the [MDX playground](https://mdxjs.com/playground/), or using [`npx docusaurus-mdx-checker`](https://github.com/slorber/docusaurus-mdx-checker)
|
||||
- delete `node_modules` and run `npm install` again
|
||||
- run `docusaurus clear` to clear the caches
|
||||
- remove third-party plugins that might not support Docusaurus v3
|
||||
- delete all your swizzled components
|
||||
|
||||
Once you have tried that, you can ask for support through the following support channels:
|
||||
|
||||
- [Docusaurus v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9336)
|
||||
- [Docusaurus v3 - Discord channel #migration-v2-to-v3](https://discord.com/channels/398180168688074762/1154771869094912090)
|
||||
- [MDX v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9053)
|
||||
- [MDX v3 - Remark/Rehype Plugins Support](https://github.com/facebook/docusaurus/discussions/9337)
|
||||
- [MDX v3 - Discord channel #migration-mdx-v3](https://discord.com/channels/398180168688074762/1116724556976111616)
|
||||
|
||||
Please consider **our time is precious**. To ensure that your support request is not ignored, we kindly ask you to:
|
||||
|
||||
- provide a **minimal** reproduction that we can easily run, ideally created with [docusaurus.new](https://docusaurus.new)
|
||||
- provide a live deployment url showing the problem in action (if your site can build)
|
||||
- explain clearly the problem, much more than an ambiguous "it doesn't work"
|
||||
- include as much relevant material as possible: code snippets, repo url, git branch urls, full stack traces, screenshots and videos
|
||||
- present your request clearly, concisely, showing us that you have made an effort to help us help you
|
||||
|
||||
Alternatively, you can look for a paid [Docusaurus Service Provider](https://github.com/facebook/docusaurus/discussions/9281) to execute this upgrade for you. If your site is open source, you can also ask our community for [free, benevolent help](https://github.com/facebook/docusaurus/discussions/9283).
|
||||
Loading…
Add table
Add a link
Reference in a new issue