diff --git a/CHANGELOG.md b/CHANGELOG.md index f0738d5c0f..3d3c27cf1b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,63 @@ # Docusaurus 2 Changelog +## 2.0.0-beta.6 (2021-09-02) + +#### :rocket: New Feature + +- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` + - [#5428](https://github.com/facebook/docusaurus/pull/5428) feat: adds blog archive route ([@gabrielcsapo](https://github.com/gabrielcsapo)) +- `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#5462](https://github.com/facebook/docusaurus/pull/5462) feat: on back navigation, close mobile sidebar ([@slorber](https://github.com/slorber)) + - [#5445](https://github.com/facebook/docusaurus/pull/5445) feat: Add docs-related stable classnames ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic` + - [#5460](https://github.com/facebook/docusaurus/pull/5460) feat: infima 33 + navbar-sidebar close button ([@slorber](https://github.com/slorber)) + - [#5442](https://github.com/facebook/docusaurus/pull/5442) feat(theme-classic): allow passing tab label and default value through TabItem ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` + - [#5454](https://github.com/facebook/docusaurus/pull/5454) feat: new docs options: versions.{badge,className} ([@slorber](https://github.com/slorber)) + +#### :bug: Bug Fix + +- `docusaurus-theme-classic` + - [#5444](https://github.com/facebook/docusaurus/pull/5444) fix: fix some theme UI issues (blockquotes, navbar-sidebar font) with Infima alpha.32 ([@slorber](https://github.com/slorber)) + - [#5431](https://github.com/facebook/docusaurus/pull/5431) fix: some beta.5 bugfixes ([@slorber](https://github.com/slorber)) +- `docusaurus-init`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` + - [#5437](https://github.com/facebook/docusaurus/pull/5437) fix: fix a few TS errors ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :nail_care: Polish + +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` + - [#5459](https://github.com/facebook/docusaurus/pull/5459) refactor(theme-classic): completely migrate package to TypeScript ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic` + - [#5453](https://github.com/facebook/docusaurus/pull/5453) refactor: use SVG for closable button in announcement bar ([@lex111](https://github.com/lex111)) + - [#5430](https://github.com/facebook/docusaurus/pull/5430) refactor: switch to Flexbox in announcement bar ([@lex111](https://github.com/lex111)) + - [#5434](https://github.com/facebook/docusaurus/pull/5434) refactor: update Arabic and Persian translations ([@3alisaki](https://github.com/3alisaki)) + - [#5410](https://github.com/facebook/docusaurus/pull/5410) refactor: add missing translations in fa.json ([@farshidinanloo](https://github.com/farshidinanloo)) + +#### :memo: Documentation + +- [#5471](https://github.com/facebook/docusaurus/pull/5471) docs: Add docusaurus-plugin-relative-paths ([@ohkimur](https://github.com/ohkimur)) +- [#5464](https://github.com/facebook/docusaurus/pull/5464) docs: add mapillary-js to showcase ([@oscarlorentzon](https://github.com/oscarlorentzon)) +- [#5433](https://github.com/facebook/docusaurus/pull/5433) docs: document doc tags + refinements ([@Josh-Cena](https://github.com/Josh-Cena)) +- [#5435](https://github.com/facebook/docusaurus/pull/5435) docs: Add netboot.xyz to site showcase ([@antonym](https://github.com/antonym)) +- [#5436](https://github.com/facebook/docusaurus/pull/5436) docs: add Redocusaurus in community plugin list ([@rohit-gohri](https://github.com/rohit-gohri)) + +#### :house: Internal + +- [#5455](https://github.com/facebook/docusaurus/pull/5455) fix: website bad version name in docusaurus.config.js ([@slorber](https://github.com/slorber)) + +#### Committers: 10 + +- Alexey Pyltsyn ([@lex111](https://github.com/lex111)) +- Ali Saki ([@3alisaki](https://github.com/3alisaki)) +- Antony Messerli ([@antonym](https://github.com/antonym)) +- Daniel Costrasel ([@ohkimur](https://github.com/ohkimur)) +- Gabriel Csapo ([@gabrielcsapo](https://github.com/gabrielcsapo)) +- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena)) +- Oscar Lorentzon ([@oscarlorentzon](https://github.com/oscarlorentzon)) +- Rohit Gohri ([@rohit-gohri](https://github.com/rohit-gohri)) +- SΓ©bastien Lorber ([@slorber](https://github.com/slorber)) +- farshid ([@farshidinanloo](https://github.com/farshidinanloo)) + ## 2.0.0-beta.5 (2021-08-26) #### :rocket: New Feature diff --git a/admin/new.docusaurus.io/package.json b/admin/new.docusaurus.io/package.json index fb71b9fdcc..397ddc4089 100644 --- a/admin/new.docusaurus.io/package.json +++ b/admin/new.docusaurus.io/package.json @@ -1,6 +1,6 @@ { "name": "new.docusaurus.io", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "private": true, "scripts": { "start": "netlify dev" diff --git a/lerna.json b/lerna.json index 29477fe35c..489f9a67ad 100644 --- a/lerna.json +++ b/lerna.json @@ -1,5 +1,5 @@ { - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "npmClient": "yarn", "useWorkspaces": true, "changelog": { diff --git a/packages/docusaurus-cssnano-preset/package.json b/packages/docusaurus-cssnano-preset/package.json index abf8339f0b..b0228f4713 100644 --- a/packages/docusaurus-cssnano-preset/package.json +++ b/packages/docusaurus-cssnano-preset/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/cssnano-preset", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Advanced cssnano preset for maximum optimization.", "main": "index.js", "license": "MIT", diff --git a/packages/docusaurus-init/package.json b/packages/docusaurus-init/package.json index 743c5202fc..6acd3431f9 100644 --- a/packages/docusaurus-init/package.json +++ b/packages/docusaurus-init/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/init", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Create Docusaurus apps easily.", "repository": { "type": "git", diff --git a/packages/docusaurus-init/templates/bootstrap/package.json b/packages/docusaurus-init/templates/bootstrap/package.json index b9880ac53c..0a22efa47e 100644 --- a/packages/docusaurus-init/templates/bootstrap/package.json +++ b/packages/docusaurus-init/templates/bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-bootstrap-template", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -14,8 +14,8 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/preset-bootstrap": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/preset-bootstrap": "2.0.0-beta.6", "@mdx-js/react": "^1.6.21", "@svgr/webpack": "^5.5.0", "clsx": "^1.1.1", diff --git a/packages/docusaurus-init/templates/classic-typescript/package.json b/packages/docusaurus-init/templates/classic-typescript/package.json index b9c0c4b704..50610d8402 100644 --- a/packages/docusaurus-init/templates/classic-typescript/package.json +++ b/packages/docusaurus-init/templates/classic-typescript/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-classic-typescript-template", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -15,8 +15,8 @@ "typecheck": "tsc" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/preset-classic": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/preset-classic": "2.0.0-beta.6", "@mdx-js/react": "^1.6.21", "@svgr/webpack": "^5.5.0", "clsx": "^1.1.1", @@ -27,7 +27,7 @@ "url-loader": "^4.1.1" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.5", + "@docusaurus/module-type-aliases": "2.0.0-beta.6", "@tsconfig/docusaurus": "^1.0.4", "@types/react": "^17.0.14", "@types/react-helmet": "^6.1.2", diff --git a/packages/docusaurus-init/templates/classic/package.json b/packages/docusaurus-init/templates/classic/package.json index b1c9128869..910bfde689 100644 --- a/packages/docusaurus-init/templates/classic/package.json +++ b/packages/docusaurus-init/templates/classic/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-classic-template", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -14,8 +14,8 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/preset-classic": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/preset-classic": "2.0.0-beta.6", "@mdx-js/react": "^1.6.21", "@svgr/webpack": "^5.5.0", "clsx": "^1.1.1", diff --git a/packages/docusaurus-init/templates/facebook/package.json b/packages/docusaurus-init/templates/facebook/package.json index 6b12580714..c492c22956 100644 --- a/packages/docusaurus-init/templates/facebook/package.json +++ b/packages/docusaurus-init/templates/facebook/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-facebook-template", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", - "@docusaurus/preset-classic": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/preset-classic": "2.0.0-beta.6", "@mdx-js/react": "^1.6.21", "@svgr/webpack": "^5.5.0", "clsx": "^1.1.1", diff --git a/packages/docusaurus-mdx-loader/package.json b/packages/docusaurus-mdx-loader/package.json index cc1e491e04..9d31cf1641 100644 --- a/packages/docusaurus-mdx-loader/package.json +++ b/packages/docusaurus-mdx-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/mdx-loader", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Docusaurus Loader for MDX", "main": "lib/index.js", "types": "src/types.d.ts", @@ -20,8 +20,8 @@ "dependencies": { "@babel/parser": "^7.12.16", "@babel/traverse": "^7.12.13", - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", "@mdx-js/mdx": "^1.6.21", "@mdx-js/react": "^1.6.21", "chalk": "^4.1.1", @@ -38,7 +38,7 @@ "webpack": "^5.40.0" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.5", + "@docusaurus/types": "2.0.0-beta.6", "@types/escape-html": "^1.0.1", "@types/mdast": "^3.0.7", "@types/stringify-object": "^3.3.1", diff --git a/packages/docusaurus-migrate/package.json b/packages/docusaurus-migrate/package.json index 9668794296..3a965ceb5c 100644 --- a/packages/docusaurus-migrate/package.json +++ b/packages/docusaurus-migrate/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/migrate", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "A CLI tool to migrate from older versions of Docusaurus.", "main": "lib/index.js", "license": "MIT", diff --git a/packages/docusaurus-module-type-aliases/package.json b/packages/docusaurus-module-type-aliases/package.json index bc78c3f358..756e27f78d 100644 --- a/packages/docusaurus-module-type-aliases/package.json +++ b/packages/docusaurus-module-type-aliases/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/module-type-aliases", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Docusaurus module type aliases.", "types": "./src/index.d.ts", "publishConfig": { diff --git a/packages/docusaurus-plugin-client-redirects/package.json b/packages/docusaurus-plugin-client-redirects/package.json index cba9593043..817d76bd7f 100644 --- a/packages/docusaurus-plugin-client-redirects/package.json +++ b/packages/docusaurus-plugin-client-redirects/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-client-redirects", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Client redirects plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-client-redirects.d.ts", @@ -18,11 +18,11 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-common": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-common": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "chalk": "^4.1.1", "eta": "^1.11.0", "fs-extra": "^10.0.0", diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json index 087a29df48..59e004655c 100644 --- a/packages/docusaurus-plugin-content-blog/package.json +++ b/packages/docusaurus-plugin-content-blog/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-blog", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Blog plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-content-blog.d.ts", @@ -18,11 +18,11 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/mdx-loader": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/mdx-loader": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "chalk": "^4.1.1", "escape-string-regexp": "^4.0.0", "feed": "^4.2.2", diff --git a/packages/docusaurus-plugin-content-docs/package.json b/packages/docusaurus-plugin-content-docs/package.json index d8da274300..612bfb139f 100644 --- a/packages/docusaurus-plugin-content-docs/package.json +++ b/packages/docusaurus-plugin-content-docs/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-docs", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", + "@docusaurus/module-type-aliases": "2.0.0-beta.6", "@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-beta.5", - "@docusaurus/mdx-loader": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/mdx-loader": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "chalk": "^4.1.1", "combine-promises": "^1.1.0", "escape-string-regexp": "^4.0.0", diff --git a/packages/docusaurus-plugin-content-pages/package.json b/packages/docusaurus-plugin-content-pages/package.json index 0a44da5572..35e405c066 100644 --- a/packages/docusaurus-plugin-content-pages/package.json +++ b/packages/docusaurus-plugin-content-pages/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-pages", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", - "@docusaurus/mdx-loader": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/mdx-loader": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "globby": "^11.0.2", "lodash": "^4.17.20", "remark-admonitions": "^1.2.1", diff --git a/packages/docusaurus-plugin-debug/package.json b/packages/docusaurus-plugin-debug/package.json index 0c814c7c06..394e555919 100644 --- a/packages/docusaurus-plugin-debug/package.json +++ b/packages/docusaurus-plugin-debug/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-debug", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Debug plugin for Docusaurus.", "main": "lib/index.js", "types": "src/types.d.ts", @@ -18,9 +18,9 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", "fs-extra": "^9.1.0", "react-json-view": "^1.21.3", "tslib": "^2.1.0" diff --git a/packages/docusaurus-plugin-google-analytics/package.json b/packages/docusaurus-plugin-google-analytics/package.json index 48646a43c7..c4e65cafc8 100644 --- a/packages/docusaurus-plugin-google-analytics/package.json +++ b/packages/docusaurus-plugin-google-analytics/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-analytics", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5" + "@docusaurus/core": "2.0.0-beta.6" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-google-gtag/package.json b/packages/docusaurus-plugin-google-gtag/package.json index 6263aef8e5..fabac2318d 100644 --- a/packages/docusaurus-plugin-google-gtag/package.json +++ b/packages/docusaurus-plugin-google-gtag/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-gtag", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5" + "@docusaurus/core": "2.0.0-beta.6" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-ideal-image/package.json b/packages/docusaurus-plugin-ideal-image/package.json index 0ca4906e6e..5fb7eb7443 100644 --- a/packages/docusaurus-plugin-ideal-image/package.json +++ b/packages/docusaurus-plugin-ideal-image/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-ideal-image", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).", "main": "lib/index.js", "scripts": { @@ -20,10 +20,10 @@ "fs-extra": "^9.1.0" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/lqip-loader": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/lqip-loader": "2.0.0-beta.6", "@docusaurus/responsive-loader": "1.4.0", - "@docusaurus/types": "2.0.0-beta.5", + "@docusaurus/types": "2.0.0-beta.6", "@endiliey/react-ideal-image": "^0.0.11", "react-waypoint": "^10.1.0", "sharp": "^0.28.2", diff --git a/packages/docusaurus-plugin-pwa/package.json b/packages/docusaurus-plugin-pwa/package.json index 348a46e30e..a5aa5b3a72 100644 --- a/packages/docusaurus-plugin-pwa/package.json +++ b/packages/docusaurus-plugin-pwa/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-pwa", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Docusaurus Plugin to add PWA support.", "main": "src/index.js", "publishConfig": { @@ -16,10 +16,10 @@ "@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-beta.5", - "@docusaurus/theme-common": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/theme-common": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "babel-loader": "^8.2.2", "clsx": "^1.1.1", "core-js": "^2.6.5", diff --git a/packages/docusaurus-plugin-sitemap/package.json b/packages/docusaurus-plugin-sitemap/package.json index ac9666f0ee..69e921710d 100644 --- a/packages/docusaurus-plugin-sitemap/package.json +++ b/packages/docusaurus-plugin-sitemap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-sitemap", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Simple sitemap generation plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-sitemap.d.ts", @@ -18,11 +18,11 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-common": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-common": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "fs-extra": "^10.0.0", "sitemap": "^7.0.0", "tslib": "^2.2.0" diff --git a/packages/docusaurus-preset-bootstrap/package.json b/packages/docusaurus-preset-bootstrap/package.json index 10051c3298..236c6461e4 100644 --- a/packages/docusaurus-preset-bootstrap/package.json +++ b/packages/docusaurus-preset-bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/preset-bootstrap", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", - "@docusaurus/plugin-content-blog": "2.0.0-beta.5", - "@docusaurus/plugin-content-docs": "2.0.0-beta.5", - "@docusaurus/plugin-content-pages": "2.0.0-beta.5", - "@docusaurus/theme-bootstrap": "2.0.0-beta.5" + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-content-blog": "2.0.0-beta.6", + "@docusaurus/plugin-content-docs": "2.0.0-beta.6", + "@docusaurus/plugin-content-pages": "2.0.0-beta.6", + "@docusaurus/theme-bootstrap": "2.0.0-beta.6" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index 0af8fa82f4..a116ba5055 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/preset-classic", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Classic preset for Docusaurus.", "main": "src/index.js", "types": "src/preset-classic.d.ts", @@ -14,16 +14,16 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/plugin-content-blog": "2.0.0-beta.5", - "@docusaurus/plugin-content-docs": "2.0.0-beta.5", - "@docusaurus/plugin-content-pages": "2.0.0-beta.5", - "@docusaurus/plugin-debug": "2.0.0-beta.5", - "@docusaurus/plugin-google-analytics": "2.0.0-beta.5", - "@docusaurus/plugin-google-gtag": "2.0.0-beta.5", - "@docusaurus/plugin-sitemap": "2.0.0-beta.5", - "@docusaurus/theme-classic": "2.0.0-beta.5", - "@docusaurus/theme-search-algolia": "2.0.0-beta.5" + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-content-blog": "2.0.0-beta.6", + "@docusaurus/plugin-content-docs": "2.0.0-beta.6", + "@docusaurus/plugin-content-pages": "2.0.0-beta.6", + "@docusaurus/plugin-debug": "2.0.0-beta.6", + "@docusaurus/plugin-google-analytics": "2.0.0-beta.6", + "@docusaurus/plugin-google-gtag": "2.0.0-beta.6", + "@docusaurus/plugin-sitemap": "2.0.0-beta.6", + "@docusaurus/theme-classic": "2.0.0-beta.6", + "@docusaurus/theme-search-algolia": "2.0.0-beta.6" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-remark-plugin-npm2yarn/package.json b/packages/docusaurus-remark-plugin-npm2yarn/package.json index 7fca3f8cec..25a1457f1b 100644 --- a/packages/docusaurus-remark-plugin-npm2yarn/package.json +++ b/packages/docusaurus-remark-plugin-npm2yarn/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/remark-plugin-npm2yarn", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Remark plugin for converting npm commands to Yarn commands as tabs.", "main": "src/index.js", "publishConfig": { diff --git a/packages/docusaurus-theme-bootstrap/package.json b/packages/docusaurus-theme-bootstrap/package.json index 509a5ffbb2..52e5ba7c8c 100644 --- a/packages/docusaurus-theme-bootstrap/package.json +++ b/packages/docusaurus-theme-bootstrap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-bootstrap", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", - "@docusaurus/plugin-content-blog": "2.0.0-beta.5", - "@docusaurus/plugin-content-docs": "2.0.0-beta.5", - "@docusaurus/plugin-content-pages": "2.0.0-beta.5", - "@docusaurus/theme-common": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-content-blog": "2.0.0-beta.6", + "@docusaurus/plugin-content-docs": "2.0.0-beta.6", + "@docusaurus/plugin-content-pages": "2.0.0-beta.6", + "@docusaurus/theme-common": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", "@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-beta.5" + "@docusaurus/module-type-aliases": "2.0.0-beta.6" }, "scripts": { "build": "yarn babel && yarn prettier", diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index 12f6eabc6e..370f4ef06a 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-classic", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Classic theme for Docusaurus", "main": "lib/index.js", "types": "src/types.d.ts", @@ -23,15 +23,15 @@ "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/plugin-content-blog": "2.0.0-beta.5", - "@docusaurus/plugin-content-docs": "2.0.0-beta.5", - "@docusaurus/plugin-content-pages": "2.0.0-beta.5", - "@docusaurus/theme-common": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-common": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-content-blog": "2.0.0-beta.6", + "@docusaurus/plugin-content-docs": "2.0.0-beta.6", + "@docusaurus/plugin-content-pages": "2.0.0-beta.6", + "@docusaurus/theme-common": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-common": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "@mdx-js/mdx": "^1.6.21", "@mdx-js/react": "^1.6.21", "chalk": "^4.1.1", @@ -50,7 +50,7 @@ "rtlcss": "^3.1.2" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.5", + "@docusaurus/module-type-aliases": "2.0.0-beta.6", "@types/mdx-js__react": "^1.5.4", "@types/parse-numeric-range": "^0.0.1", "@types/rtlcss": "^3.1.1", diff --git a/packages/docusaurus-theme-common/package.json b/packages/docusaurus-theme-common/package.json index 2aecb69292..463d211064 100644 --- a/packages/docusaurus-theme-common/package.json +++ b/packages/docusaurus-theme-common/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-common", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Common code for Docusaurus themes.", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -18,17 +18,17 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/plugin-content-blog": "2.0.0-beta.5", - "@docusaurus/plugin-content-docs": "2.0.0-beta.5", - "@docusaurus/plugin-content-pages": "2.0.0-beta.5", - "@docusaurus/types": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-content-blog": "2.0.0-beta.6", + "@docusaurus/plugin-content-docs": "2.0.0-beta.6", + "@docusaurus/plugin-content-pages": "2.0.0-beta.6", + "@docusaurus/types": "2.0.0-beta.6", "clsx": "^1.1.1", "fs-extra": "^10.0.0", "tslib": "^2.1.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.5", + "@docusaurus/module-type-aliases": "2.0.0-beta.6", "lodash": "^4.17.20" }, "peerDependencies": { diff --git a/packages/docusaurus-theme-live-codeblock/package.json b/packages/docusaurus-theme-live-codeblock/package.json index b3fc2e91bd..c8fca3ee81 100644 --- a/packages/docusaurus-theme-live-codeblock/package.json +++ b/packages/docusaurus-theme-live-codeblock/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-live-codeblock", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Docusaurus live code block component.", "main": "src/index.js", "publishConfig": { @@ -13,8 +13,8 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "@philpl/buble": "^0.19.7", "clsx": "^1.1.1", "parse-numeric-range": "^1.2.0", diff --git a/packages/docusaurus-theme-search-algolia/package.json b/packages/docusaurus-theme-search-algolia/package.json index af6693c30e..e6e3daccfa 100644 --- a/packages/docusaurus-theme-search-algolia/package.json +++ b/packages/docusaurus-theme-search-algolia/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-search-algolia", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Algolia search component for Docusaurus.", "main": "src/index.js", "publishConfig": { @@ -14,10 +14,10 @@ "license": "MIT", "dependencies": { "@docsearch/react": "^3.0.0-alpha.39", - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/theme-common": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/theme-common": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "algoliasearch": "^4.8.4", "algoliasearch-helper": "^3.3.4", "clsx": "^1.1.1", diff --git a/packages/docusaurus-types/package.json b/packages/docusaurus-types/package.json index b30a4f44d2..b2ae8bfe04 100644 --- a/packages/docusaurus-types/package.json +++ b/packages/docusaurus-types/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/types", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Common types for Docusaurus packages.", "main": "./src/index.js", "types": "./src/index.d.ts", diff --git a/packages/docusaurus-utils-common/package.json b/packages/docusaurus-utils-common/package.json index 1ce19bec22..52e5bc8ffa 100644 --- a/packages/docusaurus-utils-common/package.json +++ b/packages/docusaurus-utils-common/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils-common", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Common (Node/Browser) 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-beta.5", + "@docusaurus/types": "2.0.0-beta.6", "tslib": "^2.2.0" }, "engines": { diff --git a/packages/docusaurus-utils-validation/package.json b/packages/docusaurus-utils-validation/package.json index 60bee7d435..233e1f7706 100644 --- a/packages/docusaurus-utils-validation/package.json +++ b/packages/docusaurus-utils-validation/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils-validation", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", + "@docusaurus/utils": "2.0.0-beta.6", "chalk": "^4.1.1", "joi": "^17.4.0", "tslib": "^2.1.0" diff --git a/packages/docusaurus-utils/package.json b/packages/docusaurus-utils/package.json index bd5e438b50..9cc9b9e472 100644 --- a/packages/docusaurus-utils/package.json +++ b/packages/docusaurus-utils/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "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-beta.5", + "@docusaurus/types": "2.0.0-beta.6", "@types/github-slugger": "^1.3.0", "chalk": "^4.1.1", "escape-string-regexp": "^4.0.0", diff --git a/packages/docusaurus/package.json b/packages/docusaurus/package.json index cb0388f290..30ee8ef218 100644 --- a/packages/docusaurus/package.json +++ b/packages/docusaurus/package.json @@ -1,7 +1,7 @@ { "name": "@docusaurus/core", "description": "Easy to Maintain Open Source Documentation Websites", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "license": "MIT", "publishConfig": { "access": "public" @@ -31,7 +31,7 @@ "url": "https://github.com/facebook/docusaurus/issues" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.5", + "@docusaurus/module-type-aliases": "2.0.0-beta.6", "@types/detect-port": "^1.3.0", "@types/nprogress": "^0.2.0", "tmp-promise": "^3.0.2" @@ -47,12 +47,12 @@ "@babel/runtime": "^7.12.5", "@babel/runtime-corejs3": "^7.12.13", "@babel/traverse": "^7.12.13", - "@docusaurus/cssnano-preset": "2.0.0-beta.5", + "@docusaurus/cssnano-preset": "2.0.0-beta.6", "@docusaurus/react-loadable": "5.5.0", - "@docusaurus/types": "2.0.0-beta.5", - "@docusaurus/utils": "2.0.0-beta.5", - "@docusaurus/utils-common": "2.0.0-beta.5", - "@docusaurus/utils-validation": "2.0.0-beta.5", + "@docusaurus/types": "2.0.0-beta.6", + "@docusaurus/utils": "2.0.0-beta.6", + "@docusaurus/utils-common": "2.0.0-beta.6", + "@docusaurus/utils-validation": "2.0.0-beta.6", "@slorber/static-site-generator-webpack-plugin": "^4.0.0", "@svgr/webpack": "^5.5.0", "autoprefixer": "^10.2.5", diff --git a/packages/lqip-loader/package.json b/packages/lqip-loader/package.json index d3f4a53ee2..b7abb6b261 100644 --- a/packages/lqip-loader/package.json +++ b/packages/lqip-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/lqip-loader", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Low Quality Image Placeholders (LQIP) loader for webpack.", "main": "src/index.js", "publishConfig": { diff --git a/packages/stylelint-copyright/package.json b/packages/stylelint-copyright/package.json index 6a66064841..debcb85068 100644 --- a/packages/stylelint-copyright/package.json +++ b/packages/stylelint-copyright/package.json @@ -1,6 +1,6 @@ { "name": "stylelint-copyright", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "description": "Stylelint plugin to check CSS files for a copyright header.", "main": "index.js", "license": "MIT", diff --git a/website/package.json b/website/package.json index 90e5e9b2d4..440038691e 100644 --- a/website/package.json +++ b/website/package.json @@ -1,6 +1,6 @@ { "name": "website", - "version": "2.0.0-beta.5", + "version": "2.0.0-beta.6", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -29,13 +29,13 @@ "dependencies": { "@crowdin/cli": "^3.5.2", "@crowdin/crowdin-api-client": "^1.10.6", - "@docusaurus/core": "2.0.0-beta.5", - "@docusaurus/plugin-client-redirects": "2.0.0-beta.5", - "@docusaurus/plugin-ideal-image": "2.0.0-beta.5", - "@docusaurus/plugin-pwa": "2.0.0-beta.5", - "@docusaurus/preset-classic": "2.0.0-beta.5", - "@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.5", - "@docusaurus/theme-live-codeblock": "2.0.0-beta.5", + "@docusaurus/core": "2.0.0-beta.6", + "@docusaurus/plugin-client-redirects": "2.0.0-beta.6", + "@docusaurus/plugin-ideal-image": "2.0.0-beta.6", + "@docusaurus/plugin-pwa": "2.0.0-beta.6", + "@docusaurus/preset-classic": "2.0.0-beta.6", + "@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.6", + "@docusaurus/theme-live-codeblock": "2.0.0-beta.6", "clsx": "^1.1.1", "color": "^3.1.3", "esbuild-loader": "2.13.1", diff --git a/website/versioned_docs/version-2.0.0-beta.6/_partials/swizzleWarning.mdx b/website/versioned_docs/version-2.0.0-beta.6/_partials/swizzleWarning.mdx new file mode 100644 index 0000000000..e2aec479dd --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/_partials/swizzleWarning.mdx @@ -0,0 +1,5 @@ +:::caution + +We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-beta.6/api/docusaurus.config.js.md new file mode 100644 index 0000000000..c2204357ed --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/docusaurus.config.js.md @@ -0,0 +1,490 @@ +--- +id: docusaurus.config.js +description: API reference for Docusaurus configuration file. +slug: /docusaurus.config.js +--- + +# `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', +}; +``` + +### `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} + +### `favicon` {#favicon} + +- Type: `string | undefined` + +Path to your site favicon + +Example, if your favicon is in `static/img/favicon.ico`: + +```js title="docusaurus.config.js" +module.exports = { + favicon: '/img/favicon.ico', +}; +``` + +### `trailingSlash` {#trailing-slash} + +- Type: `boolean | undefined` + +Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated: + +- `undefined` (default): keeps URLs untouched, and emit `/docs/myDoc/index.html` for `/docs/myDoc.md` +- `true`: add trailing slashes to URLs/links, and emit `/docs/myDoc/index.html` for `/docs/myDoc.md` +- `false`: remove trailing slashes from URLs/links, and emit `/docs/myDoc.html` for `/docs/myDoc.md` + +:::tip + +Each static hosting provider serve static files differently (this behavior may even change over time). + +Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting. + +::: + +### `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 `` 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} + + + +- Type: `any[]` + +```js title="docusaurus.config.js" +module.exports = { + plugins: [], +}; +``` + +### `themes` {#themes} + + + +- Type: `any[]` + +```js title="docusaurus.config.js" +module.exports = { + themes: [], +}; +``` + +### `presets` {#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 ` + <% }); %> + <%~ it.postBodyTags %> + + +}; +``` + +### `stylesheets` {#stylesheets} + +An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `` tags will be inserted in the HTML ``. + +- 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', + }, + ], +}; +``` + +### `titleDelimiter` {#titledelimiter} + +- Type: `string` + +A string that will be used as title delimiter in the generated `` 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. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/overview.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/overview.md new file mode 100644 index 0000000000..e39469a225 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/overview.md @@ -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) diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-client-redirects.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-client-redirects.md new file mode 100644 index 0000000000..722662c903 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-client-redirects.md @@ -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']; + } + }, + }, + ], + ], +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-blog.md new file mode 100644 index 0000000000..889679757b --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-blog.md @@ -0,0 +1,257 @@ +--- +id: plugin-content-blog +title: 'πŸ“¦ plugin-content-blog' +slug: '/api/plugins/@docusaurus/plugin-content-blog' +--- + +Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus. + +## Installation {#installation} + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-blog +``` + +:::tip + +If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'blog'` | Path to the blog content directory on the filesystem, relative to site dir. | +| `editUrl` | <code>string | EditUrlFunction</code> | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | +| `blogTitle` | `string` | `'Blog'` | Blog page title for better SEO. | +| `blogDescription` | `string` | `'Blog'` | Blog page meta description for better SEO. | +| `blogSidebarCount` | <code>number | 'ALL'</code> | `5` | Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable | +| `blogSidebarTitle` | `string` | `'Recent posts'` | Title of the blog sidebar. | +| `routeBasePath` | `string` | `'blog'` | URL route for the blog section of your site. **DO NOT** include a trailing slash. Use `/` to put the blog at root path. | +| `archiveBasePath` | `string` | `'/archive'` | URL route for the archive blog section of your site. It is prepended to the `routeBasePath`. **DO NOT** include a trailing slash. | +| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. | +| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | +| `postsPerPage` | <code>number | 'ALL'</code> | `10` | Number of posts to show per page in the listing page. Use `'ALL'` to display all posts on one listing page. | +| `blogListComponent` | `string` | `'@theme/BlogListPage'` | Root component of the blog listing page. | +| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. | +| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page | +| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. | +| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | +| `truncateMarker` | `string` | `/<!--\s*(truncate)\s*-->/` | Truncate marker, can be a regex or string. | +| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. | +| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file. | +| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. | +| `feedOptions.type` | <code>'rss' | 'atom' | 'all'</code> (or array of multiple options) | **Required** | Type of feed to be generated. | +| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. | +| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. | +| `feedOptions.copyright` | `string` | `undefined` | Copyright message. | +| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. | + +</small> + +```typescript +type EditUrlFunction = (params: { + blogDirPath: string; + blogPath: string; + permalink: string; + locale: string; +}) => string | undefined; +``` + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'blog', + // Simple use-case: string editUrl + // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', + // Advanced use-case: functional editUrl + editUrl: ({locale, blogDirPath, blogPath, permalink}) => { + return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`; + }, + editLocalizedFiles: false, + blogTitle: 'Blog title', + blogDescription: 'Blog', + blogSidebarCount: 5, + blogSidebarTitle: 'All our posts', + routeBasePath: 'blog', + include: ['**/*.{md,mdx}'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + postsPerPage: 10, + blogListComponent: '@theme/BlogListPage', + blogPostComponent: '@theme/BlogPostPage', + blogTagsListComponent: '@theme/BlogTagsListPage', + blogTagsPostsComponent: '@theme/BlogTagsPostsPage', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], + truncateMarker: /<!--\s*(truncate)\s*-->/, + showReadingTime: true, + feedOptions: { + type: '', + title: '', + description: '', + copyright: '', + language: undefined, + }, +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + blog: { + path: 'blog', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-blog', + // highlight-start + { + path: 'blog', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## Markdown Frontmatter {#markdown-frontmatter} + +Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. | +| `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. | +| `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. | +| `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. | +| `author_title` | `string` | `undefined` | ⚠️ Prefer using `authors`. A description of the author. | +| `title` | `string` | Markdown title | The blog post title. | +| `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time. | +| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. | +| `draft` | `boolean` | `false` | 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. | +| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. | +| `keywords` | `string[]` | `undefined` | Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines. | +| `description` | `string` | The first line of Markdown content | 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. | +| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | +| `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. | + +</small> + +```typescript +type Tag = string | {label: string; permalink: string}; + +// An author key references an author from the global plugin authors.yml file +type AuthorKey = string; + +type Author = { + key?: AuthorKey; + name: string; + title?: string; + url?: string; + image_url?: string; +}; + +// The FrontMatter authors field allows various possible shapes +type Authors = AuthorKey | Author | (AuthorKey | Author)[]; +``` + +Example: + +```yml +--- +title: Welcome Docusaurus v2 +authors: + - slorber + - yangshun + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png +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 +--- +A Markdown blog post +``` + +## 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**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) +- **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 +β”œβ”€β”€ authors.yml +β”œβ”€β”€ first-blog-post.md +β”œβ”€β”€ second-blog-post.md +β”‚ +β”‚ # translations for the plugin options that will be rendered +└── options.json +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-docs.md new file mode 100644 index 0000000000..50ccfd5fe5 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-docs.md @@ -0,0 +1,317 @@ +--- +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 use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. | +| `editUrl` | <code>string | EditUrlFunction</code> | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | +| `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. | +| `routeBasePath` | `string` | `'docs'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. Use `/` for shipping docs without base path. | +| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. | +| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | +| `sidebarPath` | <code>false | string</code> | `undefined` (creates autogenerated sidebar) | Path to sidebar configuration. | +| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar#collapsible-categories) | +| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar#expanded-categories-by-default) | +| `sidebarItemsGenerator` | `SidebarGenerator` | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` by real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) | +| `numberPrefixParser` | <code>boolean | PrefixParser</code> | _Omitted_ | Custom parsing logic to extract number prefixes from file names. Use `false` to disable this behavior and leave the docs untouched, and `true` to use the default parser. See also [Using number prefixes](/docs/sidebar#using-number-prefixes) | +| `docLayoutComponent` | `string` | `'@theme/DocPage'` | Root Layout component of each doc page. | +| `docItemComponent` | `string` | `'@theme/DocItem'` | Main doc container, with TOC, pagination, etc. | +| `docTagsListComponent` | `string` | `'@theme/DocTagsListPage'` | Root component of the tags list page | +| `docTagDocListComponent` | `string` | `'@theme/DocTagDocListPage'` | Root component of the "docs containing tag" page. | +| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | +| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. | +| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. | +| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). | +| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory). <br /> Tip: turn it off if the current version is a work-in-progress, not ready to be published. | +| `lastVersion` | `string` | `current` (alias for the first version to appear in `versions.json` and at the "root" (docs have `path=/docs/myDoc`)) | Set the version navigated to in priority on versioned sites and the one displayed by default in docs navbar items. <br /> Note: the path and label of the last version are configurable. <br /> Tip: `lastVersion: 'current'` makes sense in many cases. | +| `versions` | `Versions` | `{}` | Independent customization of each version's properties. | +| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. | + +</small> + +```typescript +type EditUrlFunction = (params: { + version: string; + versionDocsDirPath: string; + docPath: string; + permalink: string; + locale: string; +}) => string | undefined; + +type PrefixParser = ( + filename: string, +) => {filename: string; numberPrefix?: number}; + +type SidebarGenerator = (generatorArgs: { + item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated" + version: {contentPath: string; versionName: string}; // the current version + docs: Array<{ + id: string; + frontMatter: DocFrontMatter & Record<string, unknown>; + source: string; + sourceDirName: string; + sidebarPosition?: number | undefined; + }>; // all the docs of that version (unfiltered) + numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin + defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus +}) => Promise<SidebarItem[]>; + +type Versions = Record< + string, // the version's ID + { + label: string; // the label of the version + path: string; // the route path of the version + banner: 'none' | 'unreleased' | 'unmaintained'; // the banner to show at the top of a doc of that version + badge: boolean; // show a badge with the version name at the top of a doc of that version + className; // add a custom className to the <html> element when browsing docs of that version + } +>; +``` + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'docs', + // Simple use-case: string editUrl + // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', + // Advanced use-case: functional editUrl + editUrl: ({versionDocsDirPath, docPath}) => + `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`, + editLocalizedFiles: false, + editCurrentVersion: false, + routeBasePath: 'docs', + include: ['**/*.md', '**/*.mdx'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + sidebarPath: 'sidebars.js', + sidebarItemsGenerator: async function ({ + defaultSidebarItemsGenerator, + numberPrefixParser, + item, + version, + docs, + }) { + // 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'}, + ], + }, + ]; + }, + 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}; + }, + docLayoutComponent: '@theme/DocPage', + docItemComponent: '@theme/DocItem', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], + showLastUpdateAuthor: false, + showLastUpdateTime: false, + disableVersioning: false, + includeCurrentVersion: true, + lastVersion: undefined, + versions: { + current: { + label: 'Android SDK v2.0.0 (WIP)', + path: 'android-2.0.0', + banner: 'none', + }, + '1.0.0': { + label: 'Android SDK v1.0.0', + path: 'android-1.0.0', + banner: 'unmaintained', + }, + }, + onlyIncludeVersions: ['current', '1.0.0', '2.0.0'], +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + docs: { + path: 'docs', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + // highlight-start + { + path: 'docs', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## Markdown Frontmatter {#markdown-frontmatter} + +Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | file path (including folders, without the extension) | A unique document id. | +| `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. | +| `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. | +| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. | +| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadatas](/docs/sidebar#autogenerated-sidebar-metadatas). | +| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. | +| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. | +| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](/docs/sidebar#using-number-prefixes). | +| `custom_edit_url` | `string` | Computed using the `editUrl` plugin option | The URL for editing this document. | +| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. | +| `description` | `string` | The first line of Markdown content | 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. | +| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | +| `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | +| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. | + +</small> + +```typescript +type Tag = string | {label: string; permalink: string}; +``` + +Example: + +```yml +--- +id: doc-markdown +title: Docs Markdown Features +hide_title: false +hide_table_of_contents: false +sidebar_label: Markdown +sidebar_position: 3 +pagination_label: Markdown features +custom_edit_url: https://github.com/facebook/docusaurus/edit/main/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 +--- +# Markdown Features + +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-sitedir) +- **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 +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-pages.md new file mode 100644 index 0000000000..27e3b0c9b9 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-content-pages.md @@ -0,0 +1,135 @@ +--- +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 use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'src/pages'` | Path to data on filesystem relative to site dir. Components in this directory will be automatically converted to pages. | +| `routeBasePath` | `string` | `'/'` | URL route for the pages section of your site. **DO NOT** include a trailing slash. | +| `include` | `string[]` | `['**/*.{js,jsx,ts,tsx,md,mdx}']` | Matching files will be included and processed. | +| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | +| `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. | +| `remarkPlugins` | `[]` | `any[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `[]` | `any[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | + +</small> + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'src/pages', + routeBasePath: '', + include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + mdxPageComponent: '@theme/MDXPage', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + pages: { + path: 'src/pages', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-pages', + // highlight-start + { + path: 'src/pages', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## 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-sitedir) +- **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 +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-debug.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-debug.md new file mode 100644 index 0000000000..c307099525 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-debug.md @@ -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'], +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-analytics.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-analytics.md new file mode 100644 index 0000000000..738c5f6e34 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-analytics.md @@ -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 **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead. + +## 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? + }, + }, +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-gtag.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-gtag.md new file mode 100644 index 0000000000..53b760c36c --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-google-gtag.md @@ -0,0 +1,41 @@ +--- +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, **in the production build**. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics. + +:::tip + +You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if your gtag is set up correctly! + +::: + +## 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: { + // You can also use your "G-" Measurement ID here. + trackingID: 'UA-141789564-1', + // Optional fields. + anonymizeIP: true, // Should IPs be anonymized? + }, + }, +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-ideal-image.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-ideal-image.md new file mode 100644 index 0000000000..737d4ee417 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-ideal-image.md @@ -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` + +```js {3} +module.exports = { + ... + plugins: ['@docusaurus/plugin-ideal-image'], + ... +} +``` + +## Usage {#usage} + +This plugin supports the PNG 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 | diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-pwa.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-pwa.md new file mode 100644 index 0000000000..7894d3ec2f --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-pwa.md @@ -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> +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-sitemap.md b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-sitemap.md new file mode 100644 index 0000000000..4631b9fc9d --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/plugins/plugin-sitemap.md @@ -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, + }, + ], + ], +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/overview.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/overview.md new file mode 100644 index 0000000000..984918726f --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/overview.md @@ -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) diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-bootstrap.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-bootstrap.md new file mode 100644 index 0000000000..2c2dc05a62 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-bootstrap.md @@ -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. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-classic.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-classic.md new file mode 100644 index 0000000000..3b5a3a764c --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-classic.md @@ -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. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-configuration.md new file mode 100644 index 0000000000..8b099bd1ac --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-configuration.md @@ -0,0 +1,816 @@ +--- +id: theme-configuration +title: 'Theme configuration' +slug: '/api/themes/configuration' +--- + +This configuration applies to all [main themes](./overview.md). + +## Common {#common} + +### Color 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 within the `colorMode` object. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `defaultMode` | <code>'light' | 'dark' </code> | `'light'` | The color mode when user first visits the site. | +| `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. | +| `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. | +| `switchConfig` | _See below_ | _See below_ | Dark/light switch icon options. | +| `switchConfig.darkIcon` | `string` | `'🌜'` | Icon for the switch while in dark mode. | +| `switchConfig.darkIconStyle` | JSX style object (see [documentation](https://reactjs.org/docs/dom-elements.html#style)) | `{}` | CSS to apply to dark icon. | +| `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. | +| `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + colorMode: { + defaultMode: 'light', + disableSwitch: false, + respectPrefersColorScheme: false, + switchConfig: { + darkIcon: 'πŸŒ™', + darkIconStyle: { + marginLeft: '2px', + }, + // Unicode icons such as '\u2600' will work + // Unicode with 5 chars require brackets: '\u{1F602}' + lightIcon: '\u{1F602}', + lightIconStyle: { + marginLeft: '1px', + }, + }, + }, + // highlight-end + }, +}; +``` + +:::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`. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-next-line + image: 'img/docusaurus.png', + }, +}; +``` + +### Metadatas {#metadatas} + +You can configure additional html metadatas (and override existing ones). + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-next-line + 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. All configuration are in the `announcementBar` object. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | `'announcement-bar'` | Any value that will identify this message. | +| `content` | `string` | `''` | The text content of the announcement. HTML will be interpolated. | +| `backgroundColor` | `string` | `'#fff'` | Background color of the entire bar. | +| `textColor` | `string` | `'#000'` | Announcement text color. | +| `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a 'Γ—' button. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + announcementBar: { + id: 'support_us', + content: + 'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>', + backgroundColor: '#fafbfc', + textColor: '#091E42', + isCloseable: false, + }, + // highlight-end + }, +}; +``` + +## Navbar {#navbar} + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `string` | `undefined` | Title for the navbar. | +| `logo` | _See below_ | `undefined` | Customization of the logo object. | +| `items` | `NavbarItem[]` | `[]` | A list of navbar items. See specification below. | +| `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. | +| `style` | <code>'primary' | 'dark' </code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. | + +</small> + +### Navbar logo {#navbar-logo} + +The 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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `alt` | `string` | `undefined` | Alt tag for the logo image. | +| `src` | `string` | **Required** | URL to the logo image. Base URL is appended by default. | +| `srcDark` | `string` | `logo.src` | An alternative image URL to use in dark mode. | +| `href` | `string` | `siteConfig.baseUrl` | Link to navigate to when the logo is clicked. | +| `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + title: 'Site Title', + // highlight-start + logo: { + alt: 'Site Logo', + src: 'img/logo.svg', + srcDark: 'img/logo_dark.svg', + href: 'https://docusaurus.io/', + target: '_self', + }, + // highlight-end + }, + }, +}; +``` + +### Navbar items {#navbar-items} + +You can add items to the navbar via `themeConfig.navbar.items`. + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-start + items: [ + { + type: 'doc', + position: 'left', + docId: 'introduction', + label: 'Docs', + }, + {to: 'blog', label: 'Blog', position: 'left'}, + { + type: 'docsVersionDropdown', + position: 'right', + }, + { + type: 'localeDropdown', + position: 'right', + }, + { + href: 'https://github.com/facebook/docusaurus', + position: 'right', + className: 'header-github-link', + 'aria-label': 'GitHub repository', + }, + ], + // highlight-end + }, + }, +}; +``` + +The items can have different behaviors based on the `type` field. The sections below will introduce you to all the types of navbar items available. + +### Navbar link {#navbar-link} + +By default, Navbar items are regular links (internal or external). + +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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | The name to be shown for this item. | +| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | +| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | +| `prependBaseUrlToHref` | `boolean` | `false` | Prepends the baseUrl to `href` values. | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | +| `activeBasePath` | `string` | `to` / `href` | To apply the active class styling on all routes starting with this path. This usually isn't necessary. | +| `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. | +| `className` | `string` | `''` | Custom CSS class (for styling any item). | + +</small> + +:::note + +In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link. + +::: + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + to: 'docs/introduction', + // Only one of "to" or "href" should be used + // href: 'https://www.facebook.com', + label: 'Introduction', + position: 'left', + activeBaseRegex: 'docs/(next|v8)', + target: '_blank', + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar dropdown {#navbar-dropdown} + +Navbar items of the type `dropdown` has the additional `items` field, an inner array of navbar items. + +Navbar dropdown items only accept the following **"link-like" item types**: + +- [Navbar link](#navbar-link) +- [Navbar doc link](#navbar-doc-link) +- [Navbar docs version](#navbar-docs-version) + +Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a [plain navbar link](#navbar-link). + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | The name to be shown for this item. | +| `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'dropdown', + label: 'Community', + position: 'left', + items: [ + { + label: 'Facebook', + href: 'https://www.facebook.com', + }, + { + type: 'doc', + label: 'Social', + docId: 'social', + }, + // ... more items + ], + }, + // highlight-end + ], + }, + }, +}; +``` + +### 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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `docId` | `string` | **Required** | The ID of the doc that this item links to. | +| `label` | `string` | `docId` | The name to be shown for this item. | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'doc', + position: 'left', + docId: 'introduction', + label: 'Docs', + }, + // 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). + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | +| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. | +| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. | +| `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'docsVersionDropdown', + position: 'left', + dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], + dropdownActiveClassDisabled: true, + }, + // highlight-end + ], + }, + }, +}; +``` + +### 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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | The active/latest version label. | The name to be shown for this item. | +| `to` | `string` | The active/latest version. | The internal link that this item points to. | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'docsVersion', + position: 'left', + to: '/path', + label: 'label', + }, + // 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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | +| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. | +| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'localeDropdown', + position: 'left', + dropdownItemsAfter: [ + { + to: 'https://my-site.com/help-us-translate', + label: 'Help us translate', + }, + ], + }, + // highlight-end + ], + }, + }, +}; +``` + +### 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. + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | <code>'left' | 'right'</code> | `'left'` | The side of the navbar this item should appear on. | + +</small> + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'search', + position: 'right', + }, + // highlight-end + ], + }, + }, +}; +``` + +### 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 title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-next-line + 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 title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-next-line + style: 'primary', + }, + }, +}; +``` + +## CodeBlock {#codeblock} + +Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. All configuration are in the `prism` object. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `theme` | `PrismTheme` | `palenight` | The Prism theme to use for light-theme code blocks. | +| `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. | +| `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. | + +</small> + +### 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). You may also use a different syntax highlighting theme when the site is in dark mode. + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + prism: { + // highlight-start + theme: require('prism-react-renderer/themes/github'), + darkTheme: require('prism-react-renderer/themes/dracula'), + // highlight-end + }, + }, +}; +``` + +:::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. + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + prism: { + // highlight-next-line + 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. + +Accepted fields: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `logo` | `Logo` | `undefined` | Customization of the logo object. See [Navbar logo](#navbar-logo) for details. | +| `copyright` | `string` | `undefined` | The copyright message to be displayed at the bottom. | +| `style` | <code>'dark' | 'light'</code> | `'light'` | The color theme of the footer component. | +| `items` | `FooterItem[]` | `[]` | The link groups to be present. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + 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.`, + }, + // highlight-end + }, +}; +``` + +### Footer Links {#footer-links} + +You can add links to the footer via `themeConfig.footer.links`. + +Accepted fields of each link section: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `string` | `undefined` | Label of the section of these links. | +| `items` | `FooterLink[]` | `[]` | Links in this section. | + +</small> + +Accepted fields of each item in `items`: + +<small> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | Text to be displayed for this link. | +| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | +| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | +| `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. | + +</small> + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + footer: { + // highlight-start + links: [ + { + title: 'Docs', + items: [ + { + label: 'Style Guide', + to: 'docs/', + }, + { + label: 'Second Doc', + to: 'docs/doc2/', + }, + ], + }, + { + title: 'Community', + items: [ + { + label: 'Stack Overflow', + href: 'https://stackoverflow.com/questions/tagged/docusaurus', + }, + { + label: 'Discord', + href: 'https://discordapp.com/invite/docusaurus', + }, + { + label: 'Twitter', + href: 'https://twitter.com/docusaurus', + }, + { + 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> + `, + }, + ], + }, + ], + // highlight-end + }, +}; +``` + +## Hooks {#hooks} + +### `useThemeContext` {#usethemecontext} + +React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use. + +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> + ); +} +``` + +::: + +## 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-sitedir) +- **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 +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-live-codeblock.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-live-codeblock.md new file mode 100644 index 0000000000..568d18d08e --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-live-codeblock.md @@ -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', + }, + }, +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-search-algolia.md b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-search-algolia.md new file mode 100644 index 0000000000..753d8ca66e --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/api/themes/theme-search-algolia.md @@ -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. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-banner.png b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-banner.png new file mode 100644 index 0000000000..ebe95f5ec8 Binary files /dev/null and b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-banner.png differ diff --git a/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-pdf.pdf b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-pdf.pdf new file mode 100644 index 0000000000..188262276a Binary files /dev/null and b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example-pdf.pdf differ diff --git a/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example.xyz b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example.xyz new file mode 100644 index 0000000000..188262276a Binary files /dev/null and b/website/versioned_docs/version-2.0.0-beta.6/assets/docusaurus-asset-example.xyz differ diff --git a/website/versioned_docs/version-2.0.0-beta.6/blog.mdx b/website/versioned_docs/version-2.0.0-beta.6/blog.mdx new file mode 100644 index 0000000000..a028526023 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/blog.mdx @@ -0,0 +1,471 @@ +--- +id: blog +title: Blog +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The blog feature enables you to deploy in no time a full-featured blog. + +:::info + +Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content-blog.md) for an exhaustive list of options. + +::: + +## 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 Markdown file within the blog directory. + +For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`: + +```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md" +--- +title: Welcome Docusaurus v2 +description: This is my first post on Docusaurus 2. +slug: welcome-docusaurus-v2 +authors: + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + - name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +tags: [hello, docusaurus-v2] +image: https://i.imgur.com/mErPwqL.png +hide_table_of_contents: false +--- +Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/). + +<!--truncate--> + +This is my first post on Docusaurus 2. + +A whole bunch of exploration to follow. +``` + +:::note + +Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`. + +This naming convention is optional, and you can provide the date as FrontMatter. + +<details> +<summary>Example supported patterns</summary> + +- `2021-05-28-my-blog-post-title.md` +- `2021-05-28-my-blog-post-title.mdx` +- `2021-05-28-my-blog-post-title/index.md` +- `2021-05-28/my-blog-post-title.md` +- `2021/05/28/my-blog-post-title.md` +- `2021/05-28-my-blog-post-title.md` +- `2021/05/28/my-blog-post-title/index.md` +- ... + +</details> + +::: + +:::tip + +Using a folder can be convenient to co-locate blog post images alongside the Markdown file. + +::: + +The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter). + +## Blog list {#blog-list} + +The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed. + +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. +``` + +By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add meta description to the blog list page for better SEO: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + // highlight-start + blogTitle: 'Docusaurus blog!', + blogDescription: 'A Docusaurus powered blog!', + postsPerPage: 'ALL', + // highlight-end + }, + }, + ], + ], +}; +``` + +## Blog sidebar {#blog-sidebar} + +The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed. + +You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts": + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + // highlight-start + blogSidebarTitle: 'All posts', + blogSidebarCount: 'ALL', + // highlight-end + }, + }, + ], + ], +}; +``` + +## Blog post authors {#blog-post-authors} + +Use the `authors` FrontMatter field to declare blog post authors. + +### Inline authors {#inline-authors} + +Blog post authors can be declared directly inside the FrontMatter: + +````mdx-code-block +<Tabs + defaultValue="single" + values={[ + {label: 'Single author', value: 'single'}, + {label: 'Multiple authors', value: 'multiple'}, + ]} + groupId="author-frontmatter"> + <TabItem value="single"> + +```yml title="my-blog-post.md" +--- +authors: + name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png +--- +``` + + </TabItem> + <TabItem value="multiple"> + +```yml title="my-blog-post.md" +--- +authors: + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + - name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +--- +``` + + </TabItem> +</Tabs> +```` + +:::tip + +This option works best to get started, or for casual, irregular authors. + +::: + +:::info + +Prefer usage of the `authors` FrontMatter, but the legacy `author_*` FrontMatter remains supported: + +<!-- prettier-ignore-start --> +```yml title="my-blog-post.md" +--- +author: Joel Marcey +author_title: Co-creator of Docusaurus 1 +author_url: https://github.com/JoelMarcey +author_image_url: https://github.com/JoelMarcey.png +--- +``` +<!-- prettier-ignore-end --> + +::: + +### Global authors {#global-authors} + +For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post. + +It is possible declare those authors globally in a configuration file: + +```yml title="website/blog/authors.yml" +jmarcey: + name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + +slorber: + name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +``` + +:::tip + +Use the `authorsMapPath` plugin option to configure the path. JSON is also supported. + +::: + +In blog posts FrontMatter, you can reference the authors declared in the global configuration file: + +````mdx-code-block +<Tabs + defaultValue="single" + values={[ + {label: 'Single author', value: 'single'}, + {label: 'Multiple authors', value: 'multiple'}, + ]} + groupId="author-frontmatter"> + <TabItem value="single"> + +```yml title="my-blog-post.md" +--- +authors: jmarcey +--- +``` + + </TabItem> + <TabItem value="multiple"> + +```yml title="my-blog-post.md" +--- +authors: [jmarcey, slorber] +--- +``` + + </TabItem> +</Tabs> +```` + +:::info + +The `authors` system is very flexible and can suit more advanced use-case: + +<details> + <summary>Mix inline authors and global authors</summary> + +You can use global authors most of the time, and still use inline authors: + +<!-- prettier-ignore-start --> +```yml title="my-blog-post.md" +--- +authors: + - jmarcey + - slorber + - name: Inline Author name + title: Inline Author Title + url: https://github.com/inlineAuthor + image_url: https://github.com/inlineAuthor +--- +``` +<!-- prettier-ignore-end --> + +</details> + +<details> + <summary>Local override of global authors</summary> + +You can customize the global author's data on per-blog-post basis: + +<!-- prettier-ignore-start --> +```yml title="my-blog-post.md" +--- +authors: + - key: jmarcey + title: Joel Marcey's new title + - key: slorber + name: SΓ©bastien Lorber's new name +--- +``` +<!-- prettier-ignore-end --> + +</details> + +<details> + <summary>Localize the author's configuration file</summary> + +The configuration file can be localized, just create a localized copy of it at: + +```bash +website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml +``` + +</details> + +::: + +## 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 +type BlogOptions = { + 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 {10} 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! + +::: + +### 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](/tests/blog). diff --git a/website/versioned_docs/version-2.0.0-beta.6/browser-support.md b/website/versioned_docs/version-2.0.0-beta.6/browser-support.md new file mode 100644 index 0000000000..87e9e1f2a2 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/browser-support.md @@ -0,0 +1,77 @@ +--- +id: browser-support +title: Browser support +--- + +Docusaurus allows sites to define the list of supported browsers through a [browserslist configuration](https://github.com/browserslist/browserslist). + +## Purpose {#purpose} + +Websites need to balance between backward compatibility and bundle size. As old browsers do not support modern APIs or syntax, more code is needed to implement the same functionality, penalizing all other users with increased site load time. As a tradeoff, the Docusaurus bundler only supports browser versions defined in the browser list. + +The browser list by default is provided through the `package.json` file as a root `browserslist` field. + +:::caution + +On old browsers, the compiled output will use unsupported (too recent) JS syntax, causing React to fail to initialize and ending up with a static website with only HTML/CSS and no JS. + +::: + +## Default values {#default-values} + +Websites initialized with the default classic template has the following in `package.json`: + +```json {4-11} title="package.json" +{ + "name": "docusaurus", + // ... + "browserslist": { + "production": [">0.5%", "not dead", "not op_mini all"], + "development": [ + "last 1 chrome version", + "last 1 firefox version", + "last 1 safari version" + ] + } + // ... +} +``` + +Explained in natural language, the browsers supported in production are those: + +- With more than 0.5% of market share; _and_ +- Has official support or updates in the past 24 months (the opposite of "dead"); _and_ +- Is not Opera Mini. + +And browsers used in development are: + +- The latest version of Chrome _or_ Firefox _or_ Safari. + +You can "evaluate" any config with the `browserlist` cli to obtain the actual list: + +```bash +npx browserslist --env="production" +``` + +The output are all browsers supported in production. Below is the output in May, 2021: + +```text +and_chr 89 +and_uc 12.12 +chrome 89 +chrome 88 +chrome 87 +edge 89 +edge 88 +firefox 86 +ie 11 +ios_saf 14.0-14.5 +ios_saf 13.4-13.7 +safari 14 +safari 13.1 +samsung 13.0 +``` + +## Read more {#read-more} + +You may wish to visit the [browserslist documentation](https://github.com/browserslist/browserslist/blob/main/README.md) for more specifications, especially the accepted [query values](https://github.com/browserslist/browserslist/blob/main/README.md#queries) and [best practices](https://github.com/browserslist/browserslist/blob/main/README.md#best-practices). diff --git a/website/versioned_docs/version-2.0.0-beta.6/cli.md b/website/versioned_docs/version-2.0.0-beta.6/cli.md new file mode 100644 index 0000000000..026011d03a --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/cli.md @@ -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} + +```mdx-code-block +import SwizzleWarning from "./_partials/swizzleWarning.mdx" + +<SwizzleWarning/> +``` + +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. diff --git a/website/versioned_docs/version-2.0.0-beta.6/configuration.md b/website/versioned_docs/version-2.0.0-beta.6/configuration.md new file mode 100644 index 0000000000..60af67e749 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/configuration.md @@ -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. diff --git a/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx new file mode 100644 index 0000000000..9400cf6a80 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx @@ -0,0 +1,572 @@ +--- +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. + +:::note + +The only responsibility of Docusaurus is to build your site and emit static files in `build`. + +It is now up to you to choose how to host those static files. + +::: + +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), [Surge](https://surge.sh/help/getting-started-with-surge)... + +A Docusaurus site is statically rendered, and it can generally work without JavaScript! + +## Testing your Build Locally {#testing-build-locally} + +It is important to test your build locally before deploying to production. + +Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that: + +```bash npm2yarn +npm run serve +``` + +## Trailing slash configuration {#trailing-slashes} + +Docusaurus has a [`trailingSlash` config](./api/docusaurus.config.js.md#trailing-slash), to allow customizing URLs/links and emitted filename patterns. + +The default value generally works fine. + +Unfortunately, each static hosting provider has a **different behavior**, and deploying the exact same site to various hosts can lead to distinct results. + +Depending on your host, it can be useful to change this config. + +:::tip + +Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to understand better the behavior of your host and configure `trailingSlash` appropriately. + +::: + +## Self-Hosting {#self-hosting} + +Docusaurus can be self-hosted using [`docusaurus serve`](cli.md#docusaurus-serve-sitedir). Change port using `--port` and `--host` to change host. + +```bash npm2yarn +npm run serve -- --build --port 80 --host 0.0.0.0 +``` + +:::warning + +It is not the best option, compared to a static hosting provider / CDN. + +::: + +## 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. + +When using a custom domain, you should be able to move back from `baseUrl: '/projectName/'` to `baseUrl: '/'` + +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. + +::: + +:::caution + +GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommended to set a `trailingSlash` config (`true` or `false`, not `undefined`). + +::: + +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', + trailingSlash: false, + // ... +}; +``` + +:::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 GitHub Pages Organization repos (`config.projectName` ending in `github.io`), this env variable is required. | +| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `main`, 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 your [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`. + +:::warning + +Please make sure that you replace `actions@github.com` with your GitHub email and `gh-actions` with your name. + +::: + +```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: + - '12.13.0' +branches: + only: + - main +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 `main`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. + +### Triggering deployment with Buddy {#triggering-deployment-with-buddy} + +[Buddy](https://buddy.works/) is an easy-to-use CI/CD tool that allows you to automate the deployment of your portal to different environments, including GitHub Pages. + +Follow these steps to create a pipeline that automatically deploys a new version of your website whenever you push changes to the selected branch of your project: + +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. Sign in to your Buddy account and create a new project. +1. Choose GitHub as your git hosting provider and select the repository with the code of your website. +1. Using the left navigation panel, switch to the `Pipelines` view. +1. Create a new pipeline. Define its name, set the trigger mode to `On push`, and select the branch that triggers the pipeline execution. +1. Add a `Node.js` action. +1. Add these command in the action's terminal: + ```bash + GIT_USER=<GH_PERSONAL_ACCESS_TOKEN> + git config --global user.email "<YOUR_GH_EMAIL>" + git config --global user.name "<YOUR_GH_USERNAME>" + yarn deploy + ``` + +After creating this simple pipeline, each new commit pushed to the branch you selected deploys your website to GitHub Pages using `yarn deploy`. Read [this guide](https://buddy.works/guides/react-docusaurus) to learn more about setting up a CI/CD pipeline for Docusaurus. + +### 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: + - main + +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 main + 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 `main`. + +:::warning + +By default, Netlify adds trailing slashes to Docusaurus URLs. + +It is recommended to disable the Netlify setting `Post Processing > Asset Optimization > Pretty Urls` to prevent lowercased URLs, unnecessary redirects and 404 errors. + +**Be very careful**: the `Disable asset optimization` global checkbox is broken and does not really disable the `Pretty URLs` setting in practice. Please make sure to **uncheck it independently**. + +If you want to keep the `Pretty Urls` Netlify setting on, adjust the `trailingSlash` Docusaurus config appropriately. + +Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) for more information. + +::: + +## 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://www.qovery.com) is a fully-managed cloud platform that runs on your AWS, Digital Ocean and Scaleway 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 project** and give a name to your project. +- Click on **Next**. + +3. Create a new environment + +- Click on **Create environment** and give a name (e.g. staging, production). + +4. Add an application + +- Click on **Create an application**, give a name and select your GitHub or GitLab repository where your Docusaurus app is located. +- Define the main branch name and the root application path. +- Click on **Create**. + +After the application is created: + +- Navigate to your application **Settings** +- Select **Port** +- Add port used by your Docusaurus application + +5. Deploy All you have to do now is to navigate to your application and click on **Deploy** + +![Deploy the app](https://hub.qovery.com/img/heroku/heroku-1.png) + +That's it. Watch the status and wait till the app is deployed. + +To open the application in your browser, click on **Action** and **Open** in your application overview + +## 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. diff --git a/website/versioned_docs/version-2.0.0-beta.6/docusaurus-core.md b/website/versioned_docs/version-2.0.0-beta.6/docusaurus-core.md new file mode 100644 index 0000000000..d144820e93 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/docusaurus-core.md @@ -0,0 +1,627 @@ +--- +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 + + +); +``` + +Nested or latter components will override duplicate usages: + +```jsx {2,5,8,11} + + + My Title + + + + + Nested Title + + + + +``` + +Outputs: + +```html + + Nested Title + + +``` + +### `` {#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 `` 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 `` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `` component. + +External links also work, and automatically have these props: `target="_blank" rel="noopener noreferrer"`. + +```jsx {2,7} +import React from 'react'; +import Link from '@docusaurus/Link'; + +const Page = () => ( +
+

