3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 15:47:23 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore(v2): prepare v2.0.0.alpha-75 release (#4707)

Browse source 
* alpha 75

* v2.0.0-alpha.75
This commit is contained in:
Sébastien Lorber 2021-04-30 18:41:55 +02:00 • committed by GitHub
parent 05e7250c08
commit 0ef0d27c51
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
103 changed files with 11805 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

19
CHANGELOG.md
View file

@ -1,5 +1,24 @@
# Docusaurus 2 Changelog
## 2.0.0-alpha.75 (2021-04-30)
#### :boom: Breaking Change
- `docusaurus-cssnano-preset`, `docusaurus-init`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-types`, `docusaurus`, `lqip-loader`
- [#4089](https://github.com/facebook/docusaurus/pull/4089) feat(v2): Webpack 5, PostCSS 8 ([@RDIL](https://github.com/RDIL))
#### :memo: Documentation
- [#4704](https://github.com/facebook/docusaurus/pull/4704) docs(v2): showcase meli ([@gempain](https://github.com/gempain))
- [#4699](https://github.com/facebook/docusaurus/pull/4699) docs(v2): Add Kosko to showcase ([@tommy351](https://github.com/tommy351))
#### Committers: 4
- Geoffroy Empain ([@gempain](https://github.com/gempain))
- Reece Dunham ([@RDIL](https://github.com/RDIL))
- Sébastien Lorber ([@slorber](https://github.com/slorber))
- Tommy Chen ([@tommy351](https://github.com/tommy351))
## 2.0.0-alpha.74 (2021-04-27)
#### :rocket: New Feature

2
lerna.json
View file

@ -1,5 +1,5 @@
{
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"npmClient": "yarn",
"useWorkspaces": true,
"changelog": {

2
packages/docusaurus-1.x/package.json
View file

@ -1,7 +1,7 @@
{
"name": "docusaurus",
"description": "Easy to Maintain Open Source Documentation Websites",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private_comment": "MADE PRIVATE ON PURPOSE! READ V1 PUBLISH GUIDE",
"private": true,
"license": "MIT",

2
packages/docusaurus-cssnano-preset/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/cssnano-preset",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Advanced cssnano preset for maximum optimization.",
"main": "index.js",
"license": "MIT",

2
packages/docusaurus-init-1.x/package.json
View file

@ -1,7 +1,7 @@
{
"name": "docusaurus-init",
"description": "Initialization script for Docusaurus",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private_comment": "MADE PRIVATE ON PURPOSE! READ V1 PUBLISH GUIDE",
"private": true,
"license": "MIT",

2
packages/docusaurus-init/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/init",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Create Docusaurus apps easily.",
"repository": {
"type": "git",

6
packages/docusaurus-init/templates/bootstrap/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-bootstrap-template",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -14,8 +14,8 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/preset-bootstrap": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/preset-bootstrap": "2.0.0-alpha.75",
"@mdx-js/react": "^1.6.21",
"@svgr/webpack": "^5.5.0",
"clsx": "^1.1.1",

6
packages/docusaurus-init/templates/classic/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-classic-template",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -14,8 +14,8 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/preset-classic": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/preset-classic": "2.0.0-alpha.75",
"@mdx-js/react": "^1.6.21",
"@svgr/webpack": "^5.5.0",
"clsx": "^1.1.1",

6
packages/docusaurus-init/templates/facebook/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-facebook-template",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -18,8 +18,8 @@
"prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/preset-classic": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/preset-classic": "2.0.0-alpha.75",
"@mdx-js/react": "^1.6.21",
"@svgr/webpack": "^5.5.0",
"clsx": "^1.1.1",

8
packages/docusaurus-mdx-loader/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/mdx-loader",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docusaurus Loader for MDX",
"main": "src/index.js",
"types": "src/index.d.ts",
@ -20,8 +20,8 @@
"dependencies": {
"@babel/parser": "^7.12.16",
"@babel/traverse": "^7.12.13",
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@mdx-js/mdx": "^1.6.21",
"@mdx-js/react": "^1.6.21",
"escape-html": "^1.0.3",
@ -37,7 +37,7 @@
"webpack": "^5.28.0"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.75",
"remark": "^12.0.0",
"remark-mdx": "^1.6.21",
"to-vfile": "^6.0.0",

2
packages/docusaurus-migrate/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/migrate",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "A CLI tool to migrate from older versions of Docusaurus.",
"main": "lib/index.js",
"license": "MIT",

2
packages/docusaurus-module-type-aliases/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/module-type-aliases",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docusaurus module type aliases.",
"types": "./src/index.d.ts",
"publishConfig": {

10
packages/docusaurus-plugin-client-redirects/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-client-redirects",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Client redirects plugin for Docusaurus.",
"main": "lib/index.js",
"scripts": {
@ -17,10 +17,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"chalk": "^3.0.0",
"eta": "^1.11.0",
"fs-extra": "^9.1.0",

12
packages/docusaurus-plugin-content-blog/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-blog",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Blog plugin for Docusaurus.",
"main": "lib/index.js",
"types": "index.d.ts",
@ -18,11 +18,11 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/mdx-loader": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/mdx-loader": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"chalk": "^4.1.0",
"feed": "^4.2.2",
"fs-extra": "^9.1.0",

14
packages/docusaurus-plugin-content-docs/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-docs",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docs plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-content-docs.d.ts",
@ -18,18 +18,18 @@
},
"license": "MIT",
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-alpha.74",
"@docusaurus/module-type-aliases": "2.0.0-alpha.75",
"@types/js-yaml": "^4.0.0",
"@types/picomatch": "^2.2.1",
"commander": "^5.1.0",
"picomatch": "^2.1.1"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/mdx-loader": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/mdx-loader": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"chalk": "^4.1.0",
"combine-promises": "^1.1.0",
"execa": "^5.0.0",

12
packages/docusaurus-plugin-content-pages/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-pages",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Pages plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-content-pages.d.ts",
@ -18,11 +18,11 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/mdx-loader": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/mdx-loader": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"globby": "^11.0.2",
"lodash": "^4.17.20",
"minimatch": "^3.0.4",

8
packages/docusaurus-plugin-debug/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-debug",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Debug plugin for Docusaurus.",
"main": "lib/index.js",
"scripts": {
@ -17,9 +17,9 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"react-json-view": "^1.21.1",
"tslib": "^2.1.0"
},

4
packages/docusaurus-plugin-google-analytics/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-google-analytics",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Global analytics (analytics.js) plugin for Docusaurus.",
"main": "src/index.js",
"publishConfig": {
@ -13,7 +13,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74"
"@docusaurus/core": "2.0.0-alpha.75"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

4
packages/docusaurus-plugin-google-gtag/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-google-gtag",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Global Site Tag (gtag.js) plugin for Docusaurus.",
"main": "src/index.js",
"publishConfig": {
@ -13,7 +13,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74"
"@docusaurus/core": "2.0.0-alpha.75"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

10
packages/docusaurus-plugin-ideal-image/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-ideal-image",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).",
"main": "lib/index.js",
"scripts": {
@ -20,12 +20,12 @@
"fs-extra": "^9.1.0"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/lqip-loader": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/lqip-loader": "2.0.0-alpha.75",
"@docusaurus/responsive-loader": "1.4.0",
"@docusaurus/types": "2.0.0-alpha.75",
"@endiliey/react-ideal-image": "^0.0.11",
"react-waypoint": "^9.0.2",
"@docusaurus/responsive-loader": "1.4.0",
"sharp": "^0.27.1",
"tslib": "^2.1.0",
"webpack": "^5.28.0"

8
packages/docusaurus-plugin-pwa/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-pwa",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docusaurus Plugin to add PWA support.",
"main": "src/index.js",
"publishConfig": {
@ -16,9 +16,9 @@
"@babel/plugin-proposal-nullish-coalescing-operator": "^7.12.13",
"@babel/plugin-proposal-optional-chaining": "^7.12.16",
"@babel/preset-env": "^7.12.16",
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/theme-common": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/theme-common": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"babel-loader": "^8.2.2",
"clsx": "^1.1.1",
"core-js": "^2.6.5",

10
packages/docusaurus-plugin-sitemap/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-sitemap",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Simple sitemap generation plugin for Docusaurus.",
"main": "lib/index.js",
"scripts": {
@ -17,10 +17,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"fs-extra": "^9.1.0",
"sitemap": "^6.3.6",
"tslib": "^2.1.0"

12
packages/docusaurus-preset-bootstrap/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/preset-bootstrap",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Bootstrap preset for Docusaurus.",
"main": "src/index.js",
"license": "MIT",
@ -13,11 +13,11 @@
"directory": "packages/docusaurus-preset-bootstrap"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.74",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.74",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.74",
"@docusaurus/theme-bootstrap": "2.0.0-alpha.74"
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.75",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.75",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.75",
"@docusaurus/theme-bootstrap": "2.0.0-alpha.75"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

22
packages/docusaurus-preset-classic/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/preset-classic",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Classic preset for Docusaurus.",
"main": "src/index.js",
"publishConfig": {
@ -13,16 +13,16 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.74",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.74",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.74",
"@docusaurus/plugin-debug": "2.0.0-alpha.74",
"@docusaurus/plugin-google-analytics": "2.0.0-alpha.74",
"@docusaurus/plugin-google-gtag": "2.0.0-alpha.74",
"@docusaurus/plugin-sitemap": "2.0.0-alpha.74",
"@docusaurus/theme-classic": "2.0.0-alpha.74",
"@docusaurus/theme-search-algolia": "2.0.0-alpha.74"
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.75",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.75",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.75",
"@docusaurus/plugin-debug": "2.0.0-alpha.75",
"@docusaurus/plugin-google-analytics": "2.0.0-alpha.75",
"@docusaurus/plugin-google-gtag": "2.0.0-alpha.75",
"@docusaurus/plugin-sitemap": "2.0.0-alpha.75",
"@docusaurus/theme-classic": "2.0.0-alpha.75",
"@docusaurus/theme-search-algolia": "2.0.0-alpha.75"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

2
packages/docusaurus-remark-plugin-npm2yarn/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/remark-plugin-npm2yarn",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Remark plugin for converting npm commands to Yarn commands as tabs.",
"main": "src/index.js",
"publishConfig": {

16
packages/docusaurus-theme-bootstrap/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-bootstrap",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Bootstrap theme for Docusaurus.",
"main": "src/index.js",
"types": "src/types.d.ts",
@ -14,12 +14,12 @@
"directory": "packages/docusaurus-theme-bootstrap"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.74",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.74",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.74",
"@docusaurus/theme-common": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.75",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.75",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.75",
"@docusaurus/theme-common": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@mdx-js/react": "^1.6.21",
"bootstrap": "^4.4.1",
"classnames": "^2.2.6",
@ -28,7 +28,7 @@
"reactstrap": "^8.4.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-alpha.74"
"@docusaurus/module-type-aliases": "2.0.0-alpha.75"
},
"scripts": {
"build": "tsc --noEmit && yarn babel && yarn prettier",

20
packages/docusaurus-theme-classic/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-classic",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Classic theme for Docusaurus",
"main": "lib/index.js",
"types": "src/types.d.ts",
@ -23,14 +23,14 @@
"update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.74",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.74",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.74",
"@docusaurus/theme-common": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.75",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.75",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.75",
"@docusaurus/theme-common": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"@mdx-js/mdx": "^1.6.21",
"@mdx-js/react": "^1.6.21",
"chalk": "^4.1.0",
@ -49,7 +49,7 @@
"rtlcss": "^3.1.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-alpha.74"
"@docusaurus/module-type-aliases": "2.0.0-alpha.75"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

14
packages/docusaurus-theme-common/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-common",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Common code for Docusaurus themes.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,15 +18,15 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.74",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.74",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-content-blog": "2.0.0-alpha.75",
"@docusaurus/plugin-content-docs": "2.0.0-alpha.75",
"@docusaurus/plugin-content-pages": "2.0.0-alpha.75",
"@docusaurus/types": "2.0.0-alpha.75",
"tslib": "^2.1.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-alpha.74"
"@docusaurus/module-type-aliases": "2.0.0-alpha.75"
},
"peerDependencies": {
"prism-react-renderer": "^1.1.1",

6
packages/docusaurus-theme-live-codeblock/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-live-codeblock",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Docusaurus live code block component.",
"main": "src/index.js",
"publishConfig": {
@ -13,8 +13,8 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"@philpl/buble": "^0.19.7",
"clsx": "^1.1.1",
"parse-numeric-range": "^1.2.0",

10
packages/docusaurus-theme-search-algolia/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-search-algolia",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Algolia search component for Docusaurus.",
"main": "src/index.js",
"publishConfig": {
@ -14,10 +14,10 @@
"license": "MIT",
"dependencies": {
"@docsearch/react": "^3.0.0-alpha.33",
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/theme-common": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/theme-common": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"algoliasearch": "^4.8.4",
"algoliasearch-helper": "^3.3.4",
"clsx": "^1.1.1",

2
packages/docusaurus-types/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/types",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Common types for Docusaurus packages.",
"main": "./src/index.js",
"types": "./src/index.d.ts",

4
packages/docusaurus-utils-validation/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils-validation",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Node validation utility functions for Docusaurus packages.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,7 +18,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.75",
"chalk": "^4.1.0",
"joi": "^17.4.0",
"tslib": "^2.1.0"

4
packages/docusaurus-utils/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Node utility functions for Docusaurus packages.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,7 +18,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.75",
"@types/github-slugger": "^1.3.0",
"chalk": "^4.1.0",
"escape-string-regexp": "^4.0.0",

12
packages/docusaurus/package.json
View file

@ -1,7 +1,7 @@
{
"name": "@docusaurus/core",
"description": "Easy to Maintain Open Source Documentation Websites",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"license": "MIT",
"publishConfig": {
"access": "public"
@ -31,7 +31,7 @@
"url": "https://github.com/facebook/docusaurus/issues"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-alpha.74",
"@docusaurus/module-type-aliases": "2.0.0-alpha.75",
"@types/detect-port": "^1.3.0",
"@types/nprogress": "^0.2.0",
"tmp-promise": "^3.0.2"
@ -47,11 +47,11 @@
"@babel/runtime": "^7.12.5",
"@babel/runtime-corejs3": "^7.12.13",
"@babel/traverse": "^7.12.13",
"@docusaurus/cssnano-preset": "2.0.0-alpha.74",
"@docusaurus/cssnano-preset": "2.0.0-alpha.75",
"@docusaurus/react-loadable": "5.5.0",
"@docusaurus/types": "2.0.0-alpha.74",
"@docusaurus/utils": "2.0.0-alpha.74",
"@docusaurus/utils-validation": "2.0.0-alpha.74",
"@docusaurus/types": "2.0.0-alpha.75",
"@docusaurus/utils": "2.0.0-alpha.75",
"@docusaurus/utils-validation": "2.0.0-alpha.75",
"@endiliey/static-site-generator-webpack-plugin": "^4.0.0",
"@svgr/webpack": "^5.5.0",
"autoprefixer": "^10.2.5",

2
packages/lqip-loader/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/lqip-loader",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Low Quality Image Placeholders (LQIP) loader for webpack.",
"main": "src/index.js",
"publishConfig": {

2
packages/stylelint-copyright/package.json
View file

@ -1,6 +1,6 @@
{
"name": "stylelint-copyright",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"description": "Stylelint plugin to check CSS files for a copyright header.",
"main": "index.js",
"license": "MIT",

4
website-1.x/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-1-website",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private": true,
"scripts": {
"start": "docusaurus-start",
@ -15,6 +15,6 @@
"netlify:build": "yarn crowdin-download && yarn build"
},
"dependencies": {
"docusaurus": "2.0.0-alpha.74"
"docusaurus": "2.0.0-alpha.75"
}
}

16
website/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-website",
"version": "2.0.0-alpha.74",
"version": "2.0.0-alpha.75",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -27,13 +27,13 @@
},
"dependencies": {
"@crowdin/cli": "^3.5.2",
"@docusaurus/core": "2.0.0-alpha.74",
"@docusaurus/plugin-client-redirects": "2.0.0-alpha.74",
"@docusaurus/plugin-ideal-image": "2.0.0-alpha.74",
"@docusaurus/plugin-pwa": "2.0.0-alpha.74",
"@docusaurus/preset-classic": "2.0.0-alpha.74",
"@docusaurus/remark-plugin-npm2yarn": "2.0.0-alpha.74",
"@docusaurus/theme-live-codeblock": "2.0.0-alpha.74",
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/plugin-client-redirects": "2.0.0-alpha.75",
"@docusaurus/plugin-ideal-image": "2.0.0-alpha.75",
"@docusaurus/plugin-pwa": "2.0.0-alpha.75",
"@docusaurus/preset-classic": "2.0.0-alpha.75",
"@docusaurus/remark-plugin-npm2yarn": "2.0.0-alpha.75",
"@docusaurus/theme-live-codeblock": "2.0.0-alpha.75",
"clsx": "^1.1.1",
"color": "^3.1.3",
"netlify-plugin-cache": "^1.0.3",

489
website/versioned_docs/version-2.0.0-alpha.75/api/docusaurus.config.js.md Normal file
View file

@ -0,0 +1,489 @@
---
id: docusaurus.config.js
title: docusaurus.config.js
description: API reference for Docusaurus configuration file.
slug: /docusaurus.config.js
---
## Overview {#overview}
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
## Required fields {#required-fields}
### `title` {#title}
- Type: `string`
Title for your website.
```js title="docusaurus.config.js"
module.exports = {
title: 'Docusaurus',
};
```
### `favicon` {#favicon}
- Type: `string`
URL for site favicon. Example:
```js title="docusaurus.config.js"
module.exports = {
favicon: 'https://docusaurus.io/favicon.ico',
};
```
You can also use the favicon URL relative to the `static` directory of your site. For example, your site has the following directory structure:
```bash
.
├── README.md
├ # ... other files in root directory
└─ static
└── img
└── favicon.ico
```
So you can refer it like below:
```js title="docusaurus.config.js"
module.exports = {
favicon: 'img/favicon.ico',
};
```
### `url` {#url}
- Type: `string`
URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [baseUrl](#baseurl) field.
```js title="docusaurus.config.js"
module.exports = {
url: 'https://docusaurus.io',
};
```
### `baseUrl` {#baseurl}
- 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.
```js title="docusaurus.config.js"
module.exports = {
baseUrl: '/',
};
```
## Optional fields {#optional-fields}
### `i18n` {#i18n}
- Type: `Object`
The i18n configuration object to [localize your site](../i18n/i18n-introduction.md).
Example:
```js title="docusaurus.config.js"
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
},
fr: {
label: 'Français',
direction: 'ltr',
},
},
},
};
```
- `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 Araric, Hebrew, etc.)
### `noIndex` {#noindex}
- Type: `boolean`
This option adds `<meta name="robots" content="noindex, nofollow">` in pages, to tell search engines to avoid indexing your site (more information [here](https://moz.com/learn/seo/robots-meta-directives)).
Example:
```js title="docusaurus.config.js"
module.exports = {
noIndex: true, // Defaults to `false`
};
```
### `onBrokenLinks` {#onbrokenlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
The behavior of Docusaurus, when it detects any broken link.
By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.
:::note
The broken links detection is only available for a production build (`docusaurus build`).
:::
### `onBrokenMarkdownLinks` {#onbrokenmarkdownlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
The behavior of Docusaurus, when it detects any broken markdown link.
By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed.
### `onDuplicateRoutes` {#onduplicateroutes}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
The behavior of Docusaurus when it detects any [duplicate routes](/guides/creating-pages.md#duplicate-routes).
By default, it displays a warning after you run `yarn start` or `yarn build`.
### `tagline` {#tagline}
- Type: `string`
The tagline for your website.
```js title="docusaurus.config.js"
module.exports = {
tagline:
'Docusaurus makes it easy to maintain Open Source documentation websites.',
};
```
### `organizationName` {#organizationname}
- Type: `string`
The GitHub user or organization that owns the repository. Used by the deployment command.
```js title="docusaurus.config.js"
module.exports = {
// Docusaurus' organization is facebook
organizationName: 'facebook',
};
```
### `projectName` {#projectname}
- Type: `string`
The name of the GitHub repository. Used by the deployment command.
```js title="docusaurus.config.js"
module.exports = {
projectName: 'docusaurus',
};
```
### `githubHost` {#githubhost}
- Type: `string`
The hostname of your server. Useful if you are using GitHub Enterprise.
```js title="docusaurus.config.js"
module.exports = {
githubHost: 'github.com',
};
```
### `githubPort` {#githubPort}
- Type: `string`
The port of your server. Useful if you are using GitHub Enterprise.
```js title="docusaurus.config.js"
module.exports = {
githubPort: '22',
};
```
### `themeConfig` {#themeconfig}
- Type: `Object`
The [theme configuration](./themes/theme-configuration.md) object, to customize your site UI like navbar, footer.
Example:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
hideableSidebar: false,
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: true,
switchConfig: {
darkIcon: '🌙',
lightIcon: '\u2600',
// React inline style object
// see https://reactjs.org/docs/dom-elements.html#style
darkIconStyle: {
marginLeft: '2px',
},
lightIconStyle: {
marginLeft: '1px',
},
},
},
navbar: {
title: 'Site Title',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
},
items: [
{
to: 'docs/docusaurus.config.js',
activeBasePath: 'docs',
label: 'docusaurus.config.js',
position: 'left',
},
// ... other links
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Docs',
to: 'docs/doc1',
},
],
},
// ... other links
],
logo: {
alt: 'Facebook Open Source Logo',
src: 'https://docusaurus.io/img/oss_logo.png',
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
},
},
};
```
### `plugins` {#plugins}
<!-- TODO: configuration for plugins -->
- Type: `any[]`
```js title="docusaurus.config.js"
module.exports = {
plugins: [],
};
```
### `themes` {#themes}
<!-- TODO: configuration for plugins -->
- Type: `any[]`
```js title="docusaurus.config.js"
module.exports = {
themes: [],
};
```
### `presets` {#presets}
<!-- TODO: configuration for presets -->
- Type: `any[]`
```js title="docusaurus.config.js"
module.exports = {
presets: [],
};
```
### `customFields` {#customfields}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.
- Type: `Object`
```js title="docusaurus.config.js"
module.exports = {
customFields: {
admin: 'endi',
superman: 'lol',
},
};
```
Attempting to add unknown field in the config will lead to error in build time:
```bash
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
```
### `scripts` {#scripts}
An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`.
Note that `<script>` added here are render-blocking so you might want to add `async: true`/`defer: true` to the objects.
- Type: `(string | Object)[]`
Example:
```js title="docusaurus.config.js"
module.exports = {
scripts: [
// String format.
'https://docusaurus.io/script.js',
// Object format.
{
src:
'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
async: true,
},
],
};
```
### `clientModules` {#clientmodules}
An array of client modules to load globally on your site:
Example:
```js title="docusaurus.config.js"
module.exports = {
clientModules: [
require.resolve('./mySiteGlobalJs.js'),
require.resolve('./mySiteGlobalCss.css'),
],
};
```
See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules).
### `ssrTemplate` {#ssrtemplate}
An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`.
- Type: `string`
Example:
```js title="docusaurus.config.js"
module.exports = {
ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=0.86, maximum-scale=3.0, minimum-scale=0.86">
<meta name="generator" content="Docusaurus v<%= it.version %>">
<%~ it.headTags %>
<% it.metaAttributes.forEach((metaAttribute) => { %>
<%~ metaAttribute %>
<% }); %>
<% it.stylesheets.forEach((stylesheet) => { %>
<link rel="stylesheet" type="text/css" href="<%= it.baseUrl %><%= stylesheet %>" />
<% }); %>
<% it.scripts.forEach((script) => { %>
<link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
<% }); %>
</head>
<body <%~ it.bodyAttributes %> itemscope="" itemtype="http://schema.org/Organization">
<%~ it.preBodyTags %>
<div id="__docusaurus">
<%~ it.appHtml %>
</div>
<div id="outside-docusaurus">
<span>Custom markup</span>
</div>
<% it.scripts.forEach((script) => { %>
<script type="text/javascript" src="<%= it.baseUrl %><%= script %>"></script>
<% }); %>
<%~ it.postBodyTags %>
</body>
</html>
};
```
### `stylesheets` {#stylesheets}
An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`.
- Type: `(string | Object)[]`
Example:
```js title="docusaurus.config.js"
module.exports = {
stylesheets: [
// String format.
'https://docusaurus.io/style.css',
// Object format.
{
href: 'http://mydomain.com/style.css',
type: 'text/css',
},
],
};
```
### `titleDelimiter` {#titledelimiter}
- Type: `string`
A string that will be used as title delimiter in the generated `<title>` tag.
Example:
```js title="docusaurus.config.js"
module.exports = {
titleDelimiter: '🦖', // Defaults to `|`
};
```
### `baseUrlIssueBanner` {#baseurlissuebanner}
- Type: `boolean`
When enabled, will show a banner in case your site can't load its CSS or JavaScript files, which is a very common issue, often related to a wrong `baseUrl` in site config.
Example:
```js title="docusaurus.config.js"
module.exports = {
baseUrlIssueBanner: true, // Defaults to `true`
};
```
![baseUrlIssueBanner](/img/baseUrlIssueBanner.png)
:::caution
This banner need to inline CSS / JS.
If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it.
:::