+ Check out my blog! +

+

+ Follow me on Twitter! +

+
+); +``` + +#### `to`: string {#to-string} + +The target location to navigate to. Example: `/docs/introduction`. + +```jsx + +``` + +### `` {#redirect} + +Rendering a `` 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 ; +}; +``` + +:::note + +`@docusaurus/router` implements [React Router](https://reacttraining.com/react-router/web/guides/quick-start) and supports its features. + +::: + +### `` {#browseronly} + +The `` component permits to render React components only in the browser, after the React app has hydrated. + +:::tip + +Use it for integrating with code that can't run in Node.js, because `window` or `document` objects are being accessed. + +::: + +#### Props {#browseronly-props} + +- `children`: render function prop returning browser-only JSX. Will not be executed in Node.js +- `fallback` (optional): JSX to render on the server (Node.js) and until React hydration completes. + +#### Example with code {#browseronly-example-code} + +```jsx +// highlight-start +import BrowserOnly from '@docusaurus/BrowserOnly'; +// highlight-end + +const MyComponent = () => { + return ( + // highlight-start + + {() => { + page url = {window.location.href}; + }} + + // highlight-end + ); +}; +``` + +#### Example with a library {#browseronly-example-library} + +```jsx +// highlight-start +import BrowserOnly from '@docusaurus/BrowserOnly'; +// highlight-end + +const MyComponent = (props) => { + return ( + // highlight-start + Loading...}> + {() => { + const LibComponent = require('some-lib').LibComponent; + return ; + }} + + // highlight-end + ); +}; +``` + +### `` {#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 {#interpolate-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 + + website + + ), + }}> + {'Hello, {firstName}! How are you? Take a look at my {website}'} + + // highlight-end + ); +} +``` + +### `` {#translate} + +When [localizing your site](./i18n/i18n-introduction.md), the `` component will allow providing **translation support to React components**, such as your homepage. The `` component supports [interpolation](#interpolate). + +The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/`. + +:::note + +The `` 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 {#translate-props} + +- `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 ( + +

+ {/* highlight-start */} + + Welcome to my website + + {/* highlight-end */} +

+
+ {/* highlight-start */} + + {'Welcome, {firstName}! How are you?'} + + {/* highlight-end */} +
+ + ); +} +``` + +## 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; +} + +interface I18nLocaleConfig { + label: string; + direction: string; +} + +interface I18n { + defaultLocale: string; + locales: [string, ...string[]]; + currentLocale: string; + localeConfigs: Record; +} + +interface DocusaurusContext { + siteConfig: DocusaurusConfig; + siteMetadata: DocusaurusSiteMetadata; + globalData: Record; + i18n: I18n; + codeTranslations: Record; +} +``` + +Usage example: + +```jsx {5,8-10} +import React from 'react'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +const MyComponent = () => { + const {siteConfig, siteMetadata} = useDocusaurusContext(); + return ( +
+

{siteConfig.title}

+
{siteMetadata.siteVersion}
+
{siteMetadata.docusaurusVersion}
+
+ ); +}; +``` + +### `useIsBrowser` {#useIsBrowser} + +Returns `true` when the React app has successfully hydrated in the browser. + +:::caution + +Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic. + +The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). + +Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). + +::: + +Usage example: + +```jsx +import React from 'react'; +import useIsBrowser from '@docusaurus/useIsBrowser'; + +const MyComponent = () => { + // highlight-start + const isBrowser = useIsBrowser(); + // highlight-end + return
{isBrowser ? 'Client' : 'Server'}
; +}; +``` + +### `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` 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 ; +}; +``` + +:::tip + +In most cases, you don't need `useBaseUrl`. + +Prefer a `require()` call for [assets](./guides/markdown-features/markdown-features-assets.mdx): + +```jsx + +``` + +::: + +### `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
{/* ... */}
; +}; +``` + +### `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
{myPluginData.someAttribute}
; +}; +``` + +:::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
{myPluginData.someAttribute}
; +}; +``` + +### `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
{myPluginData.someAttribute}
; +}; +``` + +## Functions {#functions} + +### `interpolate` {#interpolate-1} + +The imperative counterpart of the [``](#interpolate) component. + +#### Signature {#signature} + +```ts +// Simple string interpolation +function interpolate(text: string, values: Record): string; + +// JSX interpolation +function interpolate( + text: string, + values: Record, +): 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) 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; +``` + +#### 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 ( + + + + ); +} +``` + +## Modules {#modules} + +### `ExecutionEnvironment` {#executionenvironment} + +A module which exposes a few boolean variables to check the current rendering environment. + +:::caution + +For React rendering logic, use [`useIsBrowser()`](#useIsBrowser) or [``](#browseronly) instead. + +::: + +Example: + +```jsx +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; + +if (ExecutionEnvironment.canUseDOM) { + require('lib-that-only-works-client-side'); +} +``` + +| Field | Description | +| --- | --- | +| `ExecutionEnvironment.canUseDOM` | `true` if on client/browser, `false` on Node.js/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` | diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/creating-pages.md b/website/versioned_docs/version-2.0.0-beta.6/guides/creating-pages.md new file mode 100644 index 0000000000..c622ae5fcd --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/creating-pages.md @@ -0,0 +1,137 @@ +--- +id: creating-pages +title: Creating Pages +slug: /creating-pages +sidebar_label: 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) do. + +::: + +:::info + +Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.md) for an exhaustive list of options. + +::: + +## 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 ( + +
+