28
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/overview.md Normal file
View file

@ -0,0 +1,28 @@
---
id: plugins-overview
title: 'Docusaurus plugins'
sidebar_label: Plugins overview
slug: '/api/plugins'
---
We provide official Docusaurus plugins.
## Content plugins {#content-plugins}
These plugins are responsible to load your site's content, and create pages for your theme to render.
- [@docusaurus/plugin-content-docs](./plugin-content-docs.md)
- [@docusaurus/plugin-content-blog](./plugin-content-blog.md)
- [@docusaurus/plugin-content-pages](./plugin-content-pages.md)
## Behavior plugins {#behavior-plugins}
These plugins will add a useful behavior to your Docusaurus site.
- [@docusaurus/plugin-debug](./plugin-debug.md)
- [@docusaurus/plugin-sitemap](./plugin-sitemap.md)
- [@docusaurus/plugin-pwa](./plugin-pwa.md)
- [@docusaurus/plugin-client-redirects](./plugin-client-redirects.md)
- [@docusaurus/plugin-ideal-image](./plugin-ideal-image.md)
- [@docusaurus/plugin-google-analytics](./plugin-google-analytics.md)
- [@docusaurus/plugin-google-gtag](./plugin-google-gtag.md)

129
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-client-redirects.md Normal file
View file

@ -0,0 +1,129 @@
---
id: plugin-client-redirects
title: '📦 plugin-client-redirects'
slug: '/api/plugins/@docusaurus/plugin-client-redirects'
---
Docusaurus Plugin to generate **client-side redirects**.
This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript.
:::note
This plugin only create redirects for the production build.
:::
:::caution
It is better to use server-side redirects whenever possible.
Before using this plugin, you should look if your hosting provider doesn't offer this feature.
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-client-redirects
```
## Configuration {#configuration}
Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html'],
},
],
],
};
```
Second usecase: you have `/myDocusaurusPage.html`, and you want to redirect to this page from `/myDocusaurusPage`.
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
toExtensions: ['html'],
},
],
],
};
```
For custom redirect logic, provide your own `createRedirects` function.
Let's imagine you change the url of an existing page, you might want to make sure the old url still works:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
redirects: [
{
to: '/docs/newDocPath', // string
from: ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016'], // string | string[]
},
],
},
],
],
};
```
It's possible to use a function to create the redirects for each existing path:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
createRedirects: function (existingPath) {
if (existingPath === '/docs/newDocPath') {
return ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016']; // string | string[]
}
},
},
],
],
};
```
Finally, it's possible to use all options at the same time:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html', 'htm'],
toExtensions: ['exe', 'zip'],
redirects: [
{
to: '/docs/newDocPath',
from: '/docs/oldDocPath',
},
],
createRedirects: function (existingPath) {
if (existingPath === '/docs/newDocPath2') {
return ['/docs/oldDocPath2'];
}
},
},
],
],
};
```

140
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-content-blog.md Normal file
View file

@ -0,0 +1,140 @@
---
id: plugin-content-blog
title: '📦 plugin-content-blog'
slug: '/api/plugins/@docusaurus/plugin-content-blog'
---
Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-content-blog
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Path to data on filesystem relative to site dir.
*/
path: 'blog',
/**
* Base url to edit your site.
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* For advanced cases, compute the edit url for each markdown file yourself.
*/
editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
},
/**
* Useful if you commit localized files to git.
* When markdown files are localized, the edit url will target the localized file,
* instead of the original unlocalized file.
* Note: this option is ignored when editUrl is a function
*/
editLocalizedFiles: false,
/**
* Blog page title for better SEO
*/
blogTitle: 'Blog title',
/**
* Blog page meta description for better SEO
*/
blogDescription: 'Blog',
/**
* Number of blog post elements to show in the blog sidebar
* 'ALL' to show all blog posts
* 0 to disable
*/
blogSidebarCount: 5,
/**
* Title of the blog sidebar
*/
blogSidebarTitle: 'All our posts',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
postsPerPage: 10,
/**
* Theme components used by the blog pages.
*/
blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
/**
* Remark and Rehype plugins passed to MDX.
*/
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Truncate marker, can be a regex or string.
*/
truncateMarker: /<!--\s*(truncate)\s*-->/,
/**
* Show estimated reading time for the blog post.
*/
showReadingTime: true,
/**
* Blog feed.
* If feedOptions is undefined, no rss feed will be generated.
*/
feedOptions: {
type: '', // required. 'rss' | 'feed' | 'all'
title: '', // default to siteConfig.title
description: '', // default to `${siteConfig.title} Blog`
copyright: '',
language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
},
},
],
],
};
```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>`
- **JSON files**: N/A
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── first-blog-post.md
└── second-blog-post.md
```

260
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-content-docs.md Normal file
View file

@ -0,0 +1,260 @@
---
id: plugin-content-docs
title: '📦 plugin-content-docs'
slug: '/api/plugins/@docusaurus/plugin-content-docs'
---
Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-content-docs
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
/**
* Path to data on filesystem relative to site dir.
*/
path: 'docs',
/**
* Base url to edit your site.
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* For advanced cases, compute the edit url for each markdown file yourself.
*/
editUrl: function ({
locale,
version,
versionDocsDirPath,
docPath,
permalink,
}) {
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
},
/**
* Useful if you commit localized files to git.
* When markdown files are localized, the edit url will target the localized file,
* instead of the original unlocalized file.
* Note: this option is ignored when editUrl is a function
*/
editLocalizedFiles: false,
/**
* Useful if you don't want users to submit doc pull-requests to older versions.
* When docs are versioned, the edit url will link to the doc
* in current version, instead of the versioned doc.
* Note: this option is ignored when editUrl is a function
*/
editCurrentVersion: false,
/**
* URL route for the docs section of your site.
* *DO NOT* include a trailing slash.
* INFO: It is possible to set just `/` for shipping docs without base path.
*/
routeBasePath: 'docs',
include: ['**/*.md', '**/*.mdx'], // Extensions to include.
/**
* Path to sidebar configuration for showing a list of markdown pages.
*/
sidebarPath: 'sidebars.js',
/**
* Function used to replace the sidebar items of type "autogenerated"
* by real sidebar items (docs, categories, links...)
*/
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator, // useful to re-use/enhance default sidebar generation logic from Docusaurus
numberPrefixParser, // numberPrefixParser configured for this plugin
item, // the sidebar item with type "autogenerated"
version, // the current version
docs, // all the docs of that version (unfiltered)
}) {
// Use the provided data to generate a custom sidebar slice
return [
{type: 'doc', id: 'intro'},
{
type: 'category',
label: 'Tutorials',
items: [
{type: 'doc', id: 'tutorial1'},
{type: 'doc', id: 'tutorial2'},
],
},
];
},
/**
* The Docs plugin supports number prefixes like "01-My Folder/02.My Doc.md".
* Number prefixes are extracted and used as position to order autogenerated sidebar items.
* For conveniency, number prefixes are automatically removed from the default doc id, name, title.
* This parsing logic is configurable to allow all possible usecases and filename patterns.
* Use "false" to disable this behavior and leave the docs untouched.
*/
numberPrefixParser: function (filename) {
// Implement your own logic to extract a potential number prefix
const numberPrefix = findNumberPrefix(filename);
// Prefix found: return it with the cleaned filename
if (numberPrefix) {
return {
numberPrefix,
filename: filename.replace(prefix, ''),
};
}
// No number prefix found
return {numberPrefix: undefined, filename};
},
/**
* Theme components used by the docs pages
*/
docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/DocItem',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Whether to display the author who last updated the doc.
*/
showLastUpdateAuthor: false,
/**
* Whether to display the last date the doc was updated.
*/
showLastUpdateTime: false,
/**
* By default, versioning is enabled on versioned sites.
* This is a way to explicitly disable the versioning feature.
*/
disableVersioning: false,
/**
* Skip the next release docs when versioning is enabled.
* This will not generate HTML files in the production build for documents
* in `/docs/next` directory, only versioned docs.
*/
excludeNextVersionDocs: false,
/**
* The last version is the one we navigate to in priority on versioned sites
* It is the one displayed by default in docs navbar items
* By default, the last version is the first one to appear in versions.json
* By default, the last version is at the "root" (docs have path=/docs/myDoc)
* Note: it is possible to configure the path and label of the last version
* Tip: using lastVersion: 'current' make sense in many cases
*/
lastVersion: undefined,
/**
* The docusaurus versioning defaults don't make sense for all projects
* This gives the ability customize the label and path of each version
* You may not like that default version
*/
versions: {
/*
Example configuration:
current: {
label: 'Android SDK v2.0.0 (WIP)',
path: 'android-2.0.0',
},
'1.0.0': {
label: 'Android SDK v1.0.0',
path: 'android-1.0.0',
},
*/
},
/**
* Sometimes you only want to 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
*/
onlyIncludeVersions: undefined, // ex: ["current", "1.0.0", "2.0.0"]
},
],
],
};
```
## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side:
- `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension)
- `title`: The title of your document. If this field is not present, the document's `title` will default to its `id`
- `hide_title`: Whether to hide the title at the top of the doc. By default, it is `false`
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`
- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title`
- `sidebar_position`: Permits to control the position of a doc inside the generated sidebar slice, when using `autogenerated` sidebar items. Can be Int or Float.
- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc
- `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from options fields passed to `docusaurus-plugin-content-docs`
- `keywords`: Keywords meta tag for the document page, for search engines
- `description`: The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. If this field is not present, it will default to the first line of the contents
- `image`: Cover or thumbnail image that will be used when displaying the link to your post
- `slug`: Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`
Example:
```yml
---
id: doc-markdown
title: Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown :)
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
- docs
- docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---
My Document Markdown content
```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-docs
│
│ # translations for website/docs
├── current
│   ├── api
│   │   └── config.md
│   └── getting-started.md
├── current.json
│
│ # translations for website/versioned_docs/version-1.0.0
├── version-1.0.0
│   ├── api
│   │   └── config.md
│   └── getting-started.md
└── version-1.0.0.json
```

89
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-content-pages.md Normal file
View file

@ -0,0 +1,89 @@
---
id: plugin-content-pages
title: '📦 plugin-content-pages'
slug: '/api/plugins/@docusaurus/plugin-content-pages'
---
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-content-pages
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-pages',
{
/**
* Path to data on filesystem
* relative to site dir
* components in this directory will be automatically converted to pages
*/
path: 'src/pages',
/**
* URL route for the page section of your site
* do not include trailing slash
*/
routeBasePath: '',
include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
/**
* No Route will be created for matching files
*/
exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/*.test.{js,ts}',
'**/__tests__/**',
],
/**
* Theme component used by markdown pages.
*/
mdxPageComponent: '@theme/MDXPage',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
},
],
],
};
```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-pages
│
│ # translations for website/src/pages
├── first-markdown-page.md
└── second-markdown-page.md
```

39
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-debug.md Normal file
View file

@ -0,0 +1,39 @@
---
id: plugin-debug
title: '📦 plugin-debug'
slug: '/api/plugins/@docusaurus/plugin-debug'
---
The debug plugin will display useful debug information at [http://localhost:3000/\_\_docusaurus/debug](http://localhost:3000/__docusaurus/debug).
It is mostly useful for plugin authors, that will be able to inspect more easily the content of the `.docusaurus` folder (like the creates routes), but also be able to inspect data structures that are never written to disk, like the plugin data loaded through the `contentLoaded` lifecycle.
:::note
If you report a bug, we will probably ask you to have this plugin turned on in the production, so that we can inspect your deployment config more easily.
If you don't have any sensitive information, you can keep it on in production [like we do](http://docusaurus.io/__docusaurus/debug).
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-debug
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
By default, it's enabled in dev, and disabled in prod, to avoid exposing potentially sensitive information.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/plugin-debug'],
};
```

34
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-google-analytics.md Normal file
View file

@ -0,0 +1,34 @@
---
id: plugin-google-analytics
title: '📦 plugin-google-analytics'
slug: '/api/plugins/@docusaurus/plugin-google-analytics'
---
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-google-analytics
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/plugin-google-analytics'],
themeConfig: {
googleAnalytics: {
trackingID: 'UA-141789564-1',
// Optional fields.
anonymizeIP: true, // Should IPs be anonymized?
},
},
};
```

34
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-google-gtag.md Normal file
View file

@ -0,0 +1,34 @@
---
id: plugin-google-gtag
title: '📦 plugin-google-gtag'
slug: '/api/plugins/@docusaurus/plugin-google-gtag'
---
The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-google-gtag
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/plugin-google-gtag'],
themeConfig: {
gtag: {
trackingID: 'UA-141789564-1',
// Optional fields.
anonymizeIP: true, // Should IPs be anonymized?
},
},
};
```

52
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-ideal-image.md Normal file
View file

@ -0,0 +1,52 @@
---
id: plugin-ideal-image
title: '📦 plugin-ideal-image'
slug: '/api/plugins/@docusaurus/plugin-ideal-image'
---
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-ideal-image
```
## Configuration {#configuration}
Modify your `docusaurus.config.js`
```diff
module.exports = {
...
+ plugins: ['@docusaurus/plugin-ideal-image'],
...
}
```
## Usage {#usage}
This plugin supports the PNG, GIF and JPG formats only.
```jsx
import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';
// your React code
<Image img={thumbnail} />
// or
<Image img={require('./path/to/img.png')} />
```
## Options {#options}
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. |
| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). |
| `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) |
| `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
| `max` | `integer` | | See `min` above |
| `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
| `quality` | `integer` | `85` | JPEG compression quality |

313
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-pwa.md Normal file
View file

@ -0,0 +1,313 @@
---
id: plugin-pwa
title: '📦 plugin-pwa'
slug: '/api/plugins/@docusaurus/plugin-pwa'
---
Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-pwa
```
## Configuration {#configuration}
Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.json`.
Modify `docusaurus.config.js` with a minimal PWA config, like:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
debug: true,
offlineModeActivationStrategies: [
'appInstalled',
'standalone',
'queryString',
],
pwaHead: [
{
tagName: 'link',
rel: 'icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'manifest',
href: '/manifest.json', // your PWA manifest
},
{
tagName: 'meta',
name: 'theme-color',
content: 'rgb(37, 194, 160)',
},
],
},
],
],
};
```
## Progressive Web App {#progressive-web-app}
Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and have the correct tags in `<head>` ([Options > pwaHead](#pwahead)).
After deployment, you can use [Lighthouse](https://developers.google.com/web/tools/lighthouse) to run an audit on your site.
For a more exhaustive list of what it takes for your site to be a PWA, refer to the [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist)
## App installation support {#app-installation-support}
If your browser supports it, you should be able to install a Docusaurus site as an app.
![pwa_install.gif](/img/pwa_install.gif)
:::note
App installation requires the https protocol and a valid manifest.
:::
## Offline mode (precaching) {#offline-mode-precaching}
We enable users to browse a Docusaurus site offline, by using service-worker precaching.
> ### [What is Precaching?](https://developers.google.com/web/tools/workbox/modules/workbox-precaching)
>
> One feature of service workers is the ability to save a set of files to the cache when the service worker is installing. This is often referred to as "precaching", since you are caching content ahead of the service worker being used.
>
> The main reason for doing this is that it gives developers control over the cache, meaning they can determine when and how long a file is cached as well as serve it to the browser without going to the network, meaning it can be used to create web apps that work offline.
>
> Workbox takes a lot of the heavy lifting out of precaching by simplifying the API and ensuring assets are downloaded efficiently.
By default, offline mode is enabled when the site is installed as an app. See the `offlineModeActivationStrategies` option for details.
After the site has been precached, the service worker will serve cached responses for later visits. When a new build is deployed along with a new service worker, the new one will begin installing and eventually move to a waiting state. During this waiting state, a reload popup will show and ask the user to reload the page for new content. Until the user either clears the application cache or clicks the `reload` button on the popup, the service worker will continue serving the old content.
:::caution
Offline mode / precaching requires downloading all the static assets of the site ahead of time, and can consume unnecessary bandwidth. It may not be a good idea to activate it for all kind of sites.
:::
## Options {#options}
### `debug` {#debug}
- Type: `boolean`
- Default: `false`
Turn debug mode on:
- Workbox logs
- Additional Docusaurus logs
- Unoptimized SW file output
- Source maps
### `offlineModeActivationStrategies` {#offlinemodeactivationstrategies}
- Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>`
- Default: `['appInstalled','queryString','standalone']`
Strategies used to turn the offline mode on:
- `appInstalled`: activates for users having installed the site as an app (not 100% reliable)
- `standalone`: activates for users running the app as standalone (often the case once a PWA is installed)
- `queryString`: activates if queryString contains `offlineMode=true` (convenient for PWA debugging)
- `mobile`: activates for mobile users (width <= 940px)
- `saveData`: activates for users with `navigator.connection.saveData === true`
- `always`: activates for all users
:::caution
Use this carefully: some users may not like to be forced to use the offline mode.
:::
:::danger
It is not possible to detect if an as a PWA in a very reliable way.
The `appinstalled` event has been [removed from the specification](https://github.com/w3c/manifest/pull/836), and the [`navigator.getInstalledRelatedApps()`](https://web.dev/get-installed-related-apps/) API is only supported in recent Chrome versions and require `related_applications` declared in the manifest.
The [`standalone` strategy](https://petelepage.com/blog/2019/07/is-my-pwa-installed/) is a nice fallback to activate the offline mode (at least when running the installed app).
:::
### `injectManifestConfig` {#injectmanifestconfig}
[Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline.
- Type: `InjectManifestOptions`
- Default: `{}`
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
injectManifestConfig: {
manifestTransforms: [
//...
],
modifyURLPrefix: {
//...
},
// We already add regular static assets (html, images...) to be available offline
// You can add more files according to your needs
globPatterns: ['**/*.{pdf,docx,xlsx}'],
// ...
},
},
],
],
};
```
### `reloadPopup` {#reloadpopup}
- Type: `string | false`
- Default: `'@theme/PwaReloadPopup'`
Module path to reload popup component. This popup is rendered when a new service worker is waiting to be installed, and we suggest a reload to the user.
Passing `false` will disable the popup, but this is not recommended: users won't have a way to get up-to-date content.
A custom component can be used, as long as it accepts `onReload` as a prop. The `onReload` callback should be called when the `reload` button is clicked. This will tell the service worker to install the waiting service worker and reload the page.
```ts
interface PwaReloadPopupProps {
onReload: () => void;
}
```
The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://infima.dev/docs/components/alert).
![pwa_reload.gif](/img/pwa_reload.gif)
### `pwaHead` {#pwahead}
- Type: `Array<{ tagName: string } & Record<string,string>>`
- Default: `[]`
Array of objects containing `tagName` and key-value pairs for attributes to inject into the `<head>` tag. Technically you can inject any head tag through this, but it's ideally used for tags to make your site PWA compliant. Here's a list of tag to make your app fully compliant:
```js
module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
pwaHead: [
{
tagName: 'link',
rel: 'icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'manifest',
href: '/manifest.json',
},
{
tagName: 'meta',
name: 'theme-color',
content: 'rgb(37, 194, 160)',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-capable',
content: 'yes',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-status-bar-style',
content: '#000',
},
{
tagName: 'link',
rel: 'apple-touch-icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'mask-icon',
href: '/img/docusaurus.svg',
color: 'rgb(37, 194, 160)',
},
{
tagName: 'meta',
name: 'msapplication-TileImage',
content: '/img/docusaurus.png',
},
{
tagName: 'meta',
name: 'msapplication-TileColor',
content: '#000',
},
],
},
],
],
};
```
### `swCustom` {#swcustom}
- Type: `string | undefined`
- Default: `undefined`
Useful for additional Workbox rules. You can do whatever a service worker can do here, and use the full power of workbox libraries. The code is transpiled, so you can use modern ES6+ syntax here.
For example, to cache files from external routes:
```js
import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
// default fn export receiving some useful params
export default function swCustom(params) {
const {
debug, // :boolean
offlineMode, // :boolean
} = params;
// Cache responses from external resources
registerRoute((context) => {
return [
/graph\.facebook\.com\/.*\/picture/,
/netlify\.com\/img/,
/avatars1\.githubusercontent/,
].some((regex) => context.url.href.match(regex));
}, new StaleWhileRevalidate());
}
```
The module should have a `default` function export, and receives some params.
### `swRegister` {#swregister}
- Type: `string | false`
- Default: `'docusaurus-plugin-pwa/src/registerSW.js'`
Adds an entry before the Docusaurus app so that registration can happen before the app runs. The default `registerSW.js` file is enough for simple registration.
Passing `false` will disable registration entirely.
## Manifest example {#manifest-example}
The Docusaurus site manifest can serve as an inspiration:
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
<CodeBlock className="language-json">
{JSON.stringify(require("@site/static/manifest.json"),null,2)}
</CodeBlock>
```

36
website/versioned_docs/version-2.0.0-alpha.75/api/plugins/plugin-sitemap.md Normal file
View file

@ -0,0 +1,36 @@
---
id: plugin-sitemap
title: '📦 plugin-sitemap'
slug: '/api/plugins/@docusaurus/plugin-sitemap'
---
This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-sitemap
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
:::
## Configuration {#configuration}
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
priority: 0.5,
trailingSlash: false,
},
],
],
};
```

32
website/versioned_docs/version-2.0.0-alpha.75/api/themes/overview.md Normal file
View file

@ -0,0 +1,32 @@
---
id: themes-overview
title: 'Docusaurus themes'
sidebar_label: Themes overview
slug: '/api/themes'
---
We provide official Docusaurus themes.
## Main themes {#main-themes}
The main themes implement the user interface for the [docs](../plugins/plugin-content-docs.md), [blog](../plugins/plugin-content-blog.md) and [pages](../plugins/plugin-content-pages.md) plugins.
- [@docusaurus/theme-classic](./theme-classic.md)
- [@docusaurus/theme-bootstrap](./theme-bootstrap.md) 🚧
:::caution
The goal is to have all themes share the exact same features, user-experience and configuration.
Only the UI design and underlying styling framework should change, and you should be able to change theme easily.
We are not there yet: only the classic theme is production ready.
:::
## Enhancement themes {#enhancement-themes}
These themes will enhance the existing main themes with additional user-interface related features.
- [@docusaurus/theme-live-codeblock](./theme-live-codeblock.md)
- [@docusaurus/theme-search-algolia](./theme-search-algolia.md)

25
website/versioned_docs/version-2.0.0-alpha.75/api/themes/theme-bootstrap.md Normal file
View file

@ -0,0 +1,25 @@
---
id: theme-bootstrap
title: '📦 theme-bootstrap'
slug: '/api/themes/@docusaurus/theme-bootstrap'
---
:::danger
The bootstrap theme is a work in progress, and is not production ready.
:::
🚧 The bootstrap theme for Docusaurus.
You can refer to the [theme configuration page](theme-configuration.md) for more details on the configuration.
```bash npm2yarn
npm install --save @docusaurus/theme-bootstrap
```
:::tip
If you have installed `@docusaurus/preset-bootstrap`, you don't need to install it as a dependency.
:::

19
website/versioned_docs/version-2.0.0-alpha.75/api/themes/theme-classic.md Normal file
View file

@ -0,0 +1,19 @@
---
id: theme-classic
title: '📦 theme-classic'
slug: '/api/themes/@docusaurus/theme-classic'
---
The classic theme for Docusaurus.
You can refer to the [theme configuration page](theme-configuration.md) for more details on the configuration.
```bash npm2yarn
npm install --save @docusaurus/theme-classic
```
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::

575
website/versioned_docs/version-2.0.0-alpha.75/api/themes/theme-configuration.md Normal file
View file

@ -0,0 +1,575 @@
---
id: theme-configuration
title: 'Theme configuration'
slug: '/api/themes/configuration'
---
This configuration applies to all [main themes](./overview.md).
## Common {#common}
### Color mode - dark mode {#color-mode---dark-mode}
The classic theme provides by default light and dark mode support, with a navbar switch for the user.
It is possible to customize the color mode support with the following configuration:
```js {6-35} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// ...
colorMode: {
// "light" | "dark"
defaultMode: 'light',
// Hides the switch in the navbar
// Useful if you want to support a single color mode
disableSwitch: false,
// Should we use the prefers-color-scheme media-query,
// using user system preferences, instead of the hardcoded defaultMode
respectPrefersColorScheme: false,
// Dark/light switch icon options
switchConfig: {
// Icon for the switch while in dark mode
darkIcon: '🌙',
// CSS to apply to dark icon,
// React inline style object
// see https://reactjs.org/docs/dom-elements.html#style
darkIconStyle: {
marginLeft: '2px',
},
// Unicode icons such as '\u2600' will work
// Unicode with 5 chars require brackets: '\u{1F602}'
lightIcon: '\u{1F602}',
lightIconStyle: {
marginLeft: '1px',
},
},
},
// ...
},
// ...
};
```
:::caution
With `respectPrefersColorScheme: true`, the `defaultMode` is overridden by user system preferences.
If you only want to support one color mode, you likely want to ignore user system preferences.
:::
### Meta image {#meta-image}
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
```js {4-6} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// Relative to your site's "static" directory.
// Cannot be SVGs. Can be external URLs too.
image: 'img/docusaurus.png',
// ...
},
};
```
### Metadatas {#metadatas}
You can configure additional html metadatas (and override existing ones).
```js {4} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
metadatas: [{name: 'twitter:card', content: 'summary'}],
// ...
},
};
```
### Announcement bar {#announcement-bar}
Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar.
```js {4-11} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
announcementBar: {
id: 'support_us', // Any value that will identify this message.
content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc', // Defaults to `#fff`.
textColor: '#091E42', // Defaults to `#000`.
isCloseable: false, // Defaults to `true`.
},
// ...
},
};
```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `N/A
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
```
## Hooks {#hooks}
### `useThemeContext` {#usethemecontext}
React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
```
:::note
The component calling `useThemeContext` must be a child of the `Layout` component.
```jsx
function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}
```
:::
## Navbar {#navbar}
### Navbar title & logo {#navbar-title--logo}
You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.
To improve dark mode support, you can also set a different logo for this mode.
```js {5-11} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
title: 'Site Title',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
srcDark: 'img/logo_dark.svg', // Default to `logo.src`.
href: 'https://docusaurus.io/', // Default to `siteConfig.baseUrl`.
target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one).
},
},
// ...
},
};
```
### Navbar items {#navbar-items}
You can add items to the navbar via `themeConfig.navbar.items`.
By default, Navbar items are regular links (internal or external).
```js title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
// highlight-start
items: [
{
// Client-side routing, used for navigating within the website.
// The baseUrl will be automatically prepended to this value.
to: 'docs/introduction',
// A full-page navigation, used for navigating outside of the website.
// You should only use either `to` or `href`.
href: 'https://www.facebook.com',
// Prepends the baseUrl to href values.
prependBaseUrlToHref: true,
// The string to be shown.
label: 'Introduction',
// Left or right side of the navbar.
position: 'left', // or 'right'
// To apply the active class styling on all
// routes starting with this path.
// This usually isn't necessary
activeBasePath: 'docs',
// Alternative to activeBasePath if required.
activeBaseRegex: 'docs/(next|v8)',
// Custom CSS class (for styling any item).
className: '',
},
// ... other items
],
// highlight-end
},
// ...
},
};
```
React Router should automatically apply active link styling to links, but you can use `activeBasePath` in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use `activeBaseRegex`. `activeBaseRegex` is a more flexible alternative to `activeBasePath` and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.
Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes.
### Navbar dropdown {#navbar-dropdown}
Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items.
```js {9-19} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
items: [
{
label: 'Community',
position: 'left', // or 'right'
items: [
{
label: 'Facebook',
href: '...',
},
{
label: 'GitHub',
href: '...',
},
// ... more items
],
},
],
},
// ...
},
};
```
### Navbar doc link {#navbar-doc-link}
If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar.
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'doc',
docId: 'introduction',
//// Optional
position: 'left',
label: 'Docs',
activeSidebarClassName: 'navbar__link--active',
docsPluginId: 'default',
},
// highlight-end
],
},
},
};
```
### Navbar docs version dropdown {#navbar-docs-version-dropdown}
If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.
The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).
```js {5-8} title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
//// Optional
position: 'left',
// Add additional dropdown items at the beginning/end of the dropdown.
dropdownItemsBefore: [],
dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
// Do not add the link active class when browsing docs.
dropdownActiveClassDisabled: true,
docsPluginId: 'default',
},
],
},
},
};
```
### Navbar docs version {#navbar-docs-version}
If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version.
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'docsVersion',
//// Optional
position: 'left',
to: '/path', // by default, link to active/latest version
label: 'label', // by default, show active/latest version label
docsPluginId: 'default',
},
// highlight-end
],
},
},
};
```
### Navbar locale dropdown {#navbar-locale-dropdown}
If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales.
The user will be able to switch from one locale to another, while staying on the same page.
```js {5-8} title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
//// Optional
position: 'left',
// Add additional dropdown items at the beginning/end of the dropdown.
dropdownItemsBefore: [],
dropdownItemsAfter: [
{
to: 'https://my-site.com/help-us-translate',
label: 'Help us translate',
},
],
},
],
},
},
};
```
### Navbar search {#navbar-search}
If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar.
However, with this special navbar item type, you can change the default location.
```js {5-8} title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};
```
### Auto-hide sticky navbar {#auto-hide-sticky-navbar}
You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
```js {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
hideOnScroll: true,
},
// ...
},
};
```
### Navbar style {#navbar-style}
You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.
Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/).
```js {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
navbar: {
style: 'primary',
},
// ...
},
};
```
<!--
## Footer {#footer}
TODO.
-->
## CodeBlock {#codeblock}
Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks.
### Theme {#theme}
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.
```js {5-6} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'),
},
// ...
},
};
```
:::note
If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting).
:::
### Default language {#default-language}
You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.:
```js {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
// ...
},
};
```
## Footer {#footer-1}
You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo.
```js {5-15} title="docusaurus.config.js"
// ...
footer: {
logo: {
alt: 'Facebook Open Source Logo',
src: 'img/oss_logo.png',
href: 'https://opensource.facebook.com',
},
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
}
```
## Footer Links {#footer-links}
You can add links to the footer via `themeConfig.footer.links`:
```js {5-15} title="docusaurus.config.js"
module.exports = {
// ...
footer: {
links: [
{
// Label of the section of these links
title: 'Docs',
items: [
{
// Label of the link
label: 'Style Guide',
// Client-side routing, used for navigating within the website.
// The baseUrl will be automatically prepended to this value.
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/doc2/',
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
// A full-page navigation, used for navigating outside of the website.
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
{
//Renders the html pass-through instead of a simple link
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" />
</a>
`,
},
],
},
],
},
};
```

28
website/versioned_docs/version-2.0.0-alpha.75/api/themes/theme-live-codeblock.md Normal file
View file

@ -0,0 +1,28 @@
---
id: theme-live-codeblock
title: '📦 theme-live-codeblock'
slug: '/api/themes/@docusaurus/theme-live-codeblock'
---
This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](../../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor) documentation.
```bash npm2yarn
npm install --save @docusaurus/theme-live-codeblock
```
### Configuration {#configuration}
```jsx title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/theme-live-codeblock'],
themeConfig: {
liveCodeBlock: {
/**
* The position of the live playground, above or under the editor
* Possible values: "top" | "bottom"
*/
playgroundPosition: 'bottom',
},
},
};
```

19
website/versioned_docs/version-2.0.0-alpha.75/api/themes/theme-search-algolia.md Normal file
View file

@ -0,0 +1,19 @@
---
id: theme-search-algolia
title: '📦 theme-search-algolia'
slug: '/api/themes/@docusaurus/theme-search-algolia'
---
This theme provides a `@theme/SearchBar` component that integrates with Algolia DocSearch easily. Combined with `@docusaurus/theme-classic`, it provides a very easy search integration. You can read more on [search](../../search.md) documentation.
```bash npm2yarn
npm install --save @docusaurus/theme-search-algolia
```
This theme also adds search page available at `/search` (as swizzleable `SearchPage` component) path with OpenSearch support.
:::tip
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
:::

BIN
website/versioned_docs/version-2.0.0-alpha.75/assets/docusaurus-asset-example-banner.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 68 KiB

BIN
website/versioned_docs/version-2.0.0-alpha.75/assets/docusaurus-asset-example-pdf.pdf Normal file
View file

Binary file not shown.

BIN
website/versioned_docs/version-2.0.0-alpha.75/assets/docusaurus-asset-example.xyz Normal file
View file

Binary file not shown.

222
website/versioned_docs/version-2.0.0-alpha.75/blog.md Normal file
View file

@ -0,0 +1,222 @@
---
id: blog
title: Blog
---
## Initial setup {#initial-setup}
To setup your site's blog, start by creating a `blog` directory.
Then, add an item link to your blog within `docusaurus.config.js`:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
// highlight-next-line
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
```
## Adding posts {#adding-posts}
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name.
For example, at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
```yml
---
title: Welcome Docusaurus v2
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://docusaurus.io/).
<!--truncate-->
This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
```
## Header options {#header-options}
The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options.
- `author` - The author name to be displayed.
- `author_url` - The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc.
- `author_image_url` - The URL to the author's thumbnail image.
- `author_title` - A description of the author.
- `title` - The blog post title.
- `tags` - A list of strings to tag to your post.
- `draft` - A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development.
- `description`: The description of your post, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. If this field is not present, it will default to the first line of the contents.
- `image`: Cover or thumbnail image that will be used when displaying the link to your post.
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`.
## Summary truncation {#summary-truncation}
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
```yml
---
title: Truncation Example
---
All these will be part of the blog post summary.
Even this.
<!--truncate-->
But anything from here on down will not be.
Not this.
Or this.
```
## Feed {#feed}
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
```ts
feedOptions?: {
type?: 'rss' | 'atom' | 'all' | null;
title?: string;
description?: string;
copyright: string;
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
};
```
Example usage:
```js {8-11} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
},
},
],
],
};
```
Accessing the feed:
The feed for RSS can be found at:
```text
https://{your-domain}/blog/rss.xml
```
and for Atom:
```text
https://{your-domain}/blog/atom.xml
```
## Advanced topics {#advanced-topics}
### Blog-only mode {#blog-only-mode}
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
```js {9} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false,
blog: {
path: './blog',
routeBasePath: '/', // Set this value to '/'.
},
},
],
],
};
```
:::caution
Don't forget to delete the existing homepage at `./src/pages/index.js` or else there will be two files mapping to the same route!
:::
You can also add meta description to the blog list page for better SEO:
```js {8} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A docusaurus powered blog!',
},
},
],
],
};
```
### Multiple blogs {#multiple-blogs}
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.
Set the `routeBasePath` to the URL route that you want your second blog to be accessed on. Note that the `routeBasePath` here has to be different from the first blog or else there could be a collision of paths! Also, set `path` to the path to the directory containing your second blog's entries.
As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique id to the plugins.
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Required for any multi-instance plugin
*/
id: 'second-blog',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'my-second-blog',
/**
* Path to data on filesystem relative to site dir.
*/
path: './my-second-blog',
},
],
],
};
```
As an example, we host a second blog [here](/second-blog).

188
website/versioned_docs/version-2.0.0-alpha.75/cli.md Normal file
View file

@ -0,0 +1,188 @@
---
id: cli
---
# CLI
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:
```json title="package.json"
{
// ...
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
}
}
```
## Index {#index}
import TOCInline from "@theme/TOCInline"
<TOCInline toc={toc[1].children}/>
## Docusaurus CLI commands {#docusaurus-cli-commands}
Below is a list of Docusaurus CLI commands and their usages:
### `docusaurus start [siteDir]` {#docusaurus-start-sitedir}
Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
#### Options {#options}
| Name | Default | Description |
| --- | --- | --- |
| `--port` | `3000` | Specifies the port of the dev server. |
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
| `--no-open` | `false` | Do not open automatically the page in the browser. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
:::important
Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.
:::
#### Enabling HTTPS` {#enabling-https}
There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example.
1. Run `mkcert localhost` to generate `localhost.pem` + `localhost-key.pem`
2. Run `mkcert -install` to install the cert in your trust store, and restart your browser
3. Start the app with Docusaurus HTTPS env variables:
```shell
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
```
4. Open `https://localhost:3000/`
### `docusaurus build [siteDir]` {#docusaurus-build-sitedir}
Compiles your site for production.
#### Options {#options-1}
| Name | Default | Description |
| --- | --- | --- |
| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). |
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
:::info
For advanced minification of CSS bundle, we use the [advanced cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-advanced) (along with additional several PostCSS plugins) and [level 2 optimization of clean-css](https://github.com/jakubpawlowicz/clean-css#level-2-optimizations). If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable `USE_SIMPLE_CSS_MINIFIER=true` to minify CSS with the [default cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-default). **Please [fill out an issue](https://github.com/facebook/docusaurus/issues/new?labels=bug%2C+needs+triage&template=bug.md) if you experience CSS minification bugs.**
:::
### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
:::caution
We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
:::
Change any Docusaurus theme components to your liking with `npm run swizzle`.
```bash npm2yarn
npm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic DocSidebar
```
Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle <themeName>` without `componentName` lists all the components available for swizzling.
#### Options {#options-2}
| Name | Description |
| ------------------ | -------------------------------------- |
| `themeName` | The name of the theme you are using. |
| `swizzleComponent` | The name of the component to swizzle. |
| `--danger` | Allow swizzling of unstable components |
| `--typescript` | Swizzle TypeScript components |
An example to use `--danger` flag let's consider the below code:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Logo -- --danger
```
:::caution
Unstable Components: components that have a higher risk of breaking changes due to internal refactorings.
:::
To unswizzle a component, simply delete the files of the swizzled component.
<!--
TODO a separate section for swizzle tutorial.
To learn more about swizzling, check [here](#).
-->
### `docusaurus deploy [siteDir]` {#docusaurus-deploy-sitedir}
Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details.
#### Options {#options-3}
| Name | Default | Description |
| --- | --- | --- |
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
| `--skip-build` | `false` | Deploy website without building it. This may be useful when using custom deploy script. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
Serve your built website locally.
| Name | Default | Description |
| --- | --- | --- |
| `--port` | `3000` | Use specified port |
| `--dir` | `build` | The full path for the output directory, relative to the current workspace |
| `--build` | `false` | Build website before serving |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
### `docusaurus clear [siteDir]` {#docusaurus-clear-sitedir}
Clear a Docusaurus site's generated assets, caches, build artifacts.
We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.
### `docusaurus write-translations [siteDir]` {#docusaurus-write-translations-sitedir}
Write the JSON translation files that you will have to translate.
By default, the files are written in `website/i18n/<defaultLocale>/...`.
| Name | Default | Description |
| --- | --- | --- |
| `--locale` | `<defaultLocale>` | Define which locale folder you want to write translations the JSON files in |
| `--override` | `false` | Override existing translation messages |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--messagePrefix` | `''` | Allows to add a prefix to each translation message, to help you highlight untranslated strings |
### `docusaurus write-heading-ids [siteDir]` {#docusaurus-write-heading-ids-sitedir}
Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.

161
website/versioned_docs/version-2.0.0-alpha.75/configuration.md Normal file
View file

@ -0,0 +1,161 @@
---
id: configuration
title: Configuration
---
import TOCInline from '@theme/TOCInline';
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site.
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site.
## What goes into a `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs}
You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options.
However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.
The high-level overview of Docusaurus configuration can be categorized into:
<TOCInline toc={toc[0].children} />
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
### Site metadata {#site-metadata}
Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl` and `favicon`.
They are used in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.
### Deployment configurations {#deployment-configurations}
Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command.
It is recommended to check the [deployment docs](deployment.mdx) for more information.
### Theme, plugin, and preset configurations {#theme-plugin-and-preset-configurations}
List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
```
They can also be loaded from local directories:
```js title="docusaurus.config.js"
const path = require('path');
module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
```
To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'@docusaurus/plugin-content-pages',
],
};
```
To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`.
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
```
For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
### Custom configurations {#custom-configurations}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`.
Example:
```js title="docusaurus.config.js"
module.exports = {
// ...
// highlight-start
customFields: {
image: '',
keywords: [],
},
// highlight-end
// ...
};
```
## Accessing configuration from components {#accessing-configuration-from-components}
Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`.
Basic example:
```jsx
import React from 'react';
// highlight-next-line
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
// highlight-start
const {siteConfig} = useDocusaurusContext();
// highlight-end
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
```
:::tip
If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`.
:::
## Customizing Babel Configuration {#customizing-babel-configuration}
For new Docusaurus projects, we automatically generated a `babel.config.js` in project root.
```js title="babel.config.js"
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
```
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.

190
website/versioned_docs/version-2.0.0-alpha.75/contributing.md Normal file
View file