+ Edit pages/hello.js and save to reload. +

+
+ + ); +} + +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` β†’ `` +- `/src/pages/foo.js` β†’ `/foo` +- `/src/pages/foo/test.js` β†’ `/foo/test` +- `/src/pages/foo/index.js` β†’ `/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. diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-create-doc.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-create-doc.mdx new file mode 100644 index 0000000000..ab4d584d15 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-create-doc.mdx @@ -0,0 +1,101 @@ +--- +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: + +```mdx-code-block +import BrowserWindow from '@site/src/components/BrowserWindow'; + + + +

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

+ +With {#custom-id} syntax you can set your own header id. + + +``` + +## Doc tags {#doc-tags} + +Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels: + + +```yml "your-doc-page.md" +--- +id: doc-with-tags +title: A doc with tags +tags: + - Demo + - Getting started +--- +``` + diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-introduction.md new file mode 100644 index 0000000000..0612e7b089 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-introduction.md @@ -0,0 +1,86 @@ +--- +id: introduction +title: Docs Introduction +sidebar_label: Introduction +slug: /docs-introduction +--- + +The docs feature provides users with a way to organize Markdown files in a hierarchical format. + +:::info + +Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options. + +::: + +## Document ID {#document-id} + +Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. + +For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. + +```bash +website # Root directory of your site +└── docs +Β Β  β”œβ”€β”€ greeting.md + └── guide + └── hello.md +``` + +However, the **last part** of the `id` can be defined by 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 info](#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.mdx#blog-only-mode). + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-markdown-features.mdx new file mode 100644 index 0000000000..eb5b7732a0 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-markdown-features.mdx @@ -0,0 +1,39 @@ +--- +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 relative path of the document you want to link to. + +Docusaurus will convert the file path to be the final document url path (and remove the `.md` extension). + +For example, if you are in `folder/doc1.md` and you want to reference `folder/doc2.md`, `folder/subfolder/doc3.md` and `otherFolder/doc4.md`: + +```md +I am referencing a [document](doc2.md). + +Reference to another [document in a subfolder](subfolder/doc3.md). + +[Relative document](../otherFolder/doc4.md) referencing works as well. +``` + +:::tip + +It is better to use relative file paths links instead of relative links: + +- links will keep working on the GitHub interface +- you can customize the document slugs without having to update all the links +- a versioned doc will link to another doc of the exact same version +- relative links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash) + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-multi-instance.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-multi-instance.mdx new file mode 100644 index 0000000000..5962be207f --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/docs-multi-instance.mdx @@ -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/_versions.json` +- `website/_versioned_docs` +- `website/_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 + }, + ], + }, + }, +}; +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/sidebar.md b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/sidebar.md new file mode 100644 index 0000000000..47aecb43f2 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/sidebar.md @@ -0,0 +1,695 @@ +--- +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-next-line + sidebarPath: require.resolve('./sidebars.js'), + }, + }, + ], + ], +}; +``` + +## 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/) + }, + ], +}; +``` + +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: + collapsible: boolean; // Set the category to be collapsible + collapsed: boolean; // Set the category to be initially collapsed or open by default +}; +``` + +Example: + +```js title="sidebars.js" +module.exports = { + docs: [ + { + type: 'category', + label: 'Guides', + collapsible: true, + 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} + +We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`. + +```js title="sidebars.js" +module.exports = { + docs: [ + { + type: 'category', + label: 'Guides', + items: [ + 'creating-pages', + { + type: 'category', + // highlight-next-line + collapsible: false, + label: 'Docs', + items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], + }, + ], + }, + ], +}; +``` + +To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-docs` to `false`: + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-next-line + sidebarCollapsible: false, + }, + }, + ], + ], +}; +``` + +:::note + +The option in `sidebars.js` takes precedence over plugin configuration, so it is possible to make certain categories collapsible when `sidebarCollapsible` is set to `false` globally. + +::: + +#### Expanded categories by default {#expanded-categories-by-default} + +Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`: + +```js title="sidebars.js" +module.exports = { + docs: { + Guides: [ + 'creating-pages', + { + type: 'category', + label: 'Docs', + // highlight-next-line + collapsed: false, + items: ['markdown-features', 'sidebar', 'versioning'], + }, + ], + }, +}; +``` + +Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration. + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-next-line + sidebarCollapsed: false, + }, + }, + ], + ], +}; +``` + +:::caution + +When a category has `collapsed: true` but `collapsible: false` (either through `sidebars.js` or through plugin configuration), the latter takes precedence and the category is still rendered as expanded. + +::: + +### 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: + +```md title="docs/tutorials/tutorial-easy.md" {1-4} +--- +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 +collapsible: true # make the category collapsible +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-start + 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'; + + + {require('!!raw-loader!@site/sidebars.js') + .default + .split('\n') + // remove comments + .map((line) => !['#','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line) + .filter(Boolean) + .join('\n')} + +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/docs/versioning.md b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/versioning.md new file mode 100644 index 0000000000..e62511dbbb --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/docs/versioning.md @@ -0,0 +1,216 @@ +--- +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 the current docs version +β”œβ”€β”€ docs # docs directory for the current docs 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` | current | /docs/next/hello | + +:::tip + +The files in the `docs` directory belong to the `current` docs version. + +By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle. + +::: + +### Tagging a new version {#tagging-a-new-version} + +1. First, make sure the current docs version (the `docs` directory) is ready to be frozen. +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-/` folder. +- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/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. + +**Current version docs** + +```shell +# The new file. +docs/new.md + +# Edit the corresponding sidebar file. +sidebar.js +``` + +**Older version 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) +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/_markdown-partial-example.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/_markdown-partial-example.mdx new file mode 100644 index 0000000000..5eb3f3bf11 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/_markdown-partial-example.mdx @@ -0,0 +1,3 @@ +Hello {props.name} + +This is text some content from `_markdown-partial-example.md`. diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-admonitions.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-admonitions.mdx new file mode 100644 index 0000000000..ccd7ae68ff --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-admonitions.mdx @@ -0,0 +1,135 @@ +--- +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 + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::tip + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::info + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::caution + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::danger + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + +:::note + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::tip + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::info + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::caution + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::danger + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +## Specifying title {#specifying-title} + +You may also specify an optional title + + :::note Your Title + + Some **content** with _markdown_ `syntax`. + + ::: + +:::note Your Title + +Some **content** with _markdown_ `syntax`. + +::: + +## Admonitions with MDX + +You can use MDX inside admonitions too! + +```mdx +import Tabs from '@theme/Tabs'; + +import TabItem from '@theme/TabItem'; + +:::tip Use tabs in admonitions + + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 + + +::: +``` + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +:::tip Use tabs in admonitions + +```mdx-code-block + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 + +``` + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-assets.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-assets.mdx new file mode 100644 index 0000000000..8e0fa107f2 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-assets.mdx @@ -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 display images in three different ways: Markdown syntax, JSX require or ES imports syntax. + +Display images using simple Markdown syntax: + +```mdx +![Example banner](./assets/docusaurus-asset-example-banner.png) +``` + +Display images using inline CommonJS `require` in JSX image tag: + +```mdx +Example banner +``` + +Display images using ES `import` syntax and JSX image tag: + +```mdx +import myImageUrl from './assets/docusaurus-asset-example-banner.png'; + +Example banner +``` + +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](../../api/plugins/plugin-ideal-image.md), 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 + + + Download this PDF + + +or + +[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf) +``` + + + Download this PDF + + +[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'; + +; +``` + +import DocusaurusSvg from '@site/static/img/docusaurus.svg'; + + + +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'; + +; +``` + +```css +html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] { + fill: greenyellow; +} + +html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] { + fill: seagreen; +} +``` + + + +## 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'; + +; +``` + +```mdx-code-block +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + + +``` diff --git a/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-code-blocks.mdx b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-code-blocks.mdx new file mode 100644 index 0000000000..7fedb93fec --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.6/guides/markdown-features/markdown-features-code-blocks.mdx @@ -0,0 +1,460 @@ +--- +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