@ -0,0 +1,190 @@
---
id: contributing
title: Contributing
---
[Docusaurus 2](https://docusaurus.io/) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus.
The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Building Welcoming Communities](https://opensource.guide/building-community/)
## [Code of Conduct](https://code.fb.com/codeofconduct) {#code-of-conduct}
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
## Get involved {#get-involved}
There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:
- Start using Docusaurus 2! Go through the [Getting Started](installation.md) guides. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
- Look through the [v2.0 issues](https://github.com/facebook/docusaurus/labels/v2). If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started.
- Help us making the docs better. File an issue if you find anything that is confusing or can be improved. We also have [an umbrella issue for v2 docs](https://github.com/facebook/docusaurus/issues/1640) where we are planning and working on all v2 docs. You may adopt a doc piece there to work on.
- Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on.
Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
### Join our Discord channel {#join-our-discord-channel}
To participate in Docusaurus 2 dev, join the [#docusaurus-2-dev](https://discord.gg/Je6Ash6) channel.
## Our development process {#our-development-process}
Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning.
When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.
### Reporting new issues {#reporting-new-issues}
When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
- **One issue, one bug:** Please report a single bug per issue.
- **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
### Reporting bugs {#reporting-bugs}
We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you a are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions.
You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=feature%2C+needs+triage&template=feature.md)
### Reporting security bugs {#reporting-security-bugs}
Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
## Working on Docusaurus code {#working-on-docusaurus-code}
### Installation {#installation}
1. Ensure you have [Yarn](https://yarnpkg.com/) installed
2. After cloning the repository, run `yarn install` in the root of the repository
3. To start a local development server serving the Docusaurus docs, go into the `website` directory and run `yarn start`
### Semantic commit messages {#semantic-commit-messages}
See how a minor change to your commit message style can make you a better programmer.
Format: `<type>(<scope>): <subject>`
`<scope>` is optional
**Example**
```
feat: allow overriding of webpack config
^--^ ^------------^
| |
| +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.
```
The various types of commits:
- `feat`: (new feature for the user, not a new feature for build script)
- `fix`: (bug fix for the user, not a fix to a build script)
- `docs`: (changes to the documentation)
- `style`: (formatting, missing semi colons, etc; no production code change)
- `refactor`: (refactoring production code, eg. renaming a variable)
- `test`: (adding missing tests, refactoring tests; no production code change)
- `chore`: (updating grunt tasks etc; no production code change)
Use lower case not title case!
### Code conventions {#code-conventions}
#### Style guide {#style-guide}
[Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`.
However, there are still some styles that Prettier cannot pick up.
#### General {#general}
- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation.
- "Attractive"
#### Documentation {#documentation}
- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
## Pull requests {#pull-requests}
### Your first pull request {#your-first-pull-request}
So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
Working on your first Pull Request? You can learn how from this free video series:
[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
We have a list of [beginner friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.
### Proposing a change {#proposing-a-change}
If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=feature%2C+needs+triage&template=feature.md).
If you intend to change the public API (e.g., something in `docusaurus.config.js`), or make any non-trivial changes to the implementation, we recommend filing an issue with [proposal template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=proposal%2C+needs+triage&template=proposal.md) and including `[Proposal]` in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
### Sending a pull request {#sending-a-pull-request}
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages).
Please make sure the following is done when submitting a pull request:
1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `master`.
1. Add the copyright notice to the top of any code new files you've added.
1. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md/)!
1. Make sure your code lints (`yarn prettier && yarn lint`).
1. Make sure your Jest tests pass (`yarn test`).
1. If you haven't already, [sign the CLA](https://code.facebook.com/cla).
All pull requests should be opened against the `master` branch.
#### Test plan {#test-plan}
A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI.
- If you've changed APIs, update the documentation.
#### Breaking changes {#breaking-changes}
When adding a new breaking change, follow this template in your pull request:
```md
### New breaking change here
- **Who does this affect**:
- **How to migrate**:
- **Why make this breaking change**:
- **Severity (number of people affected x effort)**:
```
#### Copyright header for source code {#copyright-header-for-source-code}
Copy and paste this to the top of your new file(s):
```js
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
```
#### Contributor License Agreement (CLA) {#contributor-license-agreement-cla}
In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
### What happens next? {#what-happens-next}
The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
## License {#license}
By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.

492
website/versioned_docs/version-2.0.0-alpha.75/deployment.mdx Normal file
View file

@ -0,0 +1,492 @@
---
id: deployment
title: Deployment
---
To build the static files of your website for production, run:
```bash npm2yarn
npm run build
```
Once it finishes, the static files will be generated within the `build/` directory.
You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too!
## Testing Build Local {#testing-build-local}
It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally.
```bash npm2yarn
npm run serve
```
## Self Hosting {#self-hosting}
:::warning
It is not the most performant solution
:::
Docusaurus can be self hosted using [`docusaurus serve`](cli.md#docusaurus-serve). Change port using `--port` and `--host` to change host.
```bash npm2yarn
npm run serve -- --build --port 80 --host 0.0.0.0
```
## Deploying to GitHub Pages {#deploying-to-github-pages}
Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
First, modify your `docusaurus.config.js` and add the required params:
| Name | Description |
| --- | --- |
| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. |
| `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". |
| `url` | URL for your GitHub Page's user/organization page. This is commonly https://_username_.github.io. |
| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
:::info
In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment.
You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details.
:::
Example:
```jsx {3-6} title="docusaurus.config.js"
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
// ...
};
```
:::warning
By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory.
:::
### Environment settings {#environment-settings}
Specify the Git user as an environment variable.
| Name | Description |
| --- | --- |
| `GIT_USER` | The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. |
Optional parameters, also set as environment variables:
| Name | Description |
| --- | --- |
| `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. |
| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages` for normal repos and `master` for repository names ending in `github.io`. |
| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
| `GIT_PASS` | Password (or token) of the `git` user (specified by `GIT_USER`). For example, to facilitate non-interactive deployment (e.g. continuous deployment) |
GitHub enterprise installations should work in the same manner as github.com; you only need to set the organization's GitHub Enterprise host as an environment variable:
| Name | Description |
| ------------- | ----------------------------------------------- |
| `GITHUB_HOST` | The domain name of your GitHub enterprise site. |
| `GITHUB_PORT` | The port of your GitHub enterprise site. |
### Deploy {#deploy}
Finally, to deploy your site to GitHub Pages, run:
````mdx-code-block
<Tabs
defaultValue="bash"
values={[
{ label: 'Bash', value: 'bash' },
{ label: 'Windows', value: 'windows' },
{ label: 'PowerShell', value: 'powershell' }
]}>
<TabItem value="bash">
```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy
```
</TabItem>
<TabItem value="windows">
```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
```
</TabItem>
<TabItem value="powershell">
```powershell
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
```
</TabItem>
</Tabs>
````
### Triggering deployment with GitHub Actions {#triggering-deployment-with-github-actions}
[GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
This workflow assumes your documentation resided in `documentation` branch of your repository and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for `gh-pages` branch.
1. Generate a new [SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
1. By default, your public key should have been created in `~/.ssh/id_rsa.pub` or use the name you've provided in the previous step to add your key to [GitHub deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/).
1. Copy key to clipboard with `xclip -sel clip < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in your repository. Copy file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key.
1. You'll need your private key as a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to allow Docusaurus to run the deployment for you.
1. Copy your private key with `xclip -sel clip < ~/.ssh/id_rsa` and paste a GitHub secret with name `GH_PAGES_DEPLOY`. Copy file content if the command line doesn't work for you. Save your secret.
1. Create you [documentation workflow file](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#creating-a-workflow-file) in `.github/workflows/`. In this example it's `documentation.yml`.
```yaml title="documentation.yml"
name: documentation
on:
pull_request:
branches: [documentation]
push:
branches: [documentation]
jobs:
checks:
if: github.event_name != 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: actions/setup-node@v1
with:
node-version: '12.x'
- name: Test Build
run: |
if [ -e yarn.lock ]; then
yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
npm ci
else
npm i
fi
npm run build
gh-release:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: actions/setup-node@v1
with:
node-version: '12.x'
- uses: webfactory/ssh-agent@v0.5.0
with:
ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
- name: Release to GitHub Pages
env:
USE_SSH: true
GIT_USER: git
run: |
git config --global user.email "actions@github.com"
git config --global user.name "gh-actions"
if [ -e yarn.lock ]; then
yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
npm ci
else
npm i
fi
npm run deploy
```
1. Now when a new pull request arrives towards your repository in branch `documentation` it will automatically ensure that Docusaurus build is successful.
1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch.
1. After this step, your updated documentation will be available on the GitHub pages.
### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). When creating the token, grant it the `repo` scope so that it has the permissions it needs.
1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
1. Open your Travis CI dashboard. The URL looks like `https://travis-ci.com/USERNAME/REPO`, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
1. Create a `.travis.yml` on the root of your repository with the following:
```yaml title=".travis.yml"
language: node_js
node_js:
- '10'
branches:
only:
- master
cache:
yarn: true
script:
- git config --global user.name "${GH_NAME}"
- git config --global user.email "${GH_EMAIL}"
- echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
- yarn && GIT_USER="${GH_NAME}" yarn deploy
```
Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
### Using Azure Pipelines {#using-azure-pipelines}
1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
1. Create an organization and within the organization create a project and connect your repository from GitHub.
1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `repo` scope.
1. In the project page (which looks like `https://dev.azure.com/ORG_NAME/REPO_NAME/_build` create a new pipeline with the following text. Also, click on edit and add a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named `azure-pipelines.yml` at your repository root.
```yaml title="azure-pipelines.yml"
trigger:
- master
pool:
vmImage: 'ubuntu-latest'
steps:
- checkout: self
persistCredentials: true
- task: NodeTool@0
inputs:
versionSpec: '10.x'
displayName: 'Install Node.js'
- script: |
git config --global user.name "${GH_NAME}"
git config --global user.email "${GH_EMAIL}"
git checkout -b master
echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
yarn && GIT_USER="${GH_NAME}" yarn deploy
env:
GH_NAME: $(GH_NAME)
GH_EMAIL: $(GH_EMAIL)
GH_TOKEN: $(GH_TOKEN)
displayName: 'yarn install and build'
```
### Using Drone {#using-drone}
1. Create a new ssh key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project.
1. Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
1. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in our public key you just generated.
1. Open your Drone.io dashboard and login. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
1. Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated.
1. Create a `.drone.yml` on the root of your repository with below text.
```yaml
# .drone.yml
kind: pipeline
type: docker
trigger:
event:
- tag
- name: Website
image: node
commands:
- mkdir -p $HOME/.ssh
- ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
- echo "$GITHUB_PRIVATE_KEY > $HOME/.ssh/id_rsa"
- chmod 0600 $HOME/.ssh/id_rsa
- cd website
- npm i
- npm run publish-gh-pages
environment:
USE_SSH: true
GIT_USER: $DRONE_COMMIT_AUTHOR
GITHUB_PRIVATE_KEY: git_deploy_private_key
```
Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.
## Deploying to Netlify {#deploying-to-netlify}
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"
module.exports = {
url: 'https://docusaurus-2.netlify.com', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// ...
};
```
Then, [create your site with Netlify](https://app.netlify.com/start).
While you set up the site, specify the build commands and directories as follows:
- build command: `npm run build`
- build directory: `build`
If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created.
Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `master`.
:::important
Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, unnecessary redirects and 404 errors.
:::
## Deploying to Vercel {#deploying-to-vercel}
Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use.
To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository.
Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings).
After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production).
## Deploying to Render {#deploying-to-render}
[Render](https://render.com) offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto-deploy from your Git repo. Get started in just a few minutes by following [Render's guide to deploying Docusaurus](https://render.com/docs/deploy-docusaurus).
## Deploying to Qovery {#deploying-to-qovery}
[Qovery](https://qovery.com) is a fully-managed cloud platform that runs on your AWS, GCP, Azure and Digital Ocean account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place.
1. Create a Qovery account.
Visit the [Qovery dashboard](https://console.qovery.com) to create an account if you don't already have one.
2. Create a project
Click on "Create a new project" and give a name to your project.
Click on "Next".
3. Add an application
Click on "Create an application" then choose "I have an application" and select your GitHub or GitLab repository where your app is located.
Click on "Next".
Skip adding services
4. Deploy
Click on "Deploy".
You can see the status in real time by clicking on deployment logs.
## Deploying to Hostman {#deploying-to-hostman}
[Hostman](https://hostman.com/) allows you to host static websites for free. Hostman automates everything, you just need to connect your repository and follow easy steps:
1. Create a service
To deploy a Docusaurus static website, click Create in the top-left corner of your [Dashboard](https://dashboard.hostman.com/) and choose Front-end app or static website.
2. Select the project to deploy
If you are logged in to Hostman with your GitHub, GitLab or Bitbucket account, at this point you will see the repository with your projects, including the private ones.
Choose the project you want to deploy. It must contain the directory with the project’s files (usually it is website or my-website).
To access a different repository, click Connect another repository.
If you didn’t use your Git account credentials to log in, you’ll be able to access the necessary account now, and then select the project.
3. Configure the build settings Next, the Website customization window will appear.
Choose the Static website option from the list of frameworks.
The Directory with app points at the directory that will contain the project's files after the build. You can leave it empty if during Step 2 you selected the repository with the contents of the website (or my_website) directory.
The standard build command for Docusaurus will be:
```bash
yarn run build
```
You can modify the build command if needed. You can enter multiple commands separated by &&.
4. Deploy Click Deploy to start the build process.
Once it starts, you will enter the deployment log. If there are any issues with the code, you will get warning or error messages in the log, specifying the cause of the problem.
Usually the log contains all the debugging data you'll need, but we are also here to help you solve the issues, so do not hesitate to contact us via chat.
When the deployment is complete, you will receive an e-mail notification and also see a log entry.
All done!
Your project is up and ready.
## Deploying to Surge {#deploying-to-surge}
Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).
Deploy your app in a matter of seconds using surge with the following steps:
1. First, install Surge using npm by running the following command:
```bash
npm install --g surge
```
2. To build the static files of your site for production in the root directory of your project, run:
```bash
npm run build
```
3. Then, run this command inside the root directory of your project:
```bash
surge build/
```
First-time users of Surge would be prompted to create an account from the command line(happens only once).
Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given (which can be edited).
### Using your domain {#using-your-domain}
If you have a domain name you can deploy your site using surge to your domain using the command:
```bash
surge build/ yourdomain.com
```
Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose.
### Setting up CNAME file {#setting-up-cname-file}
Store your domain in a CNAME file for future deployments with the following command:
```bash
echo subdomain.surge.sh > CNAME
```
You can deploy any other changes in the future with the command `surge`.
## Deploying to QuantCDN {#deploying-to-quantcdn}
1. Install [Quant CLI](https://docs.quantcdn.io/docs/cli/get-started)
2. Create a QuantCDN account by [signing up](https://dashboard.quantcdn.io/register)
3. Initialize your project with `quant init` and fill in your credentials:
```bash
quant init
```
4. Deploy your site
```bash
quant deploy
```
See [docs](https://docs.quantcdn.io/docs/cli/continuous-integration) and [blog](https://www.quantcdn.io/blog) for more examples and use cases for deploying to QuantCDN.

34
website/versioned_docs/version-2.0.0-alpha.75/design-principles.md Normal file
View file

@ -0,0 +1,34 @@
---
id: design-principles
title: Design Principles
---
:::caution
This section is a work in progress.
:::
- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
- **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
- **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users.
## How Docusaurus works {#how-docusaurus-works}
<!-- moved in from how Docusaurus works @yangshun -->
We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
<!--
Explain the principles that guide the development of Docusaurus.
References
---
- https://www.gatsbyjs.org/docs/behind-the-scenes/
- https://reactjs.org/docs/design-principles.html
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
-->

540
website/versioned_docs/version-2.0.0-alpha.75/docusaurus-core.md Normal file
View file

@ -0,0 +1,540 @@
---
id: docusaurus-core
title: Docusaurus Client API
sidebar_label: Client API
---
Docusaurus provides some APIs on the clients that can be helpful to you when building your site.
## Components {#components}
### `<Head/>` {#head}
This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet).
Usage Example:
```jsx {2,5,10}
import React from 'react';
import Head from '@docusaurus/Head';
const MySEO = () => (
<Head>
<meta property="og:description" content="My custom description" />
<meta charSet="utf-8" />
<title>My Title</title>
<link rel="canonical" href="http://mysite.com/example" />
</Head>
);
```
Nested or latter components will override duplicate usages:
```jsx {2,5,8,11}
<Parent>
<Head>
<title>My Title</title>
<meta name="description" content="Helmet application" />
</Head>
<Child>
<Head>
<title>Nested Title</title>
<meta name="description" content="Nested component" />
</Head>
</Child>
</Parent>
```
Outputs:
```html
<head>
<title>Nested Title</title>
<meta name="description" content="Nested component" />
</head>
```
### `<Link/>` {#link}
This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `<Link>` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.
The component is a wrapper around react-router’s `<Link>` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `<Link>` component.
```jsx {2,7}
import React from 'react';
import Link from '@docusaurus/Link';
const Page = () => (
<div>
<p>
Check out my <Link to="/blog">blog</Link>!
</p>
<p>
{/* Note that external links still use `a` tags, but automatically opens in new tab. */}
Follow me on <a href="https://twitter.com/docusaurus">Twitter</a>!
</p>
</div>
);
```
#### `to`: string {#to-string}
The target location to navigate to. Example: `/docs/introduction`.
```jsx
<Link to="/courses" />
```
### `<Redirect/>` {#redirect}
Rendering a `<Redirect>` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props.
Example usage:
```jsx {2,5}
import React from 'react';
import {Redirect} from '@docusaurus/router';
const Home = () => {
return <Redirect to="/docs/test" />;
};
```
:::note
`@docusaurus/router` implements [React Router](https://reacttraining.com/react-router/web/guides/quick-start) and supports its features.
:::
### `<BrowserOnly/>` {#browseronly}
The `<BrowserOnly>` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser.
```jsx {1,5-10}
import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {
return (
<BrowserOnly
fallback={<div>The fallback content to display on prerendering</div>}>
{() => {
// Something that should be excluded during build process prerendering.
}}
</BrowserOnly>
);
};
```
### `<Interpolate/>` {#interpolate}
A simple interpolation component for text containing dynamic placeholders.
The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...).
#### Props {#props}
- `children`: text containing interpolation placeholders like `{placeholderName}`
- `values`: object containing interpolation placeholder values
```jsx
import React from 'react';
import Link from '@docusaurus/Link';
import Interpolate from '@docusaurus/Interpolate';
export default function VisitMyWebsiteMessage() {
return (
// highlight-start
<Interpolate
values={{
firstName: 'Sébastien',
website: (
<Link to="https://docusaurus.io" className="my-website-class">
website
</Link>
),
}}>
{'Hello, {firstName}! How are you? Take a look at my {website}'}
</Interpolate>
// highlight-end
);
}
```
### `<Translate/>` {#translate}
When [localizing your site](./i18n/i18n-introduction.md), the `<Translate/>` component will allow providing **translation support to React components**, such as your homepage. The `<Translate>` component supports [interpolation](#interpolate).
The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations) CLI and create a `code.json` translation file in `website/i18n/<locale>`.
:::note
The `<Translate/>` props **must be hardcoded strings**.
Apart the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work.
:::
#### Props {#props-1}
- `children`: untranslated string in the default site locale (can contain [interpolation placeholders](#interpolate))
- `id`: optional value to use as key in JSON translation files
- `description`: optional text to help the translator
- `values`: optional object containing interpolation placeholder values
#### Example {#example}
```jsx title="src/pages/index.js"
import React from 'react';
import Layout from '@theme/Layout';
// highlight-start
import Translate from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout>
<h1>
{/* highlight-start */}
<Translate
id="homepage.title"
description="The homepage welcome message">
Welcome to my website
</Translate>
{/* highlight-end */}
</h1>
<main>
{/* highlight-start */}
<Translate values={{firstName: 'Sébastien'}}>
{'Welcome, {firstName}! How are you?'}
</Translate>
{/* highlight-end */}
</main>
</Layout>
);
}
```
## Hooks {#hooks}
### `useDocusaurusContext` {#usedocusauruscontext}
React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata.
```ts
type DocusaurusPluginVersionInformation =
| {readonly type: 'package'; readonly version?: string}
| {readonly type: 'project'}
| {readonly type: 'local'}
| {readonly type: 'synthetic'};
interface DocusaurusSiteMetadata {
readonly docusaurusVersion: string;
readonly siteVersion?: string;
readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
}
interface DocusaurusContext {
siteConfig: DocusaurusConfig;
siteMetadata: DocusaurusSiteMetadata;
}
```
Usage example:
```jsx {5,8-10}
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const MyComponent = () => {
const {siteConfig, siteMetadata} = useDocusaurusContext();
return (
<div>
<h1>{siteConfig.title}</h1>
<div>{siteMetadata.siteVersion}</div>
<div>{siteMetadata.docusaurusVersion}</div>
</div>
);
};
```
### `useBaseUrl` {#usebaseurl}
React hook to prepend your site `baseUrl` to a string.
:::caution
**Don't use it for regular links!**
The `/baseUrl/` prefix is automatically added to all **absolute paths** by default:
- Markdown: `[link](/my/path)` will link to `/baseUrl/my/path`
- React: `<Link to="/my/path/">link</Link>` will link to `/baseUrl/my/path`
:::
#### Options {#options}
```ts
type BaseUrlOptions = {
forcePrependBaseUrl: boolean;
absolute: boolean;
};
```
#### Example usage: {#example-usage}
```jsx
import React from 'react';
import useBaseUrl from '@docusaurus/useBaseUrl';
const SomeImage = () => {
// highlight-start
const imgSrc = useBaseUrl('/img/myImage.png');
// highlight-end
return <img src={imgSrc} />;
};
```
:::tip
In most cases, you don't need `useBaseUrl`.
Prefer a `require()` call for [assets](./guides/markdown-features/markdown-features-assets.mdx):
```jsx
<img src={require('@site/static/img/myImage.png').default} />
```
:::
### `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.
```jsx
import React from 'react';
import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
const Component = () => {
const urls = ['/a', '/b'];
// highlight-start
const {withBaseUrl} = useBaseUrlUtils();
const urlsWithBaseUrl = urls.map(withBaseUrl);
// highlight-end
return <div>{/* ... */}</div>;
};
```
### `useGlobalData` {#useglobaldata}
React hook to access Docusaurus global data created by all the plugins.
Global data is namespaced by plugin name, and 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.
:::
```ts
type GlobalData = Record<
PluginName,
Record<
PluginId, // "default" by default
any // plugin-specific data
>
>;
```
Usage example:
```jsx {2,5-7}
import React from 'react';
import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {
const globalData = useGlobalData();
const myPluginData = globalData['my-plugin']['default'];
return <div>{myPluginData.someAttribute}</div>;
};
```
:::tip
Inspect your site's global data at `./docusaurus/globalData.json`
:::
### `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.
`pluginId` is optional if you don't use multi-instance plugins.
```ts
usePluginData(pluginName: string, pluginId?: string)
```
Usage example:
```jsx {2,5-6}
import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
const myPluginData = usePluginData('my-plugin');
return <div>{myPluginData.someAttribute}</div>;
};
```
### `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.
```ts
useAllPluginInstancesData(pluginName: string)
```
Usage example:
```jsx {2,5-7}
import React from 'react';
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
const myPluginData = allPluginInstancesData['default'];
return <div>{myPluginData.someAttribute}</div>;
};
```
## Functions {#functions}
### `interpolate` {#interpolate-1}
The imperative counterpart of the [`<Interpolate>`](#interpolate) component.
#### Signature {#signature}
```ts
// Simple string interpolation
function interpolate(text: string, values: Record<string, string>): string;
// JSX interpolation
function interpolate(
text: string,
values: Record<string, ReactNode>,
): ReactNode;
```
#### Example {#example-1}
```jsx
// highlight-start
import {interpolate} from '@docusaurus/Interpolate';
// highlight-end
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});
```
### `translate` {#translate-1}
The imperative counterpart of the [`<Translate>`](#translate) component. Also supporting [placeholders interpolation](#interpolate).
:::tip
Use the imperative API for the **rare cases** where a **component cannot be used**, such as:
- the page `title` metadata
- the `placeholder` props of form inputs
- the `aria-label` props for accessibility
:::
#### Signature {#signature-1}
```ts
function translate(
translation: {message: string; id?: string; description?: string},
values: Record<string, string>,
): string;
```
#### Example {#example-2}
```jsx title="src/pages/index.js"
import React from 'react';
import Layout from '@theme/Layout';
// highlight-start
import {translate} from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout
// highlight-start
title={translate({message: 'My page meta title'})}
// highlight-end
>
<img
src={'https://docusaurus.io/logo.png'}
aria-label={
// highlight-start
translate(
{
message: 'The logo of site {siteName}',
// Optional
id: 'homepage.logo.ariaLabel',
description: 'The home page logo aria label',
},
{siteName: 'Docusaurus'},
)
// highlight-end
}
/>
</Layout>
);
}
```
## Modules {#modules}
### `ExecutionEnvironment` {#executionenvironment}
A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code.
```jsx {2,5}
import React from 'react';
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
const MyPage = () => {
const location = ExecutionEnvironment.canUseDOM ? window.location.href : null;
return <div>{location}</div>;
};
```
| Field | Description |
| --- | --- |
| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if prerendering. |
| `ExecutionEnvironment.canUseEventListeners` | `true` if on client and has `window.addEventListener`. |
| `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. |
| `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. |
### `constants` {#constants}
A module exposing useful constants to client-side theme code.
```jsx
import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
```
| Named export | Value |
| ------------------- | --------- |
| `DEFAULT_PLUGIN_ID` | `default` |

130
website/versioned_docs/version-2.0.0-alpha.75/guides/creating-pages.md Normal file
View file

@ -0,0 +1,130 @@
---
id: creating-pages
title: Creating Pages
slug: /creating-pages
---
In this section, we will learn about creating pages in Docusaurus.
This is useful for creating **one-off standalone pages** like a showcase page, playground page or support page.
The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
You can use React components, or Markdown.
:::note
Pages do not have sidebars, only [docs](./docs/docs-introduction.md) have.
:::
## Add a React page {#add-a-react-page}
Create a file `/src/pages/helloReact.js`:
```jsx title="/src/pages/helloReact.js"
import React from 'react';
import Layout from '@theme/Layout';
function Hello() {
return (
<Layout title="Hello">
<div
style={{
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
height: '50vh',
fontSize: '20px',
}}>
<p>
Edit <code>pages/hello.js</code> and save to reload.
</p>
</div>
</Layout>
);
}
export default Hello;
```
Once you save the file, the development server will automatically reload the changes. Now open `http://localhost:3000/helloReact`, you will see the new page you just created.
Each page doesn't come with any styling. You will need to import the `Layout` component from `@theme/Layout` and wrap your contents within that component if you want the navbar and/or footer to appear.
:::tip
You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`).
:::
## Add a Markdown page {#add-a-markdown-page}
Create a file `/src/pages/helloMarkdown.md`:
```mdx title="/src/pages/helloMarkdown.md"
---
title: my hello page title
description: my hello page description
hide_table_of_contents: true
---
# Hello
How are you?
```
In the same way, a page will be created at `http://localhost:3000/helloMarkdown`.
Markdown pages are less flexible than React pages, because it always uses the theme layout.
Here's an [example Markdown page](/examples/markdownPageExample).
:::tip
You can use the full power of React in Markdown pages too, refer to the [MDX](https://mdxjs.com/) documentation.
:::
## Routing {#routing}
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
- `/src/pages/index.js` → `<baseUrl>`
- `/src/pages/foo.js` → `<baseUrl>/foo`
- `/src/pages/foo/test.js` → `<baseUrl>/foo/test`
- `/src/pages/foo/index.js` → `<baseUrl>/foo/`
In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:
- Add a `/src/pages/support.js` file
- Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file.
The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). By default, any Markdown or Javascript file starting with `_` will be ignored, and no routes will be created for that file (see the `exclude` option).
```sh
my-website
├── src
│ └── pages
│ ├── styles.module.css
│ ├── index.js
| ├──_ignored.js
│ └── support
│ ├── index.js
│ └── styles.module.css
.
```
:::caution
All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the `exclude` option (by default, files prefixed with `_`, test files(`.test.js`) and files in `__tests__` directory are not turned into pages).
:::
## Using React {#using-react}
React is used as the UI library to create pages. Every page component should export a React component, and you can leverage on the expressiveness of React to build rich and interactive content.
## Duplicate Routes {#duplicate-routes}
You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run `yarn start` or `yarn build`, but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes.

79
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/docs-create-doc.mdx Normal file
View file

@ -0,0 +1,79 @@
---
id: create-doc
title: Create a doc
description: Create a Markdown Document
slug: /create-doc
---
Create a markdown file, `greeting.md`, and place it under the `docs` directory.
```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
```
At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
```yml
---
id: greeting
title: Hello
---
## Hello from Docusaurus
Are you ready to create the documentation site for your open source project?
### Headers
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
The headers are well-spaced so that the hierarchy is clear.
- lists will help you
- present the key points
- that you want your users to remember
- and you may nest them
- multiple times
### Custom id headers {#custom-id}
With `{#custom-id}` syntax you can set your own header id.
```
This will render in the browser as follows:
import BrowserWindow from '@site/src/components/BrowserWindow';
<BrowserWindow url="http://localhost:3000">
<h2>Hello from Docusaurus</h2>
Are you ready to create the documentation site for your open source project?
<h3>Headers</h3>
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.
<h3>Only h2 and h3 will be in the toc</h3>
The headers are well-spaced so that the hierarchy is clear.
- lists will help you
- present the key points
- that you want your users to remember
- and you may nest them
- multiple times
</BrowserWindow>

80
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/docs-introduction.md Normal file
View file

@ -0,0 +1,80 @@
---
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.
## 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 user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
```yml
---
id: part1
---
Lorem ipsum
```
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
```yml
---
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 frontmatter:
```yml
---
id: my-home-doc
slug: /
---
Lorem ipsum
```
## Docs-only mode {#docs-only-mode}
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more infos](#home-page-docs)).
:::caution
You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
:::
:::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.md#blog-only-mode).
:::

28
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/docs-markdown-features.mdx Normal file
View file

@ -0,0 +1,28 @@
---
id: markdown-features
title: Docs Markdown Features
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.
## Markdown frontmatter {#markdown-frontmatter}
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
## Referencing other documents {#referencing-other-documents}
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
```md
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md).
[Relative document](../doc2.md) referencing works as well.
```
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
Another benefit, for versioned docs, is that one versioned doc will link to another doc of the exact same version.

212
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/docs-multi-instance.mdx Normal file
View file

@ -0,0 +1,212 @@
---
id: multi-instance
title: Docs Multi-instance
description: Use multiple docs plugin instances on a single Docusaurus site.
slug: /docs-multi-instance
---
The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.md#multi-instance-plugins-and-plugin-ids).
:::note
This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page.
:::
## Use-cases {#use-cases}
Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).
These documentations may even have different versioning/release lifecycles.
### Mobile SDKs documentation {#mobile-sdks-documentation}
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.
:::caution
If each documentation instance is very large, you should rather create 2 distinct Docusaurus sites.
If someone edits the iOS documentation, is it really useful to rebuild everything, including the whole Android documentation that did not change?
:::
### Versioned and unversioned doc {#versioned-and-unversioned-doc}
Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.
We use this pattern on the Docusaurus website itself:
- The [/docs/\*](/docs) section is versioned
- The [/community/\*](/community/support) section is unversioned
## Setup {#setup}
Suppose you have 2 documentations:
- Product: some versioned doc about your product
- Community: some unversioned doc about the community around your product
In this case, you should use the same plugin twice in your site configuration.
:::caution
`@docusaurus/preset-classic` already includes a docs plugin instance for you!
:::
When using the preset:
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-start
// id: 'product', // omitted => default instance
// highlight-end
path: 'product',
routeBasePath: 'product',
sidebarPath: require.resolve('./sidebarsProduct.js'),
// ... other options
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
id: 'community',
// highlight-end
path: 'community',
routeBasePath: 'community',
sidebarPath: require.resolve('./sidebarsCommunity.js'),
// ... other options
},
],
],
};
```
When not using the preset:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
// id: 'product', // omitted => default instance
// highlight-end
path: 'product',
routeBasePath: 'product',
sidebarPath: require.resolve('./sidebarsProduct.js'),
// ... other options
},
],
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
id: 'community',
// highlight-end
path: 'community',
routeBasePath: 'community',
sidebarPath: require.resolve('./sidebarsCommunity.js'),
// ... other options
},
],
],
};
```
Don't forget to assign a unique `id` attribute to plugin instances.
:::note
We consider that the `product` instance is the most important one, and make it the "default" instance by not assigning any id.
:::
## Versioned paths {#versioned-paths}
Each plugin instance will store versioned docs in a distinct folder.
The default plugin instance will use these paths:
- `website/versions.json`
- `website/versioned_docs`
- `website/versioned_sidebars`
The other plugin instances (with an `id` attribute) will use these paths:
- `website/<pluginId>_versions.json`
- `website/<pluginId>_versioned_docs`
- `website/<pluginId>_versioned_sidebars`
:::tip
You can omit the `id` attribute (defaults to `default`) for one of the docs plugin instances.
The instance paths will be simpler, and retro-compatible with a single-instance setup.
:::
## Tagging new versions {#tagging-new-versions}
Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
```bash npm2yarn
npm run docusaurus -- --help
```
To version the product/default docs plugin instance:
```bash npm2yarn
npm run docusaurus docs:version 1.0.0
```
To version the non-default/community docs plugin instance:
```bash npm2yarn
npm run docusaurus docs:version:community 1.0.0
```
## Docs navbar items {#docs-navbar-items}
Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.
For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
// highlight-start
docsPluginId: 'ios',
// highlight-end
},
{
type: 'docsVersionDropdown',
// highlight-start
docsPluginId: 'android',
// highlight-end
},
],
},
},
};
```

634
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/sidebar.md Normal file
View file

@ -0,0 +1,634 @@
---
id: sidebar
title: Sidebar
slug: /sidebar
---
Creating a sidebar is useful to:
- Group multiple **related documents**
- **Display a sidebar** on each of those documents
- Provide a **paginated navigation**, with next/previous button
To use sidebars on your Docusaurus site:
1. Define a file that exports a [sidebar object](#sidebar-object).
1. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-start
sidebarPath: require.resolve('./sidebars.js'),
// highlight-end
},
},
],
],
};
```
## Default sidebar
By default, Docusaurus [automatically generates a sidebar](#sidebar-item-autogenerated) for you, by using the filesystem structure of the `docs` folder:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/<version>)
},
],
};
```
You can also define your sidebars explicitly.
## Sidebar object {#sidebar-object}
A sidebar is a **tree of [sidebar items](#understanding-sidebar-items)**.
```typescript
type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| Record<
string, // category label
SidebarItem[] // category items
>;
```
A sidebars file can contain **multiple sidebar objects**.
```typescript
type SidebarsFile = Record<
string, // sidebar id
Sidebar
>;
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: ['doc1'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc2', 'doc3'],
},
],
};
```
Notice the following:
- There is a single sidebar `mySidebar`, containing 5 [sidebar items](#understanding-sidebar-items)
- `Getting Started` and `Docusaurus` are sidebar categories
- `doc1`, `doc2` and `doc3` are sidebar documents
:::tip
Use the **shorthand syntax** to express this sidebar more concisely:
```js title="sidebars.js"
module.exports = {
mySidebar: {
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};
```
:::
## Using multiple sidebars {#using-multiple-sidebars}
You can create a sidebar for each **set of markdown files** that you want to **group together**.
:::tip
The Docusaurus site is a good example of using multiple sidebars:
- [Docs](../../introduction.md)
- [API](../../cli.md)
:::
Example:
```js title="sidebars.js"
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
```
:::note
The keys `tutorialSidebar` and `apiSidebar` are sidebar **technical ids** and do not matter much.
:::
When browsing:
- `doc1` or `doc2`: the `tutorialSidebar` will be displayed
- `doc3` or `doc4`: the `apiSidebar` will be displayed
A **paginated navigation** link documents inside the same sidebar with **next and previous buttons**.
## Understanding sidebar items {#understanding-sidebar-items}
`SidebarItem` is an item defined in a Sidebar tree.
There are different types of sidebar items:
- **[Doc](#sidebar-item-doc)**: link to a doc page, assigning it to the sidebar
- **[Ref](#sidebar-item-ref)**: link to a doc page, without assigning it to the sidebar
- **[Link](#sidebar-item-link)**: link to any internal or external page
- **[Category](#sidebar-item-category)**: create a hierarchy of sidebar items
- **[Autogenerated](#sidebar-item-autogenerated)**: generate a sidebar slice automatically
### Doc: link to a doc {#sidebar-item-doc}
Use the `doc` type to link to a doc page and assign that doc to a sidebar:
```typescript
type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
}
// Shorthand syntax
| string; // docId shortcut
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
// Normal syntax:
// highlight-start
{
type: 'doc',
id: 'doc1', // document id
label: 'Getting started', // sidebar label
},
// highlight-end
// Shorthand syntax:
// highlight-start
'doc2', // document id
// highlight-end
],
};
```
The `sidebar_label` markdown frontmatter has a higher precedence over the `label` key in `SidebarItemDoc`.
:::note
Don't assign the same doc to multiple sidebars: use a [ref](#sidebar-item-ref) instead.
:::
### Ref: link to a doc, without sidebar {#sidebar-item-ref}
Use the `ref` type to link to a doc page without assigning it to a sidebar.
```typescript
type SidebarItemRef = {
type: 'ref';
id: string;
};
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // Document id (string).
},
],
};
```
When browsing `doc1`, Docusaurus **will not display** the `mySidebar` sidebar.
### Link: link to any page {#sidebar-item-link}
Use the `link` type to link to any page (internal or external) that is not a doc.
```typescript
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
};
```
Example:
```js title="sidebars.js"
module.exports = {
myLinksSidebar: [
// highlight-start
// External link
{
type: 'link',
label: 'Facebook', // The link label
href: 'https://facebook.com', // The external URL
},
// highlight-end
// highlight-start
// Internal link
{
type: 'link',
label: 'Home', // The link label
href: '/', // The internal path
},
// highlight-end
],
};
```
### Category: create a hierarchy {#sidebar-item-category}
Use the `category` type to create a hierarchy of sidebar items.
```typescript
type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
// Category options:
collapsed: boolean; // Set the category to be collapsed or open by default
};
```
Example:
```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
```
:::tip
Use the **shorthand syntax** when you don't need **category options**:
```js title="sidebars.js"
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
```
:::
#### Collapsible categories {#collapsible-categories}
For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-start
sidebarCollapsible: false,
// highlight-end
},
};
```
#### Expanded categories by default {#expanded-categories-by-default}
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
```js title="sidebars.js"
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
```
### Autogenerated: generate a sidebar {#sidebar-item-autogenerated}
Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category.
An `autogenerated` item is converted by Docusaurus to a **sidebar slice**: a list of items of type `doc` and `category`.
```typescript
type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};
```
Docusaurus can generate a sidebar from your docs folder:
```js title="sidebars.js"
module.exports = {
myAutogeneratedSidebar: [
// highlight-start
{
type: 'autogenerated',
dirName: '.', // '.' means the current docs folder
},
// highlight-end
],
};
```
You can also use **multiple `autogenerated` items** in a sidebar, and interleave them with regular sidebar items:
```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: 'guides', // Generate sidebar slice from docs/guides
},
// highlight-end
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};
```
#### Autogenerated sidebar metadatas {#autogenerated-sidebar-metadatas}
By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names).
If the generated sidebar does not look good, you can assign additional metadatas to docs and categories.
**For docs**: use additional frontmatter:
```diff title="docs/tutorials/tutorial-easy.md"
+ ---
+ sidebar_label: Easy
+ sidebar_position: 2
+ ---
# Easy Tutorial
This is the easy tutorial!
```
**For categories**: add a `_category_.json` or `_category_.yml` file in the appropriate folder:
```json title="docs/tutorials/_category_.json"
{
"label": "Tutorial",
"position": 3
}
```
```yaml title="docs/tutorials/_category_.yml"
label: 'Tutorial'
position: 2.5 # float position is supported
collapsed: false # keep the category open by default
```
:::info
The position metadata is only used **inside a sidebar slice**: Docusaurus does not re-order other items of your sidebar.
:::
#### Using number prefixes
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes:
```bash
docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Hard
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md
```
To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**.
By default, Docusaurus will **remove the number prefix** from the doc id, title, label and url paths.
:::caution
**Prefer using [additional metadatas](#autogenerated-sidebar-metadatas)**.
Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**:
```diff title="docs/02-Tutorial Easy/01-First Part.md"
- Check the [Tutorial End](../04-End.md);
+ Check the [Tutorial End](../05-End.md);
```
:::
#### Customize the sidebar items generator
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
}) {
// Example: return an hardcoded list of static sidebar items
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
// highlight-end
},
],
],
};
```
:::tip
**Re-use and enhance the default generator** instead of writing a generator from scratch.
**Add, update, filter, re-order** the sidebar items according to your use-case:
```js title="docusaurus.config.js"
// highlight-start
// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
// Reverse items in categories
const result = items.map((item) => {
if (item.type === 'category') {
return {...item, items: reverseSidebarItems(item.items)};
}
return item;
});
// Reverse items at current level
result.reverse();
return result;
}
// highlight-end
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
...args
}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
// highlight-end
},
],
],
};
```
:::
## Hideable sidebar {#hideable-sidebar}
Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-starrt
hideableSidebar: true,
// highlight-end
},
};
```
## Passing custom props {#passing-custom-props}
To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
```js
{
type: 'doc',
id: 'doc1',
customProps: {
/* props */
}
}
```
## Complex sidebars example {#complex-sidebars-example}
Real-world example from the Docusaurus site:
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
<CodeBlock className="language-js" title="sidebars.js">
{require('!!raw-loader!@site/sidebars.js')
.default
.split('\n')
// remove comments
.map((line) => !['#','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
.filter(Boolean)
.join('\n')}
</CodeBlock>
```

208
website/versioned_docs/version-2.0.0-alpha.75/guides/docs/versioning.md Normal file
View file

@ -0,0 +1,208 @@
---
id: versioning
title: Versioning
slug: /versioning
---
You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
:::caution
Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!
:::
Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is **best suited for websites with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
To better understand how versioning works and see if it suits your needs, you can read on below.
## Directory structure {#directory-structure}
```shell
website
├── sidebars.json # sidebar for master (next) version
├── docs # docs directory for master (next) version
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
│ └── hello.md # https://mysite.com/docs/next/hello
├── versions.json # file to indicate what versions are available
├── versioned_docs
│ ├── version-1.1.0
│ │ ├── foo
│ │ │ └── bar.md # https://mysite.com/docs/foo/bar
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar
│ └── hello.md
├── versioned_sidebars
│ ├── version-1.1.0-sidebars.json
│ └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json
```
The table below explains how a versioned file maps to its version and the generated URL.
| Path | Version | URL |
| --------------------------------------- | -------------- | ----------------- |
| `versioned_docs/version-1.0.0/hello.md` | 1.0.0 | /docs/1.0.0/hello |
| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello |
| `docs/hello.md` | next | /docs/next/hello |
### Tagging a new version {#tagging-a-new-version}
1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
1. Enter a new version number.
```bash npm2yarn
npm run docusaurus docs:version 1.1.0
```
When tagging a new version, the document versioning mechanism will:
- Copy the full `docs/` folder contents into a new `versioned_docs/version-<version>/` folder.
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`.
## Docs {#docs}
### Creating new docs {#creating-new-docs}
1. Place the new file into the corresponding version folder.
1. Include the reference for the new file into the corresponding sidebar file, according to version number.
**Master docs**
```shell
# The new file.
docs/new.md
# Edit the corresponding sidebar file.
sidebar.js
```
**Older docs**
```shell
# The new file.
versioned_docs/version-1.0.0/new.md
# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json
```
### Linking docs {#linking-docs}
- Remember to include the `.md` extension.
- Files will be linked to correct corresponding version.
- Relative paths work as well.
```md
The [@hello](hello.md#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.md) for more info.
```
## Versions {#versions}
Each directory in `versioned_docs/` will represent a documentation version.
### Updating an existing version {#updating-an-existing-version}
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
1. Edit any file.
1. Commit and push changes.
1. It will be published to the version.
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
### Deleting an existing version {#deleting-an-existing-version}
You can delete/remove versions as well.
1. Remove the version from `versions.json`.
Example:
```diff {4}
[
"2.0.0",
"1.9.0",
- "1.8.0"
]
```
2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
## Recommended practices {#recommended-practices}
### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version}
The "current" version is the version name for the `./docs` folder.
There are different ways to manage versioning, but two very common patterns are:
- You release v1, and start immediately working on v2 (including its docs)
- You release v1, and will maintain it for some time before thinking about v2.
Docusaurus defaults work great for the first usecase.
**For the 2nd usecase**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead:
```json
{
"lastVersion": "current",
"versions": {
"current": {
"label": "1.0.0",
"path": "1.0.0"
}
}
}
```
The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, and `1.0.0` will become the default version we link to in the navbar dropdown, and you will only need to maintain a single `./docs` folder.
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
### Version your documentation only when needed {#version-your-documentation-only-when-needed}
For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.
### Keep the number of versions small {#keep-the-number-of-versions-small}
As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation version with the lowest being `22.X`. Keep it small 😊
### Use absolute import within the docs {#use-absolute-import-within-the-docs}
Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by docusaurus, that points to the `website` directory. Example:
```diff
- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';
```
### Global or versioned colocated assets {#global-or-versioned-colocated-assets}
You should decide if assets like images and files are per version or shared between versions
If your assets should be versioned, put them in the docs version, and use relative paths:
```md
![img alt](./myImage.png)
[download this file](./file.pdf)
```
If your assets are global, put them in `/static` and use absolute paths:
```md
![img alt](/myImage.png)
[download this file](/file.pdf)
```

86
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-admonitions.mdx Normal file
View file

@ -0,0 +1,86 @@
---
id: admonitions
title: Admonitions
description: Handling admonitions/callouts in Docusaurus Markdown
slug: /markdown-features/admonitions
---
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.
Example:
:::note
The content and title *can* include markdown.
:::
:::tip You can specify an optional title
Heads up! Here's a pro-tip.
:::
:::info
Useful information.
:::
:::caution
Warning! You better pay attention!
:::
:::danger
Danger danger, mayday!
:::
:::note
The content and title _can_ include markdown.
:::
:::tip You can specify an optional title
Heads up! Here's a pro-tip.
:::
:::info
Useful information.
:::
:::caution
Warning! You better pay attention!
:::
:::danger
Danger danger, mayday!
:::
## Specifying title {#specifying-title}
You may also specify an optional title
:::note Your Title
The content and title *can* include markdown.
:::
:::note Your Title
The content and title _can_ include Markdown.
:::

147
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-assets.mdx Normal file
View file

@ -0,0 +1,147 @@
---
id: assets
title: Assets
description: Handling assets in Docusaurus Markdown
slug: /markdown-features/assets
---
Sometimes you want to link to static assets directly from Markdown files, and it is convenient to co-locate the asset next to the markdown file using it.
We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder.
Let's imagine the following file structure:
```
# Your doc
/website/docs/myFeature.mdx
# Some assets you want to use
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example-pdf.pdf
```
## Images {#images}
You can use images in Markdown, or by requiring them and using a JSX image tag:
```mdx
# My Markdown page
<img
src={require('./assets/docusaurus-asset-example-banner.png').default}
alt="Example banner"
/>
or
![Example banner](./assets/docusaurus-asset-example-banner.png)
```
The ES imports syntax also works:
```mdx
# My Markdown page
import myImageUrl from './assets/docusaurus-asset-example-banner.png';
<img src={myImageUrl} alt="My image alternative text" />
```
This results in displaying the image:
![My image alternative text](../../assets/docusaurus-asset-example-banner.png)
:::note
If you are using [@docusaurus/plugin-ideal-image](../../using-plugins.md#docusaurusplugin-ideal-image), you need to use the dedicated image component, as documented.
:::
## Files {#files}
In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc.
```mdx
# My Markdown page
<a
target="_blank"
href={require('./assets/docusaurus-asset-example-pdf.pdf').default}>
Download this PDF
</a>
or
[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf)
```
<a
target="_blank"
href={require('../../assets/docusaurus-asset-example-pdf.pdf').default}>
Download this PDF
</a>
[Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf)
## Inline SVGs {#inline-svgs}
Docusaurus supports inlining SVGs out of the box.
```jsx
import DocusaurusSvg from './docusaurus.svg';
<DocusaurusSvg />;
```
import DocusaurusSvg from '@site/static/img/docusaurus.svg';
<DocusaurusSvg />
This can be useful, if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.
```jsx
import DocusaurusSvg from './docusaurus.svg';
<DocusaurusSvg className="themedDocusaurus" />;
```
```css
html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
fill: greenyellow;
}
html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
fill: seagreen;
}
```
<DocusaurusSvg className="themedDocusaurus" />
## Themed Images {#themed-images}
Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme.
```jsx {5-8}
import ThemedImage from '@theme/ThemedImage';
<ThemedImage
alt="Docusaurus themed image"
sources={{
light: useBaseUrl('/img/docusaurus_light.svg'),
dark: useBaseUrl('/img/docusaurus_dark.svg'),
}}
/>;
```
```mdx-code-block
import useBaseUrl from '@docusaurus/useBaseUrl';
import ThemedImage from '@theme/ThemedImage';
<ThemedImage
alt="Docusaurus themed image"
sources={{
light: useBaseUrl('/img/docusaurus_keytar.svg'),
dark: useBaseUrl('/img/docusaurus_speed.svg'),
}}
/>
```

443
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-code-blocks.mdx Normal file
View file

@ -0,0 +1,443 @@
---
id: code-blocks
title: Code blocks
description: Handling code blocks in Docusaurus Markdown
slug: /markdown-features/code-blocks
---
Code blocks within documentation are super-powered 💪.
## Code title {#code-title}
You can add a title to the code block by adding `title` key after the language (leave a space between them).
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
## Syntax highlighting {#syntax-highlighting}
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
```jsx
console.log('Every repo must come with a mascot.');
```
<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
```jsx
console.log('Every repo must come with a mascot.');
```
By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
For example, if you prefer to use the `dracula` highlighting theme:
```js {4} title="docusaurus.config.js"
module.exports = {
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/dracula'),
},
},
};
```
By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages.
For example, if you want to add highlighting for the `powershell` language:
```js {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
additionalLanguages: ['powershell'],
},
// ...
},
};
```
If you want to add highlighting for languages not yet supported by Prism, you can swizzle `prism-include-languages`:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic prism-include-languages
```
It will produce `prism-include-languages.js` in your `src/theme` folder. You can add highlighting support for custom languages by editing `prism-include-languages.js`:
```js {8} title="src/theme/prism-include-languages.js"
const prismIncludeLanguages = (Prism) => {
// ...
additionalLanguages.forEach((lang) => {
require(`prismjs/components/prism-${lang}`); // eslint-disable-line
});
require('/path/to/your/prism-language-definition');
// ...
};
```
You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
## Line highlighting {#line-highlighting}
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
```jsx {3}
function HighlightSomeText(highlight) {
if (highlight) {
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
```
```jsx {3}
function HighlightSomeText(highlight) {
if (highlight) {
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
```
To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
```css title="/src/css/custom.css"
.docusaurus-highlight-code-line {
background-color: rgb(72, 77, 91);
display: block;
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
}
/* If you have a different syntax highlighting theme for dark mode. */
html[data-theme='dark'] .docusaurus-highlight-code-line {
background-color: ; /* Color which works with dark mode syntax highlighting theme */
}
```
To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
```jsx {1,4-6,11}
import React from 'react';
function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}
return <div>Foo</div>;
}
export default MyComponent;
```
```jsx {1,4-6,11}
import React from 'react';
function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}
return <div>Foo</div>;
}
export default MyComponent;
```
You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
```jsx
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end
return 'Nothing highlighted';
}
```
```jsx
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end
return 'Nothing highlighted';
}
```
Supported commenting syntax:
| Language | Syntax |
| ---------- | ------------------------ |
| JavaScript | `/* ... */` and `// ...` |
| JSX | `{/* ... */}` |
| Python | `# ...` |
| HTML | `<!-- ... -->` |
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
## Interactive code editor {#interactive-code-editor}
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin.
First, add the plugin to your package.
```bash npm2yarn
npm install --save @docusaurus/theme-live-codeblock
```
You will also need to add the plugin to your `docusaurus.config.js`.
```js {3}
module.exports = {
// ...
themes: ['@docusaurus/theme-live-codeblock'],
// ...
};
```
To use the plugin, create a code block with `live` attached to the language meta string.
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```
The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
var timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {date.toLocaleTimeString()}.</h2>
</div>
);
}
```
### Imports {#imports}
:::caution react-live and imports
It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.
:::
By default, all React imports are available. If you need more imports available, swizzle the react-live scope:
```bash npm2yarn
npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope
```
```jsx {3-15,21} title="src/theme/ReactLiveScope/index.js"
import React from 'react';
const ButtonExample = (props) => (
<button
{...props}
style={{
backgroundColor: 'white',
border: 'solid red',
borderRadius: 20,
padding: 10,
cursor: 'pointer',
...props.style,
}}
/>
);
// Add react-live imports you need here
const ReactLiveScope = {
React,
...React,
ButtonExample,
};
export default ReactLiveScope;
```
The `ButtonExample` component is now available to use:
```jsx live
function MyPlayground(props) {
return (
<div>
<ButtonExample onClick={() => alert('hey!')}>Click me</ButtonExample>
</div>
);
}
```
## Multi-language support code blocks {#multi-language-support-code-blocks}
With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.
Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.
The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is **intentional**. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
````jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'Python', value: 'py', },
{ label: 'Java', value: 'java', },
]
}>
<TabItem value="js">
```js
function helloWorld() {
console.log('Hello, world!');
}
```
</TabItem>
<TabItem value="py">
```py
def hello_world():
print 'Hello, world!'
```
</TabItem>
<TabItem value="java">
```java
class HelloWorld {
public static void main(String args[]) {
System.out.println("Hello, World");
}
}
```
</TabItem>
</Tabs>
````
And you will get the following:
````mdx-code-block
<Tabs
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'Python', value: 'py', },
{ label: 'Java', value: 'java', },
]
}>
<TabItem value="js">
```js
function helloWorld() {
console.log('Hello, world!');
}
```
</TabItem>
<TabItem value="py">
```py
def hello_world():
print 'Hello, world!'
```
</TabItem>
<TabItem value="java">
```java
class HelloWorld {
public static void main(String args[]) {
System.out.println("Hello, World");
}
}
```
</TabItem>
</Tabs>
````
You may want to implement your own `<MultiLanguageCode />` abstraction if you find the above approach too verbose. We might just implement one in future for convenience.
If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](#syncing-tab-choices).

59
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-headings.mdx Normal file
View file

@ -0,0 +1,59 @@
---
id: headings
title: Headings
description: Using Markdown headings
slug: /markdown-features/headings
---
## Markdown headings {#markdown-headings}
You can use regular Markdown headings.
```
## Level 2 title
### Level 3 title
#### Level 4 title
```
Markdown headings appear as a table-of-contents entry.
## Heading ids {#heading-ids}
Each heading has an id that can be automatically generated, or explicitly specified.
Heading ids allow you to link to a specific document heading in Markdown or JSX:
```md
[link](#heading-id)
```
```jsx
<Link to="#heading-id">link</Link>
```
### Generated ids {#generated-ids}
By default, Docusaurus will generate heading ids for you, based on the heading text.
`### Hello World` will have id `hello-world`.
Generated ids have **some limits**:
- The id might not look good
- You might want to **change or translate** the text without updating the existing id
### Explicit ids {#explicit-ids}
A special Markdown syntax lets you set an **explicit heading id**:
```md
### Hello World {#my-explicit-id}
```
:::tip
Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents.
:::

121
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-inline-toc.mdx Normal file
View file

@ -0,0 +1,121 @@
---
id: inline-toc
title: Inline TOC
description: Using inline table-of-contents inside Docusaurus Markdown
slug: /markdown-features/inline-toc
---
import BrowserWindow from '@site/src/components/BrowserWindow';
Each markdown document displays a tab of content on the top-right corner.
But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
## Full table of contents {#full-table-of-contents}
The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document.
```jsx
import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} />;
```
```mdx-code-block
import TOCInline from '@theme/TOCInline';
<BrowserWindow>
<TOCInline toc={toc} />
</BrowserWindow>
```
## Custom table of contents {#custom-table-of-contents}
The `toc` props is just a list of table of contents items:
```ts
type TOCItem = {
value: string;
id: string;
children: TOCItem[];
};
```
You can create this TOC tree manually, or derive a new TOC tree from the `toc` variable:
```jsx
import TOCInline from '@theme/TOCInline';
<TOCInline
toc={
// Only show 3th and 5th top-level heading
[toc[2], toc[4]]
}
/>;
```
```mdx-code-block
<BrowserWindow>
<TOCInline toc={[toc[2], toc[4]]} />
</BrowserWindow>
```
---
:::caution
The underlying content is just an example to have more table-of-contents items available in current page.
:::
## Example Section 1 {#example-section-1}
Lorem ipsum
### Example Subsection 1 a {#example-subsection-1-a}
Lorem ipsum
### Example Subsection 1 b {#example-subsection-1-b}
Lorem ipsum
### Example Subsection 1 c {#example-subsection-1-c}
Lorem ipsum
## Example Section 2 {#example-section-2}
Lorem ipsum
### Example Subsection 2 a {#example-subsection-2-a}
Lorem ipsum
### Example Subsection 2 b {#example-subsection-2-b}
Lorem ipsum
### Example Subsection 2 c {#example-subsection-2-c}
Lorem ipsum
## Example Section 3 {#example-section-3}
Lorem ipsum
### Example Subsection 3 a {#example-subsection-3-a}
Lorem ipsum
### Example Subsection 3 b {#example-subsection-3-b}
Lorem ipsum
### Example Subsection 3 c {#example-subsection-3-c}
Lorem ipsum

23
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-intro.mdx Normal file
View file

@ -0,0 +1,23 @@
---
id: introduction
title: Markdown Features introduction
sidebar_label: Introduction
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
slug: /markdown-features
---
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example.
Markdown is a syntax that enables you to write formatted content in a readable syntax.
The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents.
:::important
This section assumes you are using the official Docusaurus content plugins.
:::

78
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-plugins.mdx Normal file
View file

@ -0,0 +1,78 @@
---
id: plugins
title: Plugins
description: Using MDX plugins to expand Docusaurus Markdown functionalities
slug: /markdown-features/plugins
---
You can expand the MDX functionalities, using plugins.
Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
## Configuring plugins {#configuring-plugins}
An MDX plugin is usually a npm package, so you install them like other npm packages using npm.
First, install your [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) and [Rehype](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins) plugins.
For example:
```bash npm2yarn
npm install --save remark-images
npm install --save rehype-truncate
```
Next, import the plugins:
```js
const remarkImages = require('remark-images');
const rehypeTruncate = require('rehype-truncate');
```
Finally, add them to the `@docusaurus/preset-classic` options in `docusaurus.config.js`:
```js {10,11} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// ...
remarkPlugins: [remarkImages],
rehypePlugins: [rehypeTruncate],
},
},
],
],
};
```
## Configuring plugin options {#configuring-plugin-options}
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:
```jsx {10-13} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// ...
remarkPlugins: [
plugin1,
[plugin2, {option1: {...}}],
],
},
},
],
],
};
```
See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).

71
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-react.mdx Normal file
View file

@ -0,0 +1,71 @@
---
id: react
title: Using React
description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
slug: /markdown-features/react
---
import BrowserWindow from '@site/src/components/BrowserWindow';
Docusaurus has built-in support for [MDX](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components.
:::note
While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax.
:::
Try this block here:
```jsx
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
```
Notice how it renders both the markup from your React component and the Markdown syntax:
```mdx-code-block
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<BrowserWindow minHeight={240} url="http://localhost:3000">
<Highlight color="#25c2a0">Docusaurus green</Highlight>
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
</BrowserWindow>
```
<br />
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).
:::

228
website/versioned_docs/version-2.0.0-alpha.75/guides/markdown-features/markdown-features-tabs.mdx Normal file
View file

@ -0,0 +1,228 @@
---
id: tabs
title: Tabs
description: Using tabs inside Docusaurus Markdown
slug: /markdown-features/tabs
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides `<Tabs>` components out-of-the-box.
```jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>;
```
And you will get the following:
```mdx-code-block
<Tabs
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>
```
:::info
By default, tabs are rendered eagerly, but it is possible to load them lazily by passing the `lazy` prop to the `Tabs` component.
:::
## Syncing tab choices {#syncing-tab-choices}
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that `groupID` are globally-namespaced.
```jsx {2,14}
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac">Use Command + V to paste.</TabItem>
</Tabs>
```
```mdx-code-block
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac">Use Command + V to paste.</TabItem>
</Tabs>
```
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.
```jsx
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
{label: 'Linux', value: 'linux'},
]}>
<TabItem value="win">I am Windows.</TabItem>
<TabItem value="mac">I am macOS.</TabItem>
<TabItem value="linux">I am Linux.</TabItem>
</Tabs>
```
```mdx-code-block
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
{label: 'Linux', value: 'linux'},
]}>
<TabItem value="win">I am Windows.</TabItem>
<TabItem value="mac">I am macOS.</TabItem>
<TabItem value="linux">I am Linux.</TabItem>
</Tabs>
```
---
Tab choices with different `groupId`s will not interfere with each other:
```jsx {2,14}
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]
}>
<TabItem value="win">Windows in windows.</TabItem>
<TabItem value="mac">macOS is macOS.</TabItem>
</Tabs>
<Tabs
groupId="non-mac-operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Unix', value: 'unix'},
]
}>
<TabItem value="win">Windows is windows.</TabItem>
<TabItem value="unix">Unix is unix.</TabItem>
</Tabs>
```
```mdx-code-block
<Tabs
groupId="operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="win">Windows in windows.</TabItem>
<TabItem value="mac">macOS is macOS.</TabItem>
</Tabs>
<Tabs
groupId="non-mac-operating-systems"
defaultValue="win"
values={[
{label: 'Windows', value: 'win'},
{label: 'Unix', value: 'unix'},
]}>
<TabItem value="win">Windows is windows.</TabItem>
<TabItem value="unix">Unix is unix.</TabItem>
</Tabs>
```
## Customizing tabs {#customizing-tabs}
You might want to customize the appearance of certain set of tabs. To do that you can pass the string in `className` prop and the specified CSS class will be added to the `Tabs` component:
```jsx {5}
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
className="unique-tabs"
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>;
```
```mdx-code-block
<Tabs
className="unique-tabs"
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>
```