Hello, {props.name}

; + } + ``` + +```jsx title="/src/components/HelloCodeTitle.js" +function HelloCodeTitle(props) { + return

Hello, {props.name}

; +} +``` + +## 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.'); + ``` + + + +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.'); +``` + +### Theming {#theming} + +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'), + }, + }, +}; +``` + +### Supported Languages {#supported-languages} + +By default, Docusaurus comes with a subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js). + +:::caution + +Some popular languages like Java, C#, or PHP are not enabled by default. + +::: + +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'], + }, + // ... + }, +}; +``` + +After adding `additionalLanguages`, restart Docusaurus. + +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 { + /* Color which works with dark mode syntax highlighting theme */ + background-color: rgb(100, 100, 100); +} +``` + +### Multiple line highlighting {#multiple-line-highlighting} + +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
Bar
; + } + + return
Foo
; + } + + export default MyComponent; + ``` + +```jsx {1,4-6,11} +import React from 'react'; + +function MyComponent(props) { + if (props.isBar) { + return
Bar
; + } + + return
Foo
; +} + +export default MyComponent; +``` + +### Highlighting with comments {#highlighting-with-comments} + +You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. + + ```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 ( +
+

It is {date.toLocaleTimeString()}.

+
+ ); + } + ``` + +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 ( +
+

It is {date.toLocaleTimeString()}.

+
+ ); +} +``` + +### 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) => ( +