528
website/versioned_docs/version-2.0.0-alpha.75/i18n/i18n-crowdin.mdx Normal file
View file

@ -0,0 +1,528 @@
---
id: crowdin
title: i18n - Using Crowdin
slug: /i18n/crowdin
---
The i18n system of Docusaurus is **decoupled from any translation software**.
You can integrate Docusaurus with the **tools and SaaS of your choice**, as long as you put the **translation files at the correct location**.
We document the usage of [Crowdin](https://crowdin.com/), as **one** possible **integration example**.
:::caution
This is **not an endorsement of Crowdin** as the unique choice to translate a Docusaurus site, but it is successfully used by Facebook to translate documentation projects such as [Jest](https://jestjs.io/), [Docusaurus](https://docusaurus.io/) and [ReasonML](https://reasonml.github.io/).
Refer to the **[Crowdin documentation](https://support.crowdin.com/)** and **[Crowdin support](mailto:support@crowdin.com)** for help.
:::
:::tip
Use this **[community-driven GitHub issue](https://github.com/facebook/docusaurus/discussions/4052)** to discuss anything related to Docusaurus + Crowdin.
:::
## Crowdin overview {#crowdin-overview}
Crowdin is a translation SaaS, offering a [free plan for open-source projects](https://crowdin.com/page/open-source-project-setup-request).
We recommend the following translation workflow:
- **Upload sources** to Crowdin (untranslated files)
- Use Crowdin to **translate the content**
- **Download translations** from Crowdin (localized translation files)
Crowdin provides a [CLI](https://support.crowdin.com/cli-tool/) to **upload sources** and **download translations**, allowing you to automate the translation process.
The [`crowdin.yml` configuration file](https://support.crowdin.com/configuration-file/) is convenient for Docusaurus, and permits to **download the localized translation files at the expected location** (in `i18n/<locale>/..`).
Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows.
## Crowdin tutorial {#crowdin-tutorial}
This is a walk-through of using Crowdin to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
The end result can be seen at [docusaurus-crowdin-example.netlify.app](https://docusaurus-crowdin-example.netlify.app/) ([repository](https://github.com/slorber/docusaurus-crowdin-example)).
### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site:
```bash
npx @docusaurus/init@latest init website classic
```
Add the site configuration for the French language:
```js title="docusaurus.config.js"
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
themeConfig: {
navbar: {
items: [
// ...
{
type: 'localeDropdown',
position: 'left',
},
// ...
],
},
},
// ...
};
```
Translate the homepage:
```jsx title="src/pages/index.js"
import React from 'react';
import Translate from '@docusaurus/Translate';
import Layout from '@theme/Layout';
export default function Home() {
return (
<Layout>
<h1 style={{margin: 20}}>
<Translate description="The homepage main heading">
Welcome to my Docusaurus translated site!
</Translate>
</h1>
</Layout>
);
}
```
### Create a Crowdin project {#create-a-crowdin-project}
Sign up on [Crowdin](https://crowdin.com/), and create a project.
Use English as source language, and French as target language.
![Create a Crowdin project with english as source language, and french as target language](/img/crowdin/crowdin-create-project.png)
Your project is created, but it is empty for now. We will upload the files to translate in the next steps.
### Create the Crowdin configuration {#create-the-crowdin-configuration}
This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand:
- Where to find the source files to upload (JSON and Markdown)
- Where to download the files after translation (in `i18n/<locale>`)
Create `crowdin.yml` in `website`:
```yml title="crowdin.yml"
project_id: '123456'
api_token_env: 'CROWDIN_PERSONAL_TOKEN'
preserve_hierarchy: true
files: [
# JSON translation files
{
source: '/i18n/en/**/*',
translation: '/i18n/%two_letters_code%/**/%original_file_name%',
},
# Docs Markdown files
{
source: '/docs/**/*',
translation: '/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%',
},
# Blog Markdown files
{
source: '/blog/**/*',
translation: '/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%',
},
]
```
Crowdin has its own syntax for declaring source/translation paths:
- `**/*`: everything in a subfolder
- `%two_letters_code%`: the 2-letters variant of Crowdin target languages (`fr` in our case)
- `**/%original_file_name%`: the translations will preserve the original folder/file hierarchy
:::info
The Crowdin CLI warnings are not always easy to understand.
We advise to:
- change one thing at a time
- re-upload sources after any configuration change
- use paths starting with `/` (`./` does not work)
- avoid fancy globbing patterns like `/docs/**/*.(md|mdx)` (does not work)
:::
#### Access token {#access-token}
The `api_token_env` attribute defines the **env variable name** read by the Crowdin CLI.
You can obtain a `Personal Access Token` on [your personal profile page](https://crowdin.com/settings#api-key).
:::tip
You can keep the default value `CROWDIN_PERSONAL_TOKEN`, and set this environment variable and on your computer and on the CI server to the generated access token.
:::
:::caution
A Personal Access Tokens grant **read-write access to all your Crowdin projects**.
You should **not commit** it, and it may be a good idea to create a dedicated **Crowdin profile for your company** instead of using a personal account.
:::
#### Other configuration fields {#other-configuration-fields}
- `project_id`: can be hardcoded, and is found on `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api`
- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything
### Install the Crowdin CLI {#install-the-crowdin-cli}
This tutorial use the CLI in version `3.5.2`, but we expect `3.x` releases to keep working.
Install the Crowdin CLI as a NPM package to your Docusaurus site:
```bash npm2yarn
npm install @crowdin/cli@3
```
Add a `crowdin` script:
```json title="package.json"
{
"scripts": {
"crowdin": "crowdin"
}
}
```
Test that you can run the Crowdin CLI:
```bash npm2yarn
npm run crowdin -- --version
```
Set the `CROWDIN_PERSONAL_TOKEN` env variable on your computer, to allow the CLI to authenticate with the Crowdin API.
:::tip
Temporarily, you can hardcode your personal token in `crowdin.yml` with `api_token: 'MY-TOKEN'`.
:::
### Upload the sources {#upload-the-sources}
Generate the JSON translation files for the default language in `website/i18n/en`:
```bash npm2yarn
npm run write-translations
```
Upload all the JSON and Markdown translation files:
```bash npm2yarn
npm run crowdin upload
```
![Crowdin CLI uploading Docusaurus source files](/img/crowdin/crowdin-upload-sources-cli.png)
Your source files are now visible on the Crowdin interface: `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#files`
![Crowdin UI showing Docusaurus source files](/img/crowdin/crowdin-source-files.png)
### Translate the sources {#translate-the-sources}
On `https://crowdin.com/project/<MY_PROJECT_NAME>`, click on the French target language.
![Crowdin UI showing French translation files](/img/crowdin/crowdin-french-translations.png)
Translate some Markdown files.
![Crowdin UI to translate a Markdown file](/img/crowdin/crowdin-translate-markdown.png)
:::tip
Use `Hide String` to make sure translators **don't translate things that should not be**:
- Frontmatter: `id`, `slug`, `tags` ...
- Admonitions: `:::`, `:::note`, `:::tip` ...
![Crowdin UI hide string](/img/crowdin/crowdin-hide-string.png)
:::
Translate some JSON files.
![Crowdin UI to translate a JSON file](/img/crowdin/crowdin-translate-json.png)
:::info
The `description` attribute of JSON translation files is visible on Crowdin to help translate the strings.
:::
:::tip
**[Pre-translate](https://support.crowdin.com/pre-translation-via-machine/)** your site, and **fix pre-translation mistakes manually** (enable the Global Translation Memory in settings first).
Use the `Hide String` feature first, as Crowdin is pre-translating things too optimistically.
:::
### Download the translations {#download-the-translations}
Use the Crowdin CLI to download the translated JSON and Markdown files.
```bash npm2yarn
npm run crowdin download
```
The translated content should be downloaded in `i18n/fr`.
Start your site on the French locale:
```bash npm2yarn
npm run start -- --locale fr
```
Make sure that your website is now translated in French at `http://localhost:3000/fr/`.
### Automate with CI {#automate-with-ci}
We will configure the CI to **download the Crowdin translations at build time**, and keep them outside of Git.
Add `website/i18n` to `.gitignore`.
Set the `CROWDIN_PERSONAL_TOKEN` env variable on your CI.
Create a npm script to `sync` Crowdin (extract sources, upload sources, download translations):
```json title="package.json"
{
"scripts": {
"crowdin:sync": "docusaurus write-translations && crowdin upload && crowdin download"
}
}
```
Call the `npm run crowdin:sync` script in your CI, just before building the Docusaurus site.
:::tip
Keep your deploy-previews fast: don't download translations, and use `npm run build -- --locale en` for feature branches.
:::
:::caution
Crowdin does not support well multiple concurrent uploads/downloads: it is preferable to only include translations to your production deployment, and keep deploy previews untranslated.
:::
## Advanced Crowdin topics {#advanced-crowdin-topics}
### MDX {#mdx}
:::caution
Pay special attention to the JSX fragments in MDX documents!
:::
Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text).
#### MDX problems {#mdx-problems}
Crowdin thinks the JSX syntax is embedded HTML, and can mess-up with the JSX markup when you download the translations, leading to a site that fails to build due to invalid JSX.
Simple JSX fragments using simple string props like `<Username name="Sebastien"/>` will work fine.
More complex JSX fragments using object/array props like `<User person={{name: "Sebastien"}}/>` are more likely to fail due to a syntax that does not look like HTML.
#### MDX solutions {#mdx-solutions}
We recommend moving the complex embedded JSX code as separate standalone components.
We also added a `mdx-code-block` escape hatch syntax:
`````text
# How to deploy Docusaurus
To deploy Docusaurus, run the following command:
````mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="bash"
values={[
{ label: 'Bash', value: 'bash' },
{ label: 'Windows', value: 'windows' }
]}>
<TabItem value="bash">
```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy
```
</TabItem>
<TabItem value="windows">
```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
```
</TabItem>
</Tabs>
````
`````
This will:
- be interpreted by Crowdin as code blocks (and not mess-up with the markup on download)
- be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block)
- unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...)
### Docs versioning {#docs-versioning}
Configure translation files for the `website/versioned_docs` folder.
When creating a new version, the source strings will generally be quite similar to the current version (`website/docs`), and you don't want to translate the new version docs again and again.
Crowdin provides a `Duplicate Strings` setting.
![Crowdin Duplicate Strings option setting](/img/crowdin/crowdin-settings-duplicate-strings.png)
We recommend using `Hide`, but the ideal setting depends on how much your versions are different.
:::caution
Not using `Hide` leads to a much larger amount of `source strings` in quotas, and will affect the pricing.
:::
### Multi-instance plugins {#multi-instance-plugins}
You need to configure translation files for each plugin instance.
If you have a docs plugin instance with `id=ios`, you will need to configure those source files as well
- `website/ios`
- `website/ios_versioned_docs` (if versioned)
### Maintaining your site {#maintaining-your-site}
Sometimes, you will **remove or rename a source file** on Git, and Crowdin will display CLI warnings:
![Crowdin CLI: download translation warning](/img/crowdin/crowdin-download-translations-warning.png)
When your sources are refactored, you should use the Crowdin UI to **update your Crowdin files manually**:
![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png)
### VCS (Git) integrations {#vcs-git-integrations}
Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket.
:::warning
We recommend avoiding them.
:::
It could have been helpful to be able to edit the translations in both Git and Crowdin, and have a **bi-directional sync** between the 2 systems.
In practice, **it didn't work very reliably** for a few reasons:
- The Crowdin -> Git sync works fine (with a pull request)
- The Git -> Crowdin sync is manual (you have to press a button)
- The heuristics used by Crowdin to match existing Markdown translations to existing Markdown sources are not 100% reliable, and you have to verify the result on Crowdin UI after any sync from Git
- 2 users concurrently editing on Git and Crowdin can lead to a translation loss
- It requires the `crowdin.yml` file to be at the root of the repository
### In-Context localization {#in-context-localization}
Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-localization/) feature.
:::caution
Unfortunately, it does not work yet for technical reasons, but we have good hope it can be solved.
Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and mess-up with the frontmatter, admonitions, jsx...
:::
### Localize edit urls {#localize-edit-urls}
When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`.
You may prefer the edit button to link to the Crowdin interface instead, and can use the `editUrl` function to customize the edit urls on a per-locale basis.
```js title="docusaurus.config.js"
const DefaultLocale = 'en';
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-start
editUrl: ({locale, versionDocsDirPath, docPath}) => {
// Link to Crowdin for French docs
if (locale !== DefaultLocale) {
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
}
// Link to Github for English docs
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
},
// highlight-end
},
blog: {
// highlight-start
editUrl: ({locale, blogDirPath, blogPath}) => {
if (locale !== DefaultLocale) {
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
}
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
},
// highlight-start
},
},
],
],
};
```
:::note
It is currently **not possible to link to a specific file** in Crowdin.
:::
### Example configuration {#example-configuration}
The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:
```mdx-code-block
import CrowdinConfigV2 from '!!raw-loader!@site/../crowdin-v2.yaml';
import CodeBlock from '@theme/CodeBlock';
<CodeBlock className="language-yaml" title="crowdin.yml">
{CrowdinConfigV2.split('\n')
// remove comments
.map((line) => !line.startsWith('#') && line)
.filter(Boolean)
.join('\n')}
</CodeBlock>
```

180
website/versioned_docs/version-2.0.0-alpha.75/i18n/i18n-git.md Normal file
View file

@ -0,0 +1,180 @@
---
id: git
title: i18n - Using git
slug: /i18n/git
---
A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)).
## Tradeoffs {#tradeoffs}
This strategy has advantages:
- **Easy to get started**: just add the `i18n` folder to Git
- **Easy for developers**: Git, GitHub and pull requests are mainstream developer tools
- **Free** (or without any additional cost, assuming you already use Git)
- **Low friction**: does not require signing-up to an external tool
- **Rewarding**: contributors are happy to have a nice contribution history
Using Git also present some shortcomings:
- **Hard for non-developers**: they do not master Git and pull-requests
- **Hard for professional translations**: they are used to SaaS translation softwares and advanced features
- **Hard to maintain**: you have to keep the translated files **in sync** with the untranslated files
:::note
Some **large-scale technical projects** (React, Vue.js, MDN, TypeScript, Nuxt.js, etc.) use Git for translations.
Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues/3317) for our notes and links studying these systems.
:::
## Git tutorial {#git-tutorial}
This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site:
```bash
npx @docusaurus/init@latest init website classic
```
Add the site configuration for the French language:
```js title="docusaurus.config.js"
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
themeConfig: {
navbar: {
items: [
// ...
{
type: 'localeDropdown',
position: 'left',
},
// ...
],
},
},
// ...
};
```
Translate the homepage:
```jsx title="src/pages/index.js"
import React from 'react';
import Translate from '@docusaurus/Translate';
import Layout from '@theme/Layout';
export default function Home() {
return (
<Layout>
<h1 style={{margin: 20}}>
<Translate description="The homepage main heading">
Welcome to my Docusaurus translated site!
</Translate>
</h1>
</Layout>
);
}
```
### Initialize the `i18n` folder {#initialize-the-i18n-folder}
Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale:
```bash npm2yarn
npm run write-translations -- --locale fr
1 translations written at i18n/fr/code.json
11 translations written at i18n/fr/docusaurus-theme-classic/footer.json
4 translations written at i18n/fr/docusaurus-theme-classic/navbar.json
3 translations written at i18n/fr/docusaurus-plugin-content-docs/current.json
```
:::tip
Use the `--messagePrefix '(fr) '` option to make the untranslated strings stand out.
`Hello` will appear as `(fr) Hello` and makes it clear a translation is missing.
:::
Copy your untranslated Markdown files to the French folder:
```
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog
mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -r pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
```
Add all these files to Git.
### Translate the files {#translate-the-files}
Translate the Markdown and JSON files in `i18n/fr` and commit the translation.
You should now be able to start your site in French and see the translations:
```bash npm2yarn
npm run start -- --locale fr
```
You can also build the site locally or on your CI:
```bash npm2yarn
npm run build
# or
npm run build -- --locale fr
```
### Repeat {#repeat}
Follow the same process for each locale you need to support.
## Maintain the translations {#maintain-the-translations}
Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.
### Markdown translations {#markdown-translations}
When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so.
To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.
### JSON translations {#json-translations}
To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command:
```bash npm2yarn
npm run write-translations -- --locale fr
```
New translation will be appended, and existing ones will not be overridden.
:::tip
Reset your translations with the `--override` option.
:::
### Localize edit urls {#localize-edit-urls}
When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`.
Your translations are on Git, and you can use the `editLocalizedFiles: true` option of the docs and blog plugins.
The edit button will link to the localized doc at `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.

140
website/versioned_docs/version-2.0.0-alpha.75/i18n/i18n-introduction.md Normal file
View file

@ -0,0 +1,140 @@
---
id: introduction
title: i18n - Introduction
slug: /i18n/introduction
---
It is **easy to translate a Docusaurus website** with its internationalization ([i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization)) support.
## Goals {#goals}
It is important to understand the **design decisions** behind the Docusaurus i18n support.
For more context, you can read the initial [RFC](https://github.com/facebook/docusaurus/issues/3317) and [PR](https://github.com/facebook/docusaurus/pull/3325).
### i18n goals {#i18n-goals}
The goals of the Docusaurus i18n system are:
- **Simple**: just put the translated files in the correct filesystem location
- **Flexible translation workflows**: use Git (monorepo, forks, or submodules), SaaS software, FTP
- **Flexible deployment options**: single, multiple domains, or hybrid
- **Modular**: allow plugin authors to provide i18n support
- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills
- **Scalable build-times**: allow building and deploying localized sites independently
- **Localize assets**: an image of your site might contain text that should be translated
- **No coupling**: not forced to use any SaaS, yet integrations are possible
- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2
- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
### i18n non-goals {#i18n-non-goals}
We don't provide support for:
- **Automatic locale detection**: opinionated, and best done on the [server](../deployment.mdx)
- **Translation SaaS software**: you are responsible to understand the external tools of your choice
- **Translation of slugs**: technically complicated, little SEO value
## Translation workflow {#translation-workflow}
### Overview {#overview}
Overview of the workflow to create a translated Docusaurus website:
1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`
1. **Translate**: put the translation files at the correct filesystem location
1. **Deploy**: build and deploy your site using a single or multi-domain strategy
### Translation files {#translation-files}
You will have to work with 2 kind of translation files.
#### Markdown files {#markdown-files}
This is the main content of your Docusaurus website.
Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string.
#### JSON files {#json-files}
JSON is used to translate:
- your React code: using the `<Translate>` component
- your theme: the navbar, footer
- your plugins: the docs sidebar category labels
The JSON format used is called **Chrome i18n**:
```json
{
"myTranslationKey1": {
"message": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
},
"myTranslationKey2": {
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
}
}
```
The choice was made for 2 reasons:
- **Description attribute**: to help translators with additional context
- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json)
### Translation files location {#translation-files-location}
The translation files should be created at the correct filesystem location.
Each locale and plugin has its own `i18n` subfolder:
```
website/i18n/<locale>/<pluginName>/...
```
:::note
For multi-instance plugins, the path is `website/i18n/<locale>/<pluginName>-<pluginId>/...`.
:::
Translating a very simple Docusaurus site in French would lead to the following tree:
```bash
website/i18n
└── fr
├── code.json
│
├── docusaurus-plugin-content-blog
│   └── 2020-01-01-hello.md
│
├── docusaurus-plugin-content-docs
│   ├── current #
│   │   ├── doc1.md
│   │   └── doc2.mdx
│   └── current.json
│
└── docusaurus-theme-classic
├── footer.json
└── navbar.json
```
The JSON files are initialized with the [`docusaurus write-translations`](../cli.md#docusaurus-write-translations) CLI command.
The `code.json` file is extracted from React components using the `<Translate>` API.
:::info
Notice that the `docusaurus-plugin-content-docs` plugin has a `current` subfolder and a `current.json` file, useful for the **docs versioning feature**.
:::
Each content plugin or theme is different, and **define its own translation files location**:
- [Docs i18n](../api/plugins/plugin-content-docs.md#i18n)
- [Blog i18n](../api/plugins/plugin-content-blog.md#i18n)
- [Pages i18n](../api/plugins/plugin-content-pages.md#i18n)
- [Themes i18n](../api/themes/theme-configuration.md#i18n)

336
website/versioned_docs/version-2.0.0-alpha.75/i18n/i18n-tutorial.md Normal file
View file

@ -0,0 +1,336 @@
---
id: tutorial
title: i18n - Tutorial
slug: /i18n/tutorial
---
This tutorial will walk you through the basis of the **Docusaurus i18n system**.
We will add **French** translations to a **newly initialized English Docusaurus website**.
Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)).
## Configure your site {#configure-your-site}
Modify `docusaurus.config.js` to add the i18n support for the French language.
### Site configuration {#site-configuration}
Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales:
```js title="docusaurus.config.js"
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
};
```
### Theme configuration {#theme-configuration}
Add a **navbar item** of type `localeDropdown` so that users can select the locale they want:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'localeDropdown',
position: 'left',
},
// highlight-end
],
},
},
};
```
### Start your site {#start-your-site}
Start your localized site in dev mode, using the locale of your choice:
```bash npm2yarn
npm run start -- --locale fr
```
Your site is accessible at **`http://localhost:3000/fr/`**.
We haven't provided any translation, and the site is **mostly untranslated**.
:::tip
Docusaurus provides **default translations** for generic theme labels, such as "Next" and "Previous" for the pagination.
Please help us complete those **[default translations](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)**.
:::
:::caution
Each locale is a **distinct standalone single-page-application**: it is not possible to start the Docusaurus sites in all locales at the same time.
:::
## Translate your site {#translate-your-site}
The French translations will be added in `website/i18n/fr`.
Docusaurus is modular, and each content plugin has its own subfolder.
:::note
After copying files around, restart your site with `npm run start -- --locale fr`.
Hot-reload will work better when editing existing files.
:::
### Use the translation APIs {#use-the-translation-apis}
Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate):
```jsx title="src/pages/index.js"
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';
// highlight-start
import Translate, {translate} from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout>
<h1>
{/* highlight-start */}
<Translate>Welcome to my website</Translate>
{/* highlight-end */}
</h1>
<main>
{/* highlight-start */}
<Translate
id="homepage.visitMyBlog"
description="The homepage message to ask the user to visit my blog"
values={{blog: <Link to="https://docusaurus.io/blog">blog</Link>}}>
{'You can also visit my {blog}'}
</Translate>
{/* highlight-end */}
<input
type="text"
placeholder={
// highlight-start
translate({
message: 'Hello',
description: 'The homepage input placeholder',
})
// highlight-end
}
/>
</main>
</Layout>
);
}
```
:::caution
Docusaurus provides a **very small and lightweight translation runtime** on purpose, and only supports basic [placeholders interpolation](../docusaurus-core.md#interpolate), using a subset of the [ICU Message Format](https://formatjs.io/docs/core-concepts/icu-syntax/).
Most documentation websites are generally **static** and don't need advanced i18n features (**plurals**, **genders**, etc.). Use a library like [react-intl](https://www.npmjs.com/package/react-intl) for more advanced use-cases.
:::
### Translate JSON files {#translate-json-files}
JSON translation files are used for everything that is not contained in a Markdown document:
- React/JSX code
- Layout navbar and footer labels
- Docs sidebar category labels
- ...
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 homepage translations are statically extracted from React source code:
```json title="i18n/fr/code.json"
{
"Welcome to my website": {
"message": "Welcome to my website",
"description": "The homepage welcome message"
},
"Hello": {
"message": "Hello",
"description": "The homepage input placeholder"
}
}
```
Plugins and themes will also write their own **JSON translation files**, such as:
```json title="i18n/fr/docusaurus-theme-classic/navbar.json"
{
"title": {
"message": "My Site",
"description": "The title in the navbar"
},
"item.label.Docs": {
"message": "Docs",
"description": "Navbar item with label Docs"
},
"item.label.Blog": {
"message": "Blog",
"description": "Navbar item with label Blog"
},
"item.label.GitHub": {
"message": "GitHub",
"description": "Navbar item with label GitHub"
}
}
```
Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated.
### Translate Markdown files {#translate-markdown-files}
Official Docusaurus content plugins extensively use Markdown/MDX files, and allow you to translate them.
#### Translate the docs {#translate-the-docs}
Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them:
```bash
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
```
:::info
`current` is needed for the docs versioning feature: each docs version has its own subfolder.
:::
#### Translate the blog {#translate-the-blog}
Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them:
```bash
mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog
```
#### Translate the pages {#translate-the-pages}
Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them:
```bash
mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -r pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
```
:::caution
We only copy `.md` and `.mdx` files, as pages React components are translated through JSON translation files already.
:::
### Use explicit heading ids {#use-explicit-heading-ids}
By default, a Markdown heading `### Hello World` will have a generated id `hello-world`.
Other documents can target it with `[link](#hello-world)`.
The translated heading becomes `### Bonjour le Monde`, with id `bonjour-le-monde`.
Generated ids are not always a good fit for localized sites, as it requires you to localize all the anchor links:
```diff
- [link](#hello-world).
+ [link](#bonjour-le-monde)
```
:::tip
For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-headings.mdx#explicit-ids)**.
:::
## Deploy your site {#deploy-your-site}
You can choose to deploy your site under a **single domain**, or use **multiple (sub)domains**.
### Single-domain deployment {#single-domain-deployment}
Run the following command:
```bash npm2yarn
npm run build
```
Docusaurus will build **one single-page application per locale**:
- `website/build`: for the default, English language
- `website/build/fr`: for the French language
You can now [deploy](../deployment.mdx) the `build` folder to the static hosting solution of your choice.
:::note
The Docusaurus v2 website use this strategy:
- [https://docusaurus.io](https://docusaurus.io)
- [https://docusaurus.io/fr](https://docusaurus.io/fr)
:::
:::tip
Static hosting providers generally redirect `/unknown/urls` to `/404.html` by convention, always showing an **English 404 page**.
**Localize your 404 pages** by configuring your host to redirect `/fr/*` to `/fr/404.html`.
This is not always possible, and depends on your host: GitHub Pages can't do this, [Netlify](https://docs.netlify.com/routing/redirects/redirect-options/#custom-404-page-handling) can.
:::
### Multi-domain deployment {#multi-domain-deployment}
You can also build your site for a single locale:
```bash npm2yarn
npm run build -- --locale fr
```
Docusaurus will not add the `/fr/` URL prefix.
On your [static hosting provider](../deployment.mdx):
- create one deployment per locale
- configure the appropriate build command, using the `--locale` option
- configure the (sub)domain of your choice for each deployment
:::caution
This strategy is **not possible** with Github Pages, as it is only possible to **have a single deployment**.
:::
### Hybrid {#hybrid}
It is possible to have some locales using sub-paths, and others using subdomains.
It is also possible to deploy each locale as a separate subdomain, assemble the subdomains in a single unified domain at the CDN level:
- Deploy your site as `fr.docusaurus.io`
- Configure a CDN to serve it from `docusaurus.io/fr`

157
website/versioned_docs/version-2.0.0-alpha.75/installation.md Normal file
View file

@ -0,0 +1,157 @@
---
id: installation
title: Installation
---
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/master/packages) that can be installed over npm.
:::tip
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in CodeSandbox.
:::
## Requirements {#requirements}
- [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed
- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.
## Scaffold project website {#scaffold-project-website}
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
```bash
npx @docusaurus/init@latest init [name] [template]
```
Example:
```bash
npx @docusaurus/init@latest init my-website classic
```
If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
**[FB-Only]:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults:
```bash
npx @docusaurus/init@latest init my-website facebook
```
**[Experimental]:** If you want setting up a new website using [bootstrap](https://getbootstrap.com/), use the `bootstrap` template, like the following:
```bash
npx @docusaurus/init@latest init my-website bootstrap
```
If you want to skip installing dependencies, use the `--skip-install` option, like the following:
```bash
npx @docusaurus/init@latest init my-website classic --skip-install
```
## Project structure {#project-structure}
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`:
```sh
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
```
### Project structure rundown {#project-structure-rundown}
- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md)
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
- `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md)
- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory
- `/docusaurus.config.js` - A config file containing the site configuration. This is the equivalent of `siteConfig.js` in Docusaurus v1
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
## Running the development server {#running-the-development-server}
To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.
```bash npm2yarn
cd my-website
npm run start
```
By default, a browser window will open at http://localhost:3000.
Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.
## Build {#build}
Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
```bash npm2yarn
npm run build
```
and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.mdx) for more details.
## Updating your Docusaurus version {#updating-your-docusaurus-version}
There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version.
:::important
Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below.
:::
```json title="package.json"
"dependencies": {
"@docusaurus/core": "^2.0.0-alpha.49",
"@docusaurus/preset-classic": "^2.0.0-alpha.49",
// ...
}
```
Then, in the directory containing `package.json`, run your package manager's install command:
```bash npm2yarn
npm install
```
To check that the update occurred successfully, run:
```bash npm2yarn
npx docusaurus --version
```
You should see the correct version as output.
Alternatively, if you are using Yarn, you can do:
```bash
yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
```
## Problems? {#problems}
Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus) or [Twitter](https://twitter.com/docusaurus).

121
website/versioned_docs/version-2.0.0-alpha.75/introduction.md Normal file
View file

@ -0,0 +1,121 @@
---
id: introduction
title: Introduction
description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
slug: /
---
## Disclaimer {#disclaimer}
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
We highly encourage you to **use Docusaurus v2 over Docusaurus v1**.
Most users are already using v2 ([trends](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)), including [React Native](https://reactnative.dev), [Redux](https://redux.js.org/) and [many others](/showcase).
**Use Docusaurus v2 if:**
- :white_check_mark: You want a modern Jamstack documentation site
- :white_check_mark: You want a single-page application (SPA) with client-side routing
- :white_check_mark: You want the full power of React and MDX
- :white_check_mark: You do not need support for IE11
:::tip
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in CodeSandbox.
:::
**Use [Docusaurus v1](https://v1.docusaurus.io/) if:**
- :x: You don't want a single-page application (SPA)
- :x: You prefer stability over modernity
- :x: You need support for IE11
## A better Docusaurus is coming to town {#a-better-docusaurus-is-coming-to-town}
![Docusaurus Slash Introduction](/img/slash-introducing.svg)
Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).
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.**
## Features {#features}
Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.
- ⚛️ **Built with 💚 and React**
- Extend and customize with React
- Gain full control of your site's browsing experience by `swizzling` in your own components
- **Pluggable**
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
- Open source your plugins to share with your fellow documentarians, because sharing is caring
- ✂️ **Developer experience**
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
- Universal configuration entry point to make it more maintainable by contributors
- Hot reloading with lightning fast incremental build on changes
- Route-based code and data splitting
- Publish to GitHub Pages, Netlify, and other deployment services with ease
Our shared goal — to help your users find what they need fast, and understand your products better. With the experience of Docusaurus 1, we share with you our best practices to help you build your doc site right and well.
- 🎯 **SEO friendly**
- HTML files are statically generated for every possible path
- page-specific SEO to help your users land on your official docs directly relating their problems at hand
- 📝 **Powered by MDX**
- Write interactive components via JSX and React embedded in markdown
- Share your code in live editors to get your users love your products on the spot
- 🔍 **Search** - Your full site is searchable
- 💾 **Document Versioning** - Helps you keep documentation in sync with project releases.
- 🌍 **i18n**
Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.
- ⚡️ **Lightning fast** - Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
- 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users
## Comparison with other tools {#comparison-with-other-tools}
Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.
We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help you navigate through the prismatic choices out there.
### Gatsby {#gatsby}
Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
### GitBook {#gitbook}
GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
### Jekyll {#jekyll}
Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
### VuePress {#vuepress}
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
<!-- TODO: Add a Next.js comparison -->
## Staying informed {#staying-informed}
- [GitHub](https://github.com/facebook/docusaurus)
- [Twitter](https://twitter.com/docusaurus)
- [Blog](/blog)
## Something missing? {#something-missing}
If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/facebook/docusaurus) for us, or send a tweet mentioning the [@docusaurus](https://twitter.com/docusaurus) Twitter account.
For new feature requests, you can create a post on our [Canny board](/feedback), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!

814
website/versioned_docs/version-2.0.0-alpha.75/lifecycle-apis.md Normal file
View file

@ -0,0 +1,814 @@
---
id: lifecycle-apis
title: Lifecycle APIs
---
:::caution
This section is a work in progress.
:::
Lifecycle APIs are shared by Themes and Plugins.
## `validateOptions({options, validate})` {#validateoptionsoptions-validate}
Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during initialization.
### `options` {#options}
`validateOptions` is called with `options` passed to plugin for validation and normalization.
### `validate` {#validate}
`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
:::tip
[Joi](https://www.npmjs.com/package/joi) is recommended for validation and normalization of options.
To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-validation")`
:::
If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options and return options in case of success.
```js {8-11} title="my-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// rest of methods
};
};
module.exports.validateOptions = ({options, validate}) => {
const validatedOptions = validate(myValidationSchema, options);
return validationOptions;
};
```
You can also use ES modules style exports.
```ts {8-11} title="my-plugin/src/index.ts"
export default function (context, options) {
return {
name: 'docusaurus-plugin',
// rest of methods
};
}
export function validateOptions({options, validate}) {
const validatedOptions = validate(myValidationSchema, options);
return validationOptions;
}
```
## `validateThemeConfig({themeConfig, validate})` {#validatethemeconfigthemeconfig-validate}
Return validated and normalized configuration for the theme.
### `themeConfig` {#themeconfig}
`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
### `validate` {#validate-1}
`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
:::tip
[Joi](https://www.npmjs.com/package/joi) is recommended for validation and normalization of theme config.
To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-validation")`
:::
If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options.
```js {8-11} title="my-theme/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// rest of methods
};
};
module.exports.validateThemeConfig = ({themeConfig, validate}) => {
const validatedThemeConfig = validate(myValidationSchema, options);
return validatedThemeConfig;
};
```
You can also use ES modules style exports.
```ts {8-11} title="my-theme/src/index.ts"
export default function (context, options) {
return {
name: 'docusaurus-plugin',
// rest of methods
};
}
export function validateThemeConfig({themeConfig, validate}) {
const validatedThemeConfig = validate(myValidationSchema, options);
return validatedThemeConfig;
}
```
## `getPathsToWatch()` {#getpathstowatch}
Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site.
Example:
```js {5-7} title="docusaurus-plugin/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
getPathsToWatch() {
const contentPath = path.resolve(context.siteDir, options.path);
return [`${contentPath}/**/*.{ts,tsx}`];
},
};
};
```
## `async loadContent()` {#async-loadcontent}
Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.
For example, this plugin below return a random integer between 1 to 10 as content;
```js {5-6} title="docusaurus-plugin/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
async loadContent() {
return 1 + Math.floor(Math.random() * 10);
},
};
};
```
## `async contentLoaded({content, actions})` {#async-contentloadedcontent-actions}
Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional).
### `content` {#content}
`contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
### `actions` {#actions}
`actions` contain two functions:
- `addRoute(config: RouteConfig): void`
Create a route to add to the website.
```typescript
interface RouteConfig {
path: string;
component: string;
modules?: RouteModule;
routes?: RouteConfig[];
exact?: boolean;
priority?: number;
}
interface RouteModule {
[module: string]: Module | RouteModule | RouteModule[];
}
type Module =
| {
path: string;
__import?: boolean;
query?: ParsedUrlQueryInput;
}
| string;
```
- `createData(name: string, data: any): Promise<string>`
A function to help you create static data (generally json or string), that you can provide to your routes as props.
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
```jsx title="website/src/components/Friends.js"
import React from 'react';
export default function FriendsComponent({friends}) {
return <div>Your friends are {friends.join(',')}</div>;
}
```
```js {4-23} title="docusaurus-friends-plugin/src/index.js"
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
async contentLoaded({content, actions}) {
const {createData, addRoute} = actions;
// Create friends.json
const friends = ['Yangshun', 'Sebastien'];
const friendsJsonPath = await createData(
'friends.json',
JSON.stringify(friends),
);
// Add the '/friends' routes, and ensure it receives the friends props
addRoute({
path: '/friends',
component: '@site/src/components/Friends.js',
modules: {
// propName -> JSON file path
friends: friendsJsonPath,
},
exact: true,
});
},
};
}
```
- `setGlobalData(data: any): void`
This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout.
This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string).
One this data is created, you can access it with the global data hooks APIs.
:::caution
Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small.
Prefer `createData` and page-specific data whenever possible.
:::
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
```jsx title="website/src/components/Friends.js"
import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';
export default function FriendsComponent() {
const {friends} = usePluginData('my-friends-plugin');
return <div>Your friends are {friends.join(',')}</div>;
}
```
```js {4-14} title="docusaurus-friends-plugin/src/index.js"
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
async contentLoaded({content, actions}) {
const {setGlobalData, addRoute} = actions;
// Create friends global data
setGlobalData({friends: ['Yangshun', 'Sebastien']});
// Add the '/friends' routes
addRoute({
path: '/friends',
component: '@site/src/components/Friends.js',
exact: true,
});
},
};
}
```
## `configureWebpack(config, isServer, utils)` {#configurewebpackconfig-isserver-utils}
Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument.
### `config` {#config}
`configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with.
### `isServer` {#isserver}
`configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`.
### `utils` {#utils}
The initial call to `configureWebpack` also receives a util object consists of three functions:
- `getStyleLoaders(isServer: boolean, cssOptions: {[key: string]: any}): Loader[]`
- `getCacheLoader(isServer: boolean, cacheOptions?: {}): Loader | null`
- `getBabelLoader(isServer: boolean, babelOptions?: {}): Loader`
You may use them to return your webpack configures conditionally.
For example, this plugin below modify the webpack config to transpile `.foo` file.
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'custom-docusaurus-plugin',
// highlight-start
configureWebpack(config, isServer, utils) {
const {getCacheLoader} = utils;
return {
module: {
rules: [
{
test: /\.foo$/,
use: [getCacheLoader(isServer), 'my-custom-webpack-loader'],
},
],
},
};
},
// highlight-end
};
};
```
### Merge strategy {#merge-strategy}
We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
It is possible to specify the merge strategy. For example, if you want a webpack rule to be prepended instead of appended:
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'custom-docusaurus-plugin',
configureWebpack(config, isServer, utils) {
return {
// highlight-start
mergeStrategy: {'module.rules': 'prepend'},
module: {rules: [myRuleToPrepend]},
// highlight-end
};
},
};
};
```
Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
## `configurePostCss(options)` {#configurepostcssoptions}
Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle.
Should return the mutated `postcssOptions`.
By default, `postcssOptions` looks like this:
```js
const postcssOptions = {
ident: 'postcss',
plugins: [require('autoprefixer')],
};
```
Example:
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
configurePostCss(postcssOptions) {
// Appends new PostCSS plugin.
postcssOptions.plugins.push(require('postcss-import'));
return postcssOptions;
},
// highlight-end
};
};
```
## `postBuild(props)` {#postbuildprops}
Called when a (production) build finishes.
```ts
type Props = {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
headTags: string;
preBodyTags: string;
postBodyTags: string;
routesPaths: string[];
plugins: Plugin<any>[];
};
```
Example:
```js {4-11} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// Print out to console all the rendered routes.
routesPaths.map((route) => {
console.log(route);
});
},
};
};
```
## `extendCli(cli)` {#extendclicli}
Register an extra command to enhance the CLI of docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander) object.
Example:
```js {4-11} title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
extendCli(cli) {
cli
.command('roll')
.description('Roll a random number between 1 and 1000')
.action(() => {
console.log(Math.floor(Math.random() * 1000 + 1));
});
},
};
};
```
## `injectHtmlTags()` {#injecthtmltags}
Inject head and/or body HTML tags to Docusaurus generated HTML.
```typescript
function injectHtmlTags(): {
headTags?: HtmlTags;
preBodyTags?: HtmlTags;
postBodyTags?: HtmlTags;
};
type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
interface HtmlTagObject {
/**
* Attributes of the HTML tag
* E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
*/
attributes?: {
[attributeName: string]: string | boolean;
};
/**
* The tag name e.g. `div`, `script`, `link`, `meta`
*/
tagName: string;
/**
* The inner HTML
*/
innerHTML?: string;
}
```
Example:
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
injectHtmlTags() {
return {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'preconnect',
href: 'https://www.github.com',
},
},
],
preBodyTags: [
{
tagName: 'script',
attributes: {
charset: 'utf-8',
src: '/noflash.js',
},
},
],
postBodyTags: [`<div> This is post body </div>`],
};
},
// highlight-end
};
};
```
## `getThemePath()` {#getthemepath}
Returns the path to the directory where the theme components can be found. When your users calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
If you use the folder directory above, your `getThemePath` can be:
```js {6-8} title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'name-of-my-theme',
getThemePath() {
return path.resolve(__dirname, './theme');
},
};
};
```
## `getTypeScriptThemePath()` {#gettypescriptthemepath}
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components.
If you want to support TypeScript component swizzling for your theme, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make path returned by `getThemePath()` be the compiled JavaScript output.
Example:
```js {6-13} title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'name-of-my-theme',
getThemePath() {
// Where compiled JavaScript output lives
return path.join(__dirname, '..', 'lib', 'theme');
},
getTypeScriptThemePath() {
// Where TypeScript source code lives
return path.resolve(__dirname, './theme');
},
};
};
```
## `getSwizzleComponentList()` {#getswizzlecomponentlist}
Return a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned then all components are considered unstable, if `undefined` is returned then all component are considered stable.
```js {0-12} title="my-theme/src/index.js"
const swizzleAllowedComponents = [
'CodeBlock',
'DocSidebar',
'Footer',
'NotFound',
'SearchBar',
'hooks/useTheme',
'prism-include-languages',
];
module.exports.getSwizzleComponentList = () => swizzleAllowedComponents;
```
## `getClientModules()` {#getclientmodules}
Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.
As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
```js {7-9} title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
const {customCss, customJs} = options || {};
return {
name: 'name-of-my-theme',
getClientModules() {
return [customCss, customJs];
},
};
};
```
<!--
For example, the in docusaurus-plugin-content-docs:
In loadContent, it loads the doc Markdown files based on the specified directory in options (defaulting to docs).
In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
-->
## i18n lifecycles {#i18n-lifecycles}
### `getTranslationFiles({content})` {#get-translation-files}
Plugins declare the JSON translation files they want to use.
Returns translation files `{path: string, content: ChromeI18nJSON}`:
- Path: relative to the plugin localized folder `i18n/<locale>/pluginName`. Extension `.json` is not necessary.
- Content: using the Chrome i18n JSON format
These files will be written by the [`write-translations` CLI](./cli.md#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translate-content) and [`translateThemeConfig()`](#translate-theme-config)
Example:
```js
module.exports = function (context, options) {
return {
name: 'my-plugin',
// highlight-start
async getTranslationFiles({content}) {
return [
{
path: 'sidebar-labels',
content: {
someSidebarLabel: {
message: 'Some Sidebar Label',
description: 'A label used in my plugin in the sidebar',
},
someLabelFromContent: content.myLabel,
},
},
];
},
// highlight-end
};
};
```
### `translateContent({content,translationFiles})` {#translate-content}
Translate the plugin content, using the localized translation files.
Returns the localized plugin content.
The `contentLoaded()` lifecycle will be called with the localized plugin content returned by `translateContent()`.
Example:
```js
module.exports = function (context, options) {
return {
name: 'my-plugin',
// highlight-start
translateContent({content, translationFiles}) {
const myTranslationFile = translationFiles.find(
(f) => f.path === 'myTranslationFile',
);
return {
...content,
someContentLabel: myTranslationFile.someContentLabel.message,
};
},
// highlight-end
};
};
```
### `translateThemeConfig({themeConfig,translationFiles})` {#translate-theme-config}
Translate the site `themeConfig` labels, using the localized translation files.
Returns the localized `themeConfig`.
Example:
```js
module.exports = function (context, options) {
return {
name: 'my-theme',
// highlight-start
translateThemeConfig({themeConfig, translationFiles}) {
const myTranslationFile = translationFiles.find(
(f) => f.path === 'myTranslationFile',
);
return {
...themeConfig,
someThemeConfigLabel: myTranslationFile.someThemeConfigLabel.message,
};
},
// highlight-end
};
};
```
### `async getDefaultCodeTranslationMessages()` {#get-default-code-translation-messages}
Themes using the `<Translate>` API can provide default code translation messages.
It should return messages in `Record<string,string`>, where keys are translation ids and values are messages (without the description) localized using the site current locale.
Example:
```js
module.exports = function (context, options) {
return {
name: 'my-theme',
// highlight-start
async getDefaultCodeTranslationMessages() {
return readJsonFile(`${context.i18n.currentLocale}.json`);
},
// highlight-end
};
};
```
## Example {#example}
Here's a mind model for a presumptuous plugin implementation.
```jsx
const DEFAULT_OPTIONS = {
// Some defaults.
};
// A JavaScript function that returns an object.
// `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
// `opts` is the user-defined options.
module.exports = function (context, opts) {
// Merge defaults with user-defined options.
const options = {...DEFAULT_OPTIONS, ...options};
return {
// A compulsory field used as the namespace for directories to cache
// the intermediate data for each plugin.
// If you're writing your own local plugin, you will want it to
// be unique in order not to potentially conflict with imported plugins.
// A good way will be to add your own project name within.
name: 'docusaurus-my-project-cool-plugin',
async loadContent() {
// The loadContent hook is executed after siteConfig and env has been loaded.
// You can return a JavaScript object that will be passed to contentLoaded hook.
},
async contentLoaded({content, actions}) {
// The contentLoaded hook is done after loadContent hook is done.
// `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
},
async postBuild(props) {
// After docusaurus <build> finish.
},
// TODO
async postStart(props) {
// docusaurus <start> finish
},
// TODO
afterDevServer(app, server) {
// https://webpack.js.org/configuration/dev-server/#devserverbefore
},
// TODO
beforeDevServer(app, server) {
// https://webpack.js.org/configuration/dev-server/#devserverafter
},
configureWebpack(config, isServer) {
// Modify internal webpack config. If returned value is an Object, it
// will be merged into the final config using webpack-merge;
// If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
},
getPathsToWatch() {
// Paths to watch.
},
getThemePath() {
// Returns the path to the directory where the theme components can
// be found.
},
getClientModules() {
// Return an array of paths to the modules that are to be imported
// in the client bundle. These modules are imported globally before
// React even renders the initial UI.
},
extendCli(cli) {
// Register an extra command to enhance the CLI of Docusaurus
},
injectHtmlTags() {
// Inject head and/or body HTML tags.
},
async getTranslationFiles() {
// Return translation files
},
translateContent({content, translationFiles}) {
// translate the plugin content here
},
translateThemeConfig({themeConfig, translationFiles}) {
// translate the site themeConfig here
},
async getDefaultCodeTranslationMessages() {
// return default theme translations here
},
};
};
```

75
website/versioned_docs/version-2.0.0-alpha.75/migration/migration-automated.md Normal file
View file

@ -0,0 +1,75 @@
---
id: migration-automated
title: Automated migration
slug: /migration/automated
---
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 [structure](#) shown at the start of this page.
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
cd ./v2-website
yarn install
yarn 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.
:::

613
website/versioned_docs/version-2.0.0-alpha.75/migration/migration-manual.md Normal file
View file

@ -0,0 +1,613 @@
---
id: migration-manual
title: Manual migration
slug: /migration/manual
---
This manual migration process should be run after the [automated migration process](./migration-automated.md), 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-alpha.48",
+ "@docusaurus/preset-classic": "^2.0.0-alpha.48",
}
}
```
:::tip
Please use the most recent Docusaurus 2 alpha version, which you can check out [here](https://www.npmjs.com/package/@docusaurus/core) (it's tagged `next`).
:::
#### 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-alpha.66",
"@docusaurus/preset-classic": "^2.0.0-alpha.66",
"clsx": "^1.1.1",
"react": "^16.8.4",
"react-dom": "^16.8.4"
},
"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/master/packages/docusaurus-init/templates/classic/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`.
```jsx 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. [Now](https://zeit.co/now) supports [Docusaurus project deployments out-of-the-box](https://github.com/zeit/now-examples/tree/master/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.
Alteratively, 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`:
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
footer: {
logo: {
alt: 'Facebook Open Source Logo',
src: 'https://docusaurus.io/img/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',
// Equivalent to `docsSideNavCollapsible`.
sidebarCollapsible: false,
// ...
},
};
```
#### `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:
```jsx {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}
```jsx {4-8} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { //... },
},
// ...
},
};
```
#### `blogSidebarCount` {#blogsidebarcount}
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
```jsx {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:
```jsx {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/master/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}
```jsx {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
// ...
},
};
```
#### `gaGtag` {#gagtag}
```jsx {5} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
gtag: {
trackingID: 'UA-141789564-1',
},
// ...
},
};
```
### 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 `themeConfig.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](./using-plugins.md#docusaurusplugin-client-redirects) 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` frontmatter.
## 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.md#understanding-sidebar-items) 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](using-themes.md#swizzling-theme-components) 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: 'Facebook Open Source Logo',
src: 'img/oss_logo.png',
href: 'https://opensource.facebook.com',
},
},
},
};
```
### Pages {#pages}
Please refer to [creating pages](guides/creating-pages.md) 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/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/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-inline-toc.mdx)
### 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.
Frontmatter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your frontmatter 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 `author_image_url` 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:
```sh
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
cd website
yarn start
```
You can also try to build the site for production:
```bash
yarn build
```

95
website/versioned_docs/version-2.0.0-alpha.75/migration/migration-overview.md Normal file
View file

@ -0,0 +1,95 @@
---
id: migration-overview
title: Migration overview
slug: /migration
---
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.
## Docusaurus 1 structure {#docusaurus-1-structure}
Your Docusaurus 1 site should have the following structure:
```sh
├── 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.md) 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.md) will give you all the manual steps.
## Support {#support}
For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord channel](https://discordapp.com/invite/kYaNd6V).
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.

167
website/versioned_docs/version-2.0.0-alpha.75/migration/migration-translated-sites.md Normal file
View file

@ -0,0 +1,167 @@
---
id: migration-translated-sites
title: Translated sites
slug: /migration/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/<lang>/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.
:::caution
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.md) 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 (frontmatter, 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.
:::caution
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 master 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.

176
website/versioned_docs/version-2.0.0-alpha.75/migration/migration-versioned-sites.md Normal file
View file

@ -0,0 +1,176 @@
---
id: migration-versioned-sites
title: Versioned sites
slug: /migration/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.md)
:::
## 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` frontmatter 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 frontmatter, 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`.
```shell
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 frontmatter and id reference too).
```shell {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>
```

182
website/versioned_docs/version-2.0.0-alpha.75/presets.md Normal file
View file

@ -0,0 +1,182 @@
---
id: presets
title: Presets
---
Presets are collections of plugins and themes.
## Using presets {#using-presets}
A preset is usually a npm package, so you install them like other npm packages using npm.
```bash npm2yarn
npm install --save docusaurus-preset-name
```
Then, add it in your site's `docusaurus.config.js`'s `presets` option:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
presets: ['@docusaurus/preset-xxxx'],
};
```
To load presets from your local directory, specify how to resolve them:
```jsx {5} title="docusaurus.config.js"
const path = require('path');
module.exports = {
// ...
presets: [path.resolve(__dirname, '/path/to/docusaurus-local-presets')],
};
```
## Presets -> themes and plugins {#presets---themes-and-plugins}
Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,
```js
module.exports = function preset(context, opts = {}) {
return {
themes: [
require.resolve('@docusaurus/themes-cool'),
require.resolve('@docusaurus/themes-bootstrap'),
],
plugins: [require.resolve('@docusaurus/plugin-blog')],
};
};
```
then in your Docusaurus config, you may configure the preset instead:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
presets: ['@docusaurus/preset-my-own'],
};
```
This is equivalent of doing:
```jsx title="docusaurus.config.js"
module.exports = {
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
plugins: ['@docusaurus/plugin-blog'],
};
```
This is especially useful when some plugins and themes are intended to be used together.
## Official presets {#official-presets}
### `@docusaurus/preset-classic` {#docusauruspreset-classic}
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
| Themes | Plugins |
| ---------------------------------- | ------------------------------------- |
| `@docusaurus/theme-classic` | `@docusaurus/plugin-content-docs` |
| `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog` |
| | `@docusaurus/plugin-content-pages` |
| | `@docusaurus/plugin-debug` |
| | `@docusaurus/plugin-google-analytics` |
| | `@docusaurus/plugin-google-gtag` |
| | `@docusaurus/plugin-sitemap` |
To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// Debug defaults to true in dev, false in prod
debug: undefined,
// Will be passed to @docusaurus/theme-classic.
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
docs: {},
// Will be passed to @docusaurus/plugin-content-blog (false to disable)
blog: {},
// Will be passed to @docusaurus/plugin-content-pages (false to disable)
pages: {},
// Will be passed to @docusaurus/plugin-content-sitemap (false to disable)
sitemap: {},
},
],
],
};
```
In addition to these plugins and themes, `@docusaurus/theme-classic` adds [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions) as a remark plugin to `@docusaurus/plugin-content-blog` and `@docusaurus/plugin-content-docs`.
The `admonitions` key will be passed as the [options](https://github.com/elviswolcott/remark-admonitions#options) to `remark-admonitions`. Passing `false` will prevent the plugin from being added to MDX.
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// options for remark-admonitions
admonitions: {},
},
},
],
],
};
```
### `@docusaurus/preset-bootstrap` {#docusauruspreset-bootstrap}
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
| Themes | Plugins |
| ----------------------------- | ---------------------------------- |
| `@docusaurus/theme-bootstrap` | `@docusaurus/plugin-content-docs` |
| | `@docusaurus/plugin-content-blog` |
| | `@docusaurus/plugin-content-pages` |
| | `@docusaurus/plugin-debug` |
To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `docs` for `@docusaurus/theme-bootstrap`, pass them in the preset field, like this:
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-bootstrap',
{
// Debug defaults to true in dev, false in prod
debug: undefined,
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
docs: {},
// Will be passed to @docusaurus/plugin-content-blog (false to disable)
blog: {},
},
],
],
};
```
:::caution
This preset is work in progress
:::
<!--
Advanced guide on using and configuring presets
References
---
- [classic themes](/packages/docusaurus-preset-classic/src/index.js)
- [babel docs on presets](https://babeljs.io/docs/en/presets)
-->

189
website/versioned_docs/version-2.0.0-alpha.75/search.md Normal file
View file

@ -0,0 +1,189 @@
---
id: search
title: Search
keywords:
- algolia
- search
---
Docusaurus' own `@docusaurus/preset-classic` supports a search integration.
There are two main options, you can use [Algolia DocSearch](https://docsearch.algolia.com) or bring in your own `SearchBar` component.
## Using Algolia DocSearch {#using-algolia-docsearch}
Algolia DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (i.e., not behind a firewall). The service is free.
If your website is [not eligible](https://docsearch.algolia.com/docs/who-can-apply) for the free, hosted version of DocSearch, or if your website sits behind a firewall, then you can [run your own](https://docsearch.algolia.com/docs/run-your-own/) DocSearch crawler. For best results, you may want to use a config file based on the [Docusaurus 2 config](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json).
### Connecting Algolia {#connecting-algolia}
To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. **[Apply for DocSearch](https://docsearch.algolia.com/apply/)** to get your Algolia index and API key.
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// ...
// highlight-start
algolia: {
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
// Optional: see doc section below
contextualSearch: true,
// Optional: see doc section below
appId: 'YOUR_APP_ID',
// Optional: Algolia search parameters
searchParameters: {},
//... other Algolia params
},
// highlight-end
},
};
```
:::info
The `searchParameters` option used to be named `algoliaOptions` in Docusaurus v1.
:::
### Contextual search {#contextual-search}
Contextual search is mostly useful for versioned Docusaurus sites.
Let's consider you have 2 docs versions, v1 and v2. When you are browsing v2 docs, it would be odd to return search results for the v1 documentation. Sometimes v1 and v2 docs are quite similar, and you would end up with duplicate search results for the same query (one result per version).
To solve this problem, the contextual search feature understands that you are browsing a specific docs version, and will create the search query filters dynamically.
- browsing `/docs/v1/myDoc`, search results will only include **v1** docs (+ other unversioned pages)
- browsing `/docs/v2/myDoc`, search results will only include **v2** docs (+ other unversioned pages)
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// ...
// highlight-start
algolia: {
contextualSearch: true,
},
// highlight-end
},
};
```
:::caution
When using `contextualSearch: true`, the contextual facet filters will be merged with the ones provided with `algolia.searchParameters.facetFilters`.
:::
### Custom Application ID {#custom-application-id}
When [running your own](https://docsearch.algolia.com/docs/run-your-own/) DocSearch crawler, it is [required to set the `appId` configuration key](https://docsearch.algolia.com/docs/behavior/#appid) to your own Application ID. If left unset, the `appId` will fallback to the one used with the free, hosted version of Algolia DocSearch.
```jsx title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
// ...
// highlight-start
algolia: {
appId: 'YOUR_APP_ID',
},
// highlight-end
},
};
```
### Styling your Algolia search {#styling-your-algolia-search}
By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.
Still, you can reuse the [Infima CSS variables](styling-layout#styling-your-site-with-infima) from Docusaurus to style DocSearch by editing the `/src/css/custom.css` file.
```css title="/src/css/custom.css"
html[data-theme='light'] .DocSearch {
/* --docsearch-primary-color: var(--ifm-color-primary); */
/* --docsearch-text-color: var(--ifm-font-color-base); */
--docsearch-muted-color: var(--ifm-color-secondary-darkest);
--docsearch-container-background: rgba(94, 100, 112, 0.7);
/* Modal */
--docsearch-modal-background: var(--ifm-color-secondary-lighter);
/* Search box */
--docsearch-searchbox-background: var(--ifm-color-secondary);
--docsearch-searchbox-focus-background: var(--ifm-color-white);
/* Hit */
--docsearch-hit-color: var(--ifm-font-color-base);
--docsearch-hit-active-color: var(--ifm-color-white);
--docsearch-hit-background: var(--ifm-color-white);
/* Footer */
--docsearch-footer-background: var(--ifm-color-white);
}
html[data-theme='dark'] .DocSearch {
--docsearch-text-color: var(--ifm-font-color-base);
--docsearch-muted-color: var(--ifm-color-secondary-darkest);
--docsearch-container-background: rgba(47, 55, 69, 0.7);
/* Modal */
--docsearch-modal-background: var(--ifm-background-color);
/* Search box */
--docsearch-searchbox-background: var(--ifm-background-color);
--docsearch-searchbox-focus-background: var(--ifm-color-black);
/* Hit */
--docsearch-hit-color: var(--ifm-font-color-base);
--docsearch-hit-active-color: var(--ifm-color-white);
--docsearch-hit-background: var(--ifm-color-emphasis-100);
/* Footer */
--docsearch-footer-background: var(--ifm-background-surface-color);
--docsearch-key-gradient: linear-gradient(
-26.5deg,
var(--ifm-color-emphasis-200) 0%,
var(--ifm-color-emphasis-100) 100%
);
}
```
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// ...
algolia: {
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
// Options...
},
},
};
```
### Editing the Algolia search component {#editing-the-algolia-search-component}
If you prefer to edit the Algolia search React component, swizzle the `SearchBar` component in `@docusaurus/theme-search-algolia`:
```bash npm2yarn
npm run swizzle @docusaurus/theme-search-algolia SearchBar
```
## Using your own search {#using-your-own-search}
To use your own search, swizzle the `SearchBar` component in `@docusaurus/theme-classic`
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic SearchBar
```
This will create a `src/themes/SearchBar` file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own `SearchBar` component now.
**Notes**: You can alternatively [swizzle from Algolia SearchBar](#editing-the-algolia-search-component) and create your own search component from there.

77
website/versioned_docs/version-2.0.0-alpha.75/static-assets.md Normal file
View file

@ -0,0 +1,77 @@
---
id: static-assets
title: Static Assets
---
Every website needs assets: images, stylesheets, favicons etc. In such cases, you can create a directory named `static` at the root of your project.
Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
This means that:
- for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`.
- for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`.
## Referencing your static asset {#referencing-your-static-asset}
You can reference assets from the `static` folder in your code using absolute paths, but this is not ideal because changing the site `baseUrl` will **break those link**s.
You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
### JSX example {#jsx-example}
```jsx title="MyComponent.js"
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;
```
```jsx title="MyComponent.js"
<img src={require('@site/static/img/docusaurus.png').default} />
```
```jsx title="MyComponent.js"
import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;
```
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';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
```
### Markdown example {#markdown-example}
Markdown links and images referencing assets of the static folder will be converted to `require("@site/static/assetName.png")"`, and **the site baseUrl will be automatically prepended** for you.
```md title="my-doc.md"
![Docusaurus](/img/docusaurus.png)
```
Thanks to MDX, you can also use `useBaseUrl` utility function in Markdown files! You'd have to use html tags like `<img>` instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
```jsx title="my-doc.mdx"
---
id: my-doc
title: My Doc
---
// Add to the top of the file below the front matter.
import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />
```
### Caveats {#caveats}
Keep in mind that:
- By default, none of the files in `static` folder will be post-processed, hashed or minified.
- Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting.

229
website/versioned_docs/version-2.0.0-alpha.75/styling-layout.md Normal file
View file

@ -0,0 +1,229 @@
---
id: styling-layout
title: Styling and Layout
description: A Docusaurus site is a pre-rendered single-page React application. You can style it the way you style React apps.
---
import ColorGenerator from '@site/src/components/ColorGenerator';
## Traditional CSS {#traditional-css}
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset.
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-start
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
// highlight-end
},
],
],
};
```
Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization.
## 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 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 `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file.
```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);
--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`.
<ColorGenerator/>
### Dark Mode {#dark-mode}
To customize the Infima variables for dark mode you can add the following to `src/css/custom.css`.
```css title="/src/css/custom.css"
html[data-theme='dark'] {
--ifm-color-primary: #4e89e8;
--ifm-color-primary-dark: #5a91ea;
/* any other colors you wish to overwrite */
}
```
<!-- TODO need more refinement here -->
## Styling approaches {#styling-approaches}
A Docusaurus site is a single-page React application. You can style it the way you style React apps.
There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from a more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.
### Global styles {#global-styles}
This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.
Assuming you are using `@docusaurus/preset-classic` and `/src/css/custom.css` was passed in to the preset config, styles inside that file would be available globally.
```css title="/src/css/custom.css"
.purple-text {
color: rebeccapurple;
}
```
```jsx
function MyComponent() {
return (
<main>
<h1 className="purple-text">Purple Heading!</h1>
</main>
);
}
```
#### Theme Class Names
We provide some predefined CSS class names to provide access for developers to style layout of a page globally in Docusaurus. The purpose is to have stable classnames shared by all themes that are meant to be targeted by custom CSS.
```mdx-code-block
import ThemeClassNamesCode from '!!raw-loader!@site/../packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts';
import CodeBlock from '@theme/CodeBlock';
<CodeBlock className="language-ts">
{ThemeClassNamesCode
// remove source comments
.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g,'')
.trim()}
</CodeBlock>
```
### CSS modules {#css-modules}
To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
```css title="styles.module.css"
.main {
padding: 12px;
}
.heading {
font-weight: bold;
}
.contents {
color: #ccc;
}
```
```jsx
import styles from './styles.module.css';
function MyComponent() {
return (
<main className={styles.main}>
<h1 className={styles.heading}>Hello!</h1>
<article className={styles.contents}>Lorem Ipsum</article>
</main>
);
}
```
The class names which will be processed by webpack into a globally unique class name during build.
### CSS-in-JS {#css-in-js}
:::caution
This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).
:::
### Sass/SCSS {#sassscss}
To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach:
1. Install [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass):
```bash npm2yarn
npm install --save docusaurus-plugin-sass
```
2. Include the plugin in your `docusaurus.config.js` file:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
```
3. Write and import your stylesheets in Sass/SCSS as normal.
#### Global styles using Sass/SCSS {#global-styles-using-sassscss}
You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
```jsx {8} title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// ...
theme: {
customCss: [require.resolve('./src/css/custom.scss')],
},
// ...
},
],
],
};
```
#### Modules using Sass/SCSS {#modules-using-sassscss}
Name your stylesheet files with the `.module.scss` suffix (e.g. `welcome.module.scss`) instead of `.css`. Webpack will use `sass-loader` to preprocess your stylesheets and load them as CSS modules.
```scss title="styles.module.scss"
.main {
padding: 12px;
article {
color: #ccc;
}
}
```
```jsx
import styles from './styles.module.scss';
function MyComponent() {
return (
<main className={styles.main}>
<article>Lorem Ipsum</article>
</main>
);
}
```

35
website/versioned_docs/version-2.0.0-alpha.75/typescript-support.md Normal file
View file

@ -0,0 +1,35 @@
---
id: typescript-support
title: TypeScript Support
---
## Setup {#setup}
Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project:
```bash npm2yarn
npm install --save-dev typescript @docusaurus/module-type-aliases @types/react @types/react-router-dom @types/react-helmet @tsconfig/docusaurus
```
Then add `tsconfig.json` to your project root with the following content:
```json title="tsconfig.json"
{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"include": ["src/"]
}
```
Docusaurus doesn't use this `tsconfig.json` to compile your project. It is added just for a nicer Editor experience, although you can choose to run `tsc` to type check your code for yourself or on CI.
Now you can start writing TypeScript theme components.
## Swizzling TypeScript theme components {#swizzling-typescript-theme-components}
For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`.
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Footer -- --typescript
```
At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./lifecycle-apis.md#gettypescriptthemepath).

177
website/versioned_docs/version-2.0.0-alpha.75/using-plugins.md Normal file
View file

@ -0,0 +1,177 @@
---
id: using-plugins
title: Plugins
---
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via [presets](presets.md).
## Available plugins {#available-plugins}
We maintain a [list of official plugins](./api/plugins/overview.md), but the community has also created some [unofficial plugins](/community/resources#community-plugins).
## Installing a plugin {#installing-a-plugin}
A plugin is usually a npm package, so you install them like other npm packages using npm.
```bash npm2yarn
npm install --save docusaurus-plugin-name
```
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};
```
Docusaurus can also load plugins from your local directory, you can do something like the following:
```jsx {5} title="docusaurus.config.js"
const path = require('path');
module.exports = {
// ...
plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
};
```
## Configuring plugins {#configuring-plugins}
For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.
However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
```js {4-9} title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};
```
Example:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
// Basic usage.
'@docusaurus/plugin-google-analytics',
// With options object (babel style)
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};
```
## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids}
All Docusaurus content plugins can support multiple plugin instances.
The Docs plugin has [additional multi-instance documentation](./guides/docs/docs-multi-instance.mdx)
It is required to assign a unique id to each plugin instance.
By default, the plugin id is `default`.
```js {6,13} title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-xxx',
{
id: 'plugin-xxx-1',
// other options
},
],
[
'@docusaurus/plugin-xxx',
{
id: 'plugin-xxx-2',
// other options
},
],
],
};
```
:::note
At most one plugin instance can be the "default plugin instance", by omitting the `id` attribute, or using `id: 'default'`.
:::
## Plugins design {#plugins-design}
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
## Creating plugins {#creating-plugins}
A plugin is a module which exports a function that takes two parameters and returns an object when executed.
### Module definition {#module-definition}
The exported modules for plugins are called with two parameters: `context` and `options` and returns a JavaScript object with defining the [lifecycle APIs](./lifecycle-apis.md).
For example if you have a reference to a local folder such as this in your `docusaurus.config.js`:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [path.resolve(__dirname, 'my-plugin')],
};
```
Then in the folder `my-plugin` you can create an index.js such as this
```js title="index.js"
module.exports = function (context, options) {
// ...
return {
name: 'my-docusaurus-plugin',
async loadContent() {
/* ... */
},
async contentLoaded({content, actions}) {
/* ... */
},
/* other lifecycle API */
};
};
```
The `my-plugin` folder could also be a fully fledged package with it's own package.json and a `src/index.js` file for example
#### `context` {#context}
`context` is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields:
```ts
interface LoadContext {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
}
```
#### `options` {#options}
`options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
#### Return value {#return-value}
The returned object value should implement the [lifecycle APIs](lifecycle-apis.md).

Some files were not shown because too many files have changed in this diff Show more