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

chore: prepare v2.0.0-beta.16 release (#6760)

Browse source
This commit is contained in:
Sébastien Lorber 2022-02-25 16:00:11 +01:00 • committed by GitHub
parent 17b8eded79
commit 124511f445
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
142 changed files with 6743 additions and 4173 deletions
Download patch file Download diff file Expand all files Collapse all files

253
CHANGELOG.md
View file

@ -1,5 +1,258 @@
# Docusaurus 2 Changelog
## 2.0.0-beta.16 (2022-02-25)
#### :rocket: New Feature
- `docusaurus-logger`, `docusaurus-module-type-aliases`, `docusaurus-plugin-debug`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus`
- [#6243](https://github.com/facebook/docusaurus/pull/6243) feat(core): brand new swizzle CLI experience ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`
- [#6750](https://github.com/facebook/docusaurus/pull/6750) feat(create): new --package-manager option; interactive package manager selection ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6610](https://github.com/facebook/docusaurus/pull/6610) feat(create): allow specifying a git clone strategy ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`, `docusaurus-theme-common`
- [#6723](https://github.com/facebook/docusaurus/pull/6723) feat: sync color mode between browser tabs ([@lex111](https://github.com/lex111))
- `docusaurus-theme-search-algolia`
- [#6692](https://github.com/facebook/docusaurus/pull/6692) feat(search-algolia): allow disabling search page and configuring path ([@lex111](https://github.com/lex111))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`
- [#6517](https://github.com/facebook/docusaurus/pull/6517) feat(docs,theme-classic): docs breadcrumbs ([@jodyheavener](https://github.com/jodyheavener))
- [#6519](https://github.com/facebook/docusaurus/pull/6519) feat(content-docs): sidebar item type "html" for rendering pure markup ([@jodyheavener](https://github.com/jodyheavener))
- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-utils`
- [#6593](https://github.com/facebook/docusaurus/pull/6593) feat(content-blog): infer blog post date from git history ([@felipecrs](https://github.com/felipecrs))
- `docusaurus-plugin-content-docs`
- [#6619](https://github.com/facebook/docusaurus/pull/6619) feat(content-docs): add custom props front matter ([@TheCatLady](https://github.com/TheCatLady))
- [#6452](https://github.com/facebook/docusaurus/pull/6452) feat(content-docs): allow explicitly disabling index page for generated category ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`
- [#6603](https://github.com/facebook/docusaurus/pull/6603) feat(content-blog): allow customizing blog archive component through option ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
- [#6221](https://github.com/facebook/docusaurus/pull/6221) feat(content-blog): Allow pagination for BlogTagsPostsPage ([@redhoyasa](https://github.com/redhoyasa))
#### :boom: Breaking Change
- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`, `stylelint-copyright`
- [#6752](https://github.com/facebook/docusaurus/pull/6752) chore: upgrade docsearch-react to v3 stable, bump dependencies ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-types`
- [#6729](https://github.com/facebook/docusaurus/pull/6729) refactor: make MDX export a flat TOC list instead of tree ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-types`, `docusaurus-utils-validation`, `docusaurus`
- [#6740](https://github.com/facebook/docusaurus/pull/6740) refactor: remove deprecated Webpack utils & validation escape hatch ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`
- [#6707](https://github.com/facebook/docusaurus/pull/6707) refactor(theme-classic): bias again search metadata toward Algolia DocSearch ([@slorber](https://github.com/slorber))
- `docusaurus-module-type-aliases`, `docusaurus-theme-common`, `docusaurus`
- [#6651](https://github.com/facebook/docusaurus/pull/6651) refactor: reduce exported members of docusaurus router ([@Josh-Cena](https://github.com/Josh-Cena))
#### :bug: Bug Fix
- `docusaurus-theme-common`
- [#6758](https://github.com/facebook/docusaurus/pull/6758) fix(theme-common): isSamePath should be case-insensitive ([@slorber](https://github.com/slorber))
- [#6748](https://github.com/facebook/docusaurus/pull/6748) fix(theme-classic): temporarily disable toc heading autoscrolling ([@slorber](https://github.com/slorber))
- [#6696](https://github.com/facebook/docusaurus/pull/6696) fix(theme-common): do not run useLocationChange when hot reloading ([@lex111](https://github.com/lex111))
- [#6490](https://github.com/facebook/docusaurus/pull/6490) fix(theme-classic): do not switch color modes when printing ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus-theme-common`
- [#6749](https://github.com/facebook/docusaurus/pull/6749) fix(theme-classic): fix breadcrumb home link bug with new useHomePageRoute() hook ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-content-docs`
- [#6720](https://github.com/facebook/docusaurus/pull/6720) fix(content-docs): create assets for frontmatter images ([@lebalz](https://github.com/lebalz))
- [#6592](https://github.com/facebook/docusaurus/pull/6592) fix(content-docs): read last update from inner git repositories ([@felipecrs](https://github.com/felipecrs))
- [#6477](https://github.com/facebook/docusaurus/pull/6477) fix(content-docs): export versioning utils ([@milesj](https://github.com/milesj))
- `docusaurus-mdx-loader`
- [#6712](https://github.com/facebook/docusaurus/pull/6712) fix(mdx-loader): make headings containing links properly formatted in ToC ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus`
- [#6701](https://github.com/facebook/docusaurus/pull/6701) fix(cli): disable directory listing in serve ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6607](https://github.com/facebook/docusaurus/pull/6607) fix(cli): log error itself on unhandled rejection ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6500](https://github.com/facebook/docusaurus/pull/6500) fix(cli): allow passing a list of file names to write-heading-ids ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6496](https://github.com/facebook/docusaurus/pull/6496) fix(core): configValidation should allow inline theme functions ([@slorber](https://github.com/slorber))
- `docusaurus-theme-classic`
- [#6652](https://github.com/facebook/docusaurus/pull/6652) fix(theme-classic): minor BTT button fixes ([@lex111](https://github.com/lex111))
- [#6612](https://github.com/facebook/docusaurus/pull/6612) fix(theme-classic): make Prism additional languages properly server-side rendered ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6599](https://github.com/facebook/docusaurus/pull/6599) fix(theme-classic): add docSidebar as allowed item in dropdown ([@homotechsual](https://github.com/homotechsual))
- [#6531](https://github.com/facebook/docusaurus/pull/6531) fix(theme-classic): highlight active collapsible doc category properly ([@lex111](https://github.com/lex111))
- [#6515](https://github.com/facebook/docusaurus/pull/6515) fix(theme-classic): add key prop for SimpleLinks map ([@kgajera](https://github.com/kgajera))
- [#6508](https://github.com/facebook/docusaurus/pull/6508) fix(theme-classic): apply width/height for footer logos without href ([@kgajera](https://github.com/kgajera))
- `docusaurus-utils`
- [#6617](https://github.com/facebook/docusaurus/pull/6617) fix(utils): convert Markdown links in reference-style links with multiple spaces ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6489](https://github.com/facebook/docusaurus/pull/6489) fix(utils): do not resolve Markdown paths with @site prefix ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6478](https://github.com/facebook/docusaurus/pull/6478) fix(utils): Markdown linkification match local paths beginning with http ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
- [#6495](https://github.com/facebook/docusaurus/pull/6495) fix(content-docs): render category with no subitems as a normal link ([@Josh-Cena](https://github.com/Josh-Cena))
#### :nail_care: Polish
- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils`, `docusaurus`, `lqip-loader`
- [#6755](https://github.com/facebook/docusaurus/pull/6755) refactor: unify error handling behavior ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`
- [#6679](https://github.com/facebook/docusaurus/pull/6679) feat(create): better detection of package manager preference ([@lex111](https://github.com/lex111))
- [#6481](https://github.com/facebook/docusaurus/pull/6481) refactor(init): promote good practices; use site alias ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-docs`
- [#6745](https://github.com/facebook/docusaurus/pull/6745) fix(content-docs): improve sidebar shorthand normalization error message ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6602](https://github.com/facebook/docusaurus/pull/6602) feat(content-docs): allow omitting enclosing array consistently for category shorthand ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6596](https://github.com/facebook/docusaurus/pull/6596) refactor(content-docs): clean up sidebars logic; validate generator returns ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6586](https://github.com/facebook/docusaurus/pull/6586) refactor(content-docs): read category metadata files before autogenerating ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus`
- [#6730](https://github.com/facebook/docusaurus/pull/6730) refactor: declare all props as interfaces ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-translations`
- [#6711](https://github.com/facebook/docusaurus/pull/6711) chore(theme-translations): complete Korean translations ([@revi](https://github.com/revi))
- [#6686](https://github.com/facebook/docusaurus/pull/6686) fix(theme-translations): improve Korean translations ([@winterlood](https://github.com/winterlood))
- [#6635](https://github.com/facebook/docusaurus/pull/6635) refactor(theme-translation): improve Traditional Chinese translation quality ([@toto6038](https://github.com/toto6038))
- `docusaurus-theme-classic`, `docusaurus-theme-translations`
- [#6674](https://github.com/facebook/docusaurus/pull/6674) fix(theme-classic): improve aria label of color mode toggle ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-theme-classic`
- [#6668](https://github.com/facebook/docusaurus/pull/6668) refactor: recommend using data-theme without html element selector ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`
- [#6622](https://github.com/facebook/docusaurus/pull/6622) refactor(theme-classic): clean up CSS of doc sidebar item ([@lex111](https://github.com/lex111))
- `docusaurus`
- [#6644](https://github.com/facebook/docusaurus/pull/6644) fix(core): forward ref to Link's anchor element ([@koistya](https://github.com/koistya))
- [#6646](https://github.com/facebook/docusaurus/pull/6646) fix(cli): make docusaurus clear also remove .yarn/.cache folder ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6306](https://github.com/facebook/docusaurus/pull/6306) feat(core): use react-helmet-async ([@seyoon20087](https://github.com/seyoon20087))
- `docusaurus-utils-validation`
- [#6656](https://github.com/facebook/docusaurus/pull/6656) feat: allow numbers in plugin ID ([@cdemonchy-pro](https://github.com/cdemonchy-pro))
- `docusaurus-mdx-loader`, `docusaurus-utils`, `lqip-loader`
- [#6650](https://github.com/facebook/docusaurus/pull/6650) refactor(utils): replace hash with contenthash for file loader ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`
- [#6615](https://github.com/facebook/docusaurus/pull/6615) fix: remove more peer dependency warnings ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`
- [#6598](https://github.com/facebook/docusaurus/pull/6598) feat: make Markdown images lazy loaded ([@johnnyreilly](https://github.com/johnnyreilly))
- `docusaurus-theme-classic`, `docusaurus-theme-common`
- [#6505](https://github.com/facebook/docusaurus/pull/6505) fix(theme-classic): make focused link outlined with JS disabled ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
- [#6507](https://github.com/facebook/docusaurus/pull/6507) refactor: improve internal typing ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`
- [#6498](https://github.com/facebook/docusaurus/pull/6498) fix: updating peerDependency fields for yarn berry ([@vidarc](https://github.com/vidarc))
- `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`
- [#6482](https://github.com/facebook/docusaurus/pull/6482) feat: mark some text labels as translatable ([@Josh-Cena](https://github.com/Josh-Cena))
#### :memo: Documentation
- Other
- [#6727](https://github.com/facebook/docusaurus/pull/6727) docs: add Blog Matheus Brunelli site to showcase ([@mrbrunelli](https://github.com/mrbrunelli))
- [#6721](https://github.com/facebook/docusaurus/pull/6721) docs: add Butterfly Documentation to showcase ([@CodeDoctorDE](https://github.com/CodeDoctorDE))
- [#6710](https://github.com/facebook/docusaurus/pull/6710) docs(website): Add techharvesting to showcase ([@NaseelNiyas](https://github.com/NaseelNiyas))
- [#6708](https://github.com/facebook/docusaurus/pull/6708) docs: add doc for generated-index keyword/image metadata ([@slorber](https://github.com/slorber))
- [#6709](https://github.com/facebook/docusaurus/pull/6709) docs(website): fix video responsiveness ([@lex111](https://github.com/lex111))
- [#6687](https://github.com/facebook/docusaurus/pull/6687) docs: add deep dive video for Docusaurus ([@dmitryvinn](https://github.com/dmitryvinn))
- [#6704](https://github.com/facebook/docusaurus/pull/6704) docs(website): search doc typo searchParameters ([@slorber](https://github.com/slorber))
- [#6682](https://github.com/facebook/docusaurus/pull/6682) docs: add redux-cool site to showcase ([@Ruben-Arushanyan](https://github.com/Ruben-Arushanyan))
- [#6677](https://github.com/facebook/docusaurus/pull/6677) docs: add Rivalis to showcase ([@kalevski](https://github.com/kalevski))
- [#6676](https://github.com/facebook/docusaurus/pull/6676) docs: add SmartCookieWeb site to showcase ([@CookieJarApps](https://github.com/CookieJarApps))
- [#6675](https://github.com/facebook/docusaurus/pull/6675) docs: mention that all official themes are TypeScript-covered ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6673](https://github.com/facebook/docusaurus/pull/6673) docs: mention about blog date in front matter ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6672](https://github.com/facebook/docusaurus/pull/6672) refactor(website): extract homepage data from UI; feature text updates ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6670](https://github.com/facebook/docusaurus/pull/6670) docs: add CyberDrain Improved Partner Portal (CIPP) to showcase ([@homotechsual](https://github.com/homotechsual))
- [#6667](https://github.com/facebook/docusaurus/pull/6667) fix(website): make YT iframe responsive ([@lex111](https://github.com/lex111))
- [#6659](https://github.com/facebook/docusaurus/pull/6659) docs: add eli5 video to home page ([@dmitryvinn-fb](https://github.com/dmitryvinn-fb))
- [#6633](https://github.com/facebook/docusaurus/pull/6633) docs: improve wording of using Markdown file paths ([@BigDataWriter](https://github.com/BigDataWriter))
- [#6624](https://github.com/facebook/docusaurus/pull/6624) docs: add Resoto & Some Engineering Inc. to showcase ([@TheCatLady](https://github.com/TheCatLady))
- [#6611](https://github.com/facebook/docusaurus/pull/6611) docs: fix bad anchor link syntax ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6591](https://github.com/facebook/docusaurus/pull/6591) docs: improve Github Actions example jobs ([@ebarojas](https://github.com/ebarojas))
- [#6426](https://github.com/facebook/docusaurus/pull/6426) feat(website): add Tweets section ([@yangshun](https://github.com/yangshun))
- [#6532](https://github.com/facebook/docusaurus/pull/6532) docs: add SAP Cloud SDK to showcase ([@artemkovalyov](https://github.com/artemkovalyov))
- [#6513](https://github.com/facebook/docusaurus/pull/6513) docs: clean up CONTRIBUTING ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6501](https://github.com/facebook/docusaurus/pull/6501) docs: add Cloudflare pages deployment guide ([@apidev234](https://github.com/apidev234))
- [#6499](https://github.com/facebook/docusaurus/pull/6499) docs: mention how env vars can be read ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6492](https://github.com/facebook/docusaurus/pull/6492) docs: mention where to find the sitemap ([@tamalweb](https://github.com/tamalweb))
- [#6491](https://github.com/facebook/docusaurus/pull/6491) docs: add developers.verida to showcase ([@nick-verida](https://github.com/nick-verida))
- [#6414](https://github.com/facebook/docusaurus/pull/6414) feat(website): new plugin to load CHANGELOG and render as blog ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6404](https://github.com/facebook/docusaurus/pull/6404) docs: elaborate on Markdown asset linking; document pathname:// protocol ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6484](https://github.com/facebook/docusaurus/pull/6484) docs: remove mention that CDN resources are cached cross-domain ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6429](https://github.com/facebook/docusaurus/pull/6429) refactor: self-host KaTeX assets ([@pranabdas](https://github.com/pranabdas))
- [#6483](https://github.com/facebook/docusaurus/pull/6483) docs: mark a lot of website texts as translatable ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-preset-classic`
- [#6627](https://github.com/facebook/docusaurus/pull/6627) docs: fix presets documentation link ([@thedanielhanke](https://github.com/thedanielhanke))
#### :house: Internal
- `docusaurus-theme-classic`
- [#6759](https://github.com/facebook/docusaurus/pull/6759) refactor(theme-classic): merge CSS files for Heading ([@slorber](https://github.com/slorber))
- [#6584](https://github.com/facebook/docusaurus/pull/6584) misc: enable jsx-key eslint rule ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`
- [#6756](https://github.com/facebook/docusaurus/pull/6756) test: sort migration test FS mock calls ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6609](https://github.com/facebook/docusaurus/pull/6609) refactor(migrate): change internal methods' parameter style ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6476](https://github.com/facebook/docusaurus/pull/6476) chore: fix Stylelint globs for editor support ([@nschonni](https://github.com/nschonni))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
- [#6744](https://github.com/facebook/docusaurus/pull/6744) fix(content-docs): properly display collocated social card image ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-types`, `docusaurus`
- [#6742](https://github.com/facebook/docusaurus/pull/6742) refactor: improve client modules types ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`
- [#6741](https://github.com/facebook/docusaurus/pull/6741) chore(module-type-aliases): add react as peer dependency ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6658](https://github.com/facebook/docusaurus/pull/6658) refactor(module-aliases): remove react-helmet dependency ([@Josh-Cena](https://github.com/Josh-Cena))
- Other
- [#6726](https://github.com/facebook/docusaurus/pull/6726) misc: improve bug report template ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6512](https://github.com/facebook/docusaurus/pull/6512) misc: configure linguist behavior to show better language stats ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6487](https://github.com/facebook/docusaurus/pull/6487) chore: fix codesandbox example link + mention npm publish recovery ([@slorber](https://github.com/slorber))
- [#6486](https://github.com/facebook/docusaurus/pull/6486) chore: update examples for beta.15 ([@slorber](https://github.com/slorber))
- [#6485](https://github.com/facebook/docusaurus/pull/6485) fix(website): bad translate tags without default translation ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`, `lqip-loader`
- [#6716](https://github.com/facebook/docusaurus/pull/6716) refactor: ensure lodash is default-imported ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-logger`, `docusaurus-migrate`, `docusaurus`
- [#6661](https://github.com/facebook/docusaurus/pull/6661) refactor: convert CLI entry points to ESM; migrate create-docusaurus to ESM ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-theme-common`, `docusaurus`
- [#6651](https://github.com/facebook/docusaurus/pull/6651) refactor: reduce exported members of docusaurus router ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
- [#6629](https://github.com/facebook/docusaurus/pull/6629) refactor: move module declarations for non-route components to theme-classic ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-pwa`, `docusaurus-theme-classic`
- [#6614](https://github.com/facebook/docusaurus/pull/6614) refactor: remove Babel plugins that are included in preset-env ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-translations`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
- [#6605](https://github.com/facebook/docusaurus/pull/6605) chore: fix ESLint warnings, restrict export all syntax ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`
- [#6583](https://github.com/facebook/docusaurus/pull/6583) refactor(live-codeblock): migrate theme to TS ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-common`, `docusaurus-utils`, `docusaurus`, `lqip-loader`
- [#6524](https://github.com/facebook/docusaurus/pull/6524) refactor: enforce named capture groups; clean up regexes ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`, `docusaurus-plugin-content-docs`, `docusaurus`
- [#6521](https://github.com/facebook/docusaurus/pull/6521) refactor: mark all functions that import external modules as async ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-cssnano-preset`, `docusaurus-logger`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-module-type-aliases`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-types`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `stylelint-copyright`
- [#6514](https://github.com/facebook/docusaurus/pull/6514) chore: clean up ESLint config, enable a few rules ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-types`, `docusaurus`
- [#6511](https://github.com/facebook/docusaurus/pull/6511) refactor(core): convert theme-fallback to TS ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-utils`
- [#6506](https://github.com/facebook/docusaurus/pull/6506) test: add test for readOutputHTMLFile ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`, `docusaurus-theme-common`
- [#6502](https://github.com/facebook/docusaurus/pull/6502) refactor: fix all eslint warnings ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus`
- [#6474](https://github.com/facebook/docusaurus/pull/6474) test: rename 'fixtures' to '**fixtures**' ([@nschonni](https://github.com/nschonni))
#### :running_woman: Performance
- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils`, `docusaurus`
- [#6725](https://github.com/facebook/docusaurus/pull/6725) refactor: convert all fs methods to async ([@Josh-Cena](https://github.com/Josh-Cena))
#### Committers: 38
- Alexey Pyltsyn ([@lex111](https://github.com/lex111))
- Artem Kovalov ([@artemkovalyov](https://github.com/artemkovalyov))
- Balthasar Hofer ([@lebalz](https://github.com/lebalz))
- Clement Demonchy ([@cdemonchy-pro](https://github.com/cdemonchy-pro))
- CodeDoctor ([@CodeDoctorDE](https://github.com/CodeDoctorDE))
- Daniel Hanke ([@thedanielhanke](https://github.com/thedanielhanke))
- Daniel Kalevski ([@kalevski](https://github.com/kalevski))
- Dmitry Vinnik ([@dmitryvinn](https://github.com/dmitryvinn))
- Dmitry Vinnik | Meta ([@dmitryvinn-fb](https://github.com/dmitryvinn-fb))
- Erick Zhao ([@erickzhao](https://github.com/erickzhao))
- Everardo J. Barojas M. ([@ebarojas](https://github.com/ebarojas))
- Felipe Santos ([@felipecrs](https://github.com/felipecrs))
- Gaurish ([@apidev234](https://github.com/apidev234))
- Hong Yongmin ([@revi](https://github.com/revi))
- Jody Heavener ([@jodyheavener](https://github.com/jodyheavener))
- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly))
- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
- Kishan Gajera ([@kgajera](https://github.com/kgajera))
- Konstantin Tarkus ([@koistya](https://github.com/koistya))
- Matheus Ricardo Brunelli ([@mrbrunelli](https://github.com/mrbrunelli))
- Matthew Ailes ([@vidarc](https://github.com/vidarc))
- Mikey O'Toole ([@homotechsual](https://github.com/homotechsual))
- Miles Johnson ([@milesj](https://github.com/milesj))
- Muhammad Redho Ayassa ([@redhoyasa](https://github.com/redhoyasa))
- Naseel Niyas ([@NaseelNiyas](https://github.com/NaseelNiyas))
- Nick Schonning ([@nschonni](https://github.com/nschonni))
- Pranab Das ([@pranabdas](https://github.com/pranabdas))
- Ruben Arushanyan ([@Ruben-Arushanyan](https://github.com/Ruben-Arushanyan))
- Sébastien Lorber ([@slorber](https://github.com/slorber))
- Tamal Web ([@tamalweb](https://github.com/tamalweb))
- Yangshun Tay ([@yangshun](https://github.com/yangshun))
- [@BigDataWriter](https://github.com/BigDataWriter)
- [@CookieJarApps](https://github.com/CookieJarApps)
- [@TheCatLady](https://github.com/TheCatLady)
- [@nick-verida](https://github.com/nick-verida)
- [@seyoon20087](https://github.com/seyoon20087)
- [@toto6038](https://github.com/toto6038)
- 이정환 ([@winterlood](https://github.com/winterlood))
## 2.0.0-beta.15 (2022-01-26)
#### :rocket: New Feature

2
admin/new.docusaurus.io/package.json
View file

@ -1,6 +1,6 @@
{
"name": "new.docusaurus.io",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"private": true,
"scripts": {
"start": "netlify dev"

2
admin/publish.md
View file

@ -118,7 +118,7 @@ You should still be on your local branch `<your_username>/<version_to_release>`
Make a commit/push, create a pull request with the changes.
Example PR: [#3114](https://github.com/facebook/docusaurus/pull/5098), using title such as `chore(v2): prepare v2.0.0-beta.0 release`
Example PR: [#3114](https://github.com/facebook/docusaurus/pull/5098), using title such as `chore: prepare v2.0.0-beta.0 release`
**Don't merge it yet**, but wait for the CI checks to complete.

2
lerna.json
View file

@ -1,5 +1,5 @@
{
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"npmClient": "yarn",
"useWorkspaces": true,
"changelog": {

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

@ -1,6 +1,6 @@
{
"name": "create-docusaurus",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Create Docusaurus apps easily.",
"type": "module",
"repository": {
@ -22,7 +22,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"commander": "^5.1.0",
"fs-extra": "^10.0.1",
"lodash": "^4.17.21",

8
packages/create-docusaurus/templates/classic-typescript/package.json
View file

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-classic-typescript-template",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -15,8 +15,8 @@
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/preset-classic": "2.0.0-beta.16",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.1.1",
"prism-react-renderer": "^1.2.1",
@ -24,7 +24,7 @@
"react-dom": "^17.0.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@tsconfig/docusaurus": "^1.0.4",
"typescript": "^4.5.2"
},

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

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-classic-template",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -14,8 +14,8 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/preset-classic": "2.0.0-beta.16",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.1.1",
"prism-react-renderer": "^1.2.1",

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

@ -1,6 +1,6 @@
{
"name": "docusaurus-2-facebook-template",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -18,8 +18,8 @@
"format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/preset-classic": "2.0.0-beta.16",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.1.1",
"react": "^17.0.1",

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

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

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/logger",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "An encapsulated logger for semantically formatting console messages.",
"main": "./lib/index.js",
"repository": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/mdx-loader",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus Loader for MDX",
"main": "lib/index.js",
"types": "src/mdx-loader.d.ts",
@ -20,8 +20,8 @@
"dependencies": {
"@babel/parser": "^7.17.3",
"@babel/traverse": "^7.17.3",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@mdx-js/mdx": "^1.6.22",
"escape-html": "^1.0.3",
"file-loader": "^6.2.0",
@ -36,7 +36,7 @@
"webpack": "^5.69.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.16",
"@types/escape-html": "^1.0.1",
"@types/mdast": "^3.0.7",
"@types/stringify-object": "^3.3.1",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/migrate",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "A CLI tool to migrate from older versions of Docusaurus.",
"main": "lib/index.js",
"license": "MIT",
@ -24,8 +24,8 @@
},
"dependencies": {
"@babel/preset-env": "^7.16.11",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@mapbox/hast-util-to-jsx": "^2.0.0",
"color": "^4.0.1",
"commander": "^5.1.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/module-type-aliases",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus module type aliases.",
"types": "./src/index.d.ts",
"publishConfig": {
@ -12,7 +12,7 @@
"directory": "packages/docusaurus-module-type-aliases"
},
"dependencies": {
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.16",
"@types/react": "*",
"@types/react-router-config": "*",
"@types/react-router-dom": "*",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-client-redirects",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Client redirects plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-client-redirects.d.ts",
@ -18,18 +18,18 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"eta": "^1.12.3",
"fs-extra": "^10.0.1",
"lodash": "^4.17.21",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-blog",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Blog plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-content-blog.d.ts",
@ -18,12 +18,12 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/mdx-loader": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/mdx-loader": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"cheerio": "^1.0.0-rc.10",
"feed": "^4.2.2",
"fs-extra": "^10.0.1",
@ -35,7 +35,7 @@
"webpack": "^5.69.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.16",
"escape-string-regexp": "^4.0.0"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-docs",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docs plugin for Docusaurus.",
"main": "lib/index.js",
"exports": {
@ -23,11 +23,11 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/mdx-loader": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/mdx-loader": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"combine-promises": "^1.1.0",
"fs-extra": "^10.0.1",
"import-fresh": "^3.3.0",
@ -39,8 +39,8 @@
"webpack": "^5.69.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@docusaurus/types": "2.0.0-beta.16",
"@types/js-yaml": "^4.0.5",
"@types/picomatch": "^2.3.0",
"commander": "^5.1.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-content-pages",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Pages plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-content-pages.d.ts",
@ -18,17 +18,17 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/mdx-loader": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/mdx-loader": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"fs-extra": "^10.0.1",
"remark-admonitions": "^1.2.1",
"tslib": "^2.3.1",
"webpack": "^5.69.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-debug",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Debug plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-debug.d.ts",
@ -18,14 +18,14 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"fs-extra": "^10.0.1",
"react-json-view": "^1.21.3",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-google-analytics",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Global analytics (analytics.js) plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-google-analytics.d.ts",
@ -18,12 +18,12 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-google-gtag",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Global Site Tag (gtag.js) plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-google-gtag.d.ts",
@ -18,12 +18,12 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-ideal-image",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).",
"main": "lib/index.js",
"types": "src/plugin-ideal-image.d.ts",
@ -21,11 +21,11 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/lqip-loader": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/lqip-loader": "2.0.0-beta.16",
"@docusaurus/responsive-loader": "^1.7.0",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/theme-translations": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"@endiliey/react-ideal-image": "^0.0.11",
"react-waypoint": "^10.1.0",
"sharp": "^0.30.1",
@ -33,8 +33,8 @@
"webpack": "^5.69.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@docusaurus/types": "2.0.0-beta.16",
"fs-extra": "^10.0.1"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-pwa",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus Plugin to add PWA support.",
"main": "lib/index.js",
"types": "src/plugin-pwa.d.ts",
@ -22,11 +22,11 @@
"dependencies": {
"@babel/core": "^7.17.5",
"@babel/preset-env": "^7.16.11",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-translations": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"babel-loader": "^8.2.3",
"clsx": "^1.1.1",
"core-js": "^3.21.0",
@ -39,7 +39,7 @@
"workbox-window": "^6.5.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"fs-extra": "^10.0.1"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-sitemap",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Simple sitemap generation plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-sitemap.d.ts",
@ -18,16 +18,16 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"fs-extra": "^10.0.1",
"sitemap": "^7.1.1",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/preset-classic",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Classic preset for Docusaurus.",
"main": "lib/index.js",
"types": "src/preset-classic.d.ts",
@ -18,17 +18,17 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/plugin-content-blog": "2.0.0-beta.15",
"@docusaurus/plugin-content-docs": "2.0.0-beta.15",
"@docusaurus/plugin-content-pages": "2.0.0-beta.15",
"@docusaurus/plugin-debug": "2.0.0-beta.15",
"@docusaurus/plugin-google-analytics": "2.0.0-beta.15",
"@docusaurus/plugin-google-gtag": "2.0.0-beta.15",
"@docusaurus/plugin-sitemap": "2.0.0-beta.15",
"@docusaurus/theme-classic": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-search-algolia": "2.0.0-beta.15"
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/plugin-content-blog": "2.0.0-beta.16",
"@docusaurus/plugin-content-docs": "2.0.0-beta.16",
"@docusaurus/plugin-content-pages": "2.0.0-beta.16",
"@docusaurus/plugin-debug": "2.0.0-beta.16",
"@docusaurus/plugin-google-analytics": "2.0.0-beta.16",
"@docusaurus/plugin-google-gtag": "2.0.0-beta.16",
"@docusaurus/plugin-sitemap": "2.0.0-beta.16",
"@docusaurus/theme-classic": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-search-algolia": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

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

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

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-classic",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Classic theme for Docusaurus",
"main": "lib/index.js",
"types": "src/theme-classic.d.ts",
@ -21,15 +21,15 @@
"format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/plugin-content-blog": "2.0.0-beta.15",
"@docusaurus/plugin-content-docs": "2.0.0-beta.15",
"@docusaurus/plugin-content-pages": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/plugin-content-blog": "2.0.0-beta.16",
"@docusaurus/plugin-content-docs": "2.0.0-beta.16",
"@docusaurus/plugin-content-pages": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-translations": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.1.1",
"copy-text-to-clipboard": "^3.0.1",
@ -42,8 +42,8 @@
"rtlcss": "^3.3.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@docusaurus/types": "2.0.0-beta.16",
"@types/mdx-js__react": "^1.5.5",
"@types/prismjs": "^1.26.0",
"@types/rtlcss": "^3.1.2",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-common",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Common code for Docusaurus themes.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,10 +18,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/plugin-content-blog": "2.0.0-beta.15",
"@docusaurus/plugin-content-docs": "2.0.0-beta.15",
"@docusaurus/plugin-content-pages": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@docusaurus/plugin-content-blog": "2.0.0-beta.16",
"@docusaurus/plugin-content-docs": "2.0.0-beta.16",
"@docusaurus/plugin-content-pages": "2.0.0-beta.16",
"clsx": "^1.1.1",
"parse-numeric-range": "^1.3.0",
"prism-react-renderer": "^1.3.1",
@ -29,8 +29,8 @@
"utility-types": "^3.10.0"
},
"devDependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/types": "2.0.0-beta.16",
"@testing-library/react-hooks": "^7.0.2",
"fs-extra": "^10.0.1",
"lodash": "^4.17.21"

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-live-codeblock",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus live code block component.",
"main": "lib/index.js",
"types": "src/theme-live-codeblock.d.ts",
@ -21,10 +21,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-translations": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"@philpl/buble": "^0.19.7",
"clsx": "^1.1.1",
"fs-extra": "^10.0.1",
@ -32,7 +32,7 @@
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.16",
"@types/buble": "^0.20.1"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-search-algolia",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Algolia search component for Docusaurus.",
"main": "lib/index.js",
"exports": {
@ -26,12 +26,12 @@
},
"dependencies": {
"@docsearch/react": "^3.0.0",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-translations": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"algoliasearch": "^4.12.1",
"algoliasearch-helper": "^3.7.0",
"clsx": "^1.1.1",
@ -42,7 +42,7 @@
"utility-types": "^3.10.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15"
"@docusaurus/module-type-aliases": "2.0.0-beta.16"
},
"peerDependencies": {
"react": "^16.8.4 || ^17.0.0",

6
packages/docusaurus-theme-translations/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-translations",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Docusaurus theme translations.",
"main": "lib/index.js",
"types": "lib/index.d.ts",
@ -23,8 +23,8 @@
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"lodash": "^4.17.21"
},
"engines": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/types",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Common types for Docusaurus packages.",
"types": "./src/index.d.ts",
"publishConfig": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils-common",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Common (Node/Browser) utility functions for Docusaurus packages.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -21,7 +21,7 @@
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15"
"@docusaurus/types": "2.0.0-beta.16"
},
"engines": {
"node": ">=14"

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils-validation",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Node validation utility functions for Docusaurus packages.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,8 +18,8 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"joi": "^17.6.0",
"tslib": "^2.3.1"
},

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Node utility functions for Docusaurus packages.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,7 +18,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"@svgr/webpack": "^6.0.0",
"file-loader": "^6.2.0",
"fs-extra": "^10.0.1",
@ -38,7 +38,7 @@
"node": ">=14"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.16",
"@types/dedent": "^0.7.0",
"@types/github-slugger": "^1.3.0",
"@types/micromatch": "^4.0.2",

18
packages/docusaurus/package.json
View file

@ -1,7 +1,7 @@
{
"name": "@docusaurus/core",
"description": "Easy to Maintain Open Source Documentation Websites",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"license": "MIT",
"publishConfig": {
"access": "public"
@ -41,13 +41,13 @@
"@babel/runtime": "^7.17.2",
"@babel/runtime-corejs3": "^7.17.2",
"@babel/traverse": "^7.17.3",
"@docusaurus/cssnano-preset": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/mdx-loader": "2.0.0-beta.15",
"@docusaurus/cssnano-preset": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/mdx-loader": "2.0.0-beta.16",
"@docusaurus/react-loadable": "5.5.2",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@docusaurus/utils-validation": "2.0.0-beta.16",
"@slorber/static-site-generator-webpack-plugin": "^4.0.1",
"@svgr/webpack": "^6.2.1",
"autoprefixer": "^10.4.2",
@ -106,8 +106,8 @@
"webpackbar": "^5.0.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.16",
"@docusaurus/types": "2.0.0-beta.16",
"@types/detect-port": "^1.3.2",
"@types/nprogress": "^0.2.0",
"@types/react-dom": "^17.0.11",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/lqip-loader",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"description": "Low Quality Image Placeholders (LQIP) loader for webpack.",
"main": "lib/index.js",
"publishConfig": {
@ -17,7 +17,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.16",
"file-loader": "^6.2.0",
"lodash": "^4.17.21",
"node-vibrant": "^3.1.6",

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

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

26
website/package.json
View file

@ -1,6 +1,6 @@
{
"name": "website",
"version": "2.0.0-beta.15",
"version": "2.0.0-beta.16",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -36,18 +36,18 @@
"dependencies": {
"@crowdin/cli": "^3.7.8",
"@crowdin/crowdin-api-client": "^1.14.0",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/plugin-client-redirects": "2.0.0-beta.15",
"@docusaurus/plugin-ideal-image": "2.0.0-beta.15",
"@docusaurus/plugin-pwa": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/theme-classic": "2.0.0-beta.15",
"@docusaurus/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-live-codeblock": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/core": "2.0.0-beta.16",
"@docusaurus/logger": "2.0.0-beta.16",
"@docusaurus/plugin-client-redirects": "2.0.0-beta.16",
"@docusaurus/plugin-ideal-image": "2.0.0-beta.16",
"@docusaurus/plugin-pwa": "2.0.0-beta.16",
"@docusaurus/preset-classic": "2.0.0-beta.16",
"@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.16",
"@docusaurus/theme-classic": "2.0.0-beta.16",
"@docusaurus/theme-common": "2.0.0-beta.16",
"@docusaurus/theme-live-codeblock": "2.0.0-beta.16",
"@docusaurus/utils": "2.0.0-beta.16",
"@docusaurus/utils-common": "2.0.0-beta.16",
"@popperjs/core": "^2.11.2",
"axios": "^0.26.0",
"clsx": "^1.1.1",

5
website/versioned_docs/version-2.0.0-beta.14/_partials/swizzleWarning.mdx
View file

@ -1,5 +0,0 @@
:::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.
:::

17
website/versioned_docs/version-2.0.0-beta.14/advanced/routing.md
View file

@ -1,17 +0,0 @@
# Routing
This page is only accessible through version-switching. It shows how a versioned doc file becomes a webpage.
```mdx-code-block
import {useLatestVersion, useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
import {useLocation} from '@docusaurus/router';
export const URLPath = () => <code>{useLocation().pathname}</code>;
export const FilePath = () => {
const currentVersion = useActiveDocContext('default').activeVersion.name;
return <code>{currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md</code>;
}
```
This page, <URLPath />, is generated from the file at <FilePath />. The component used is `@theme/DocItem`.

130
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-client-redirects.md
View file

@ -1,130 +0,0 @@
---
sidebar_position: 4
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'];
}
},
},
],
],
};
```

40
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-debug.md
View file

@ -1,40 +0,0 @@
---
sidebar_position: 5
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'],
};
```

94
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-google-analytics.md
View file

@ -1,94 +0,0 @@
---
sidebar_position: 6
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}
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trackingID` | `string` | **Required** | The tracking ID of your analytics service. |
| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
</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 = {
trackingID: 'UA-141789564-1',
anonymizeIP: true,
};
```
### 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
googleAnalytics: {
trackingID: 'UA-141789564-1',
anonymizeIP: true,
},
// 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-google-analytics',
// highlight-start
{
trackingID: 'UA-141789564-1',
anonymizeIP: true,
},
// highlight-end
],
],
};
```

100
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-google-gtag.md
View file

@ -1,100 +0,0 @@
---
sidebar_position: 7
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}
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trackingID` | `string` | **Required** | The tracking ID of your gtag service. |
| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
</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 = {
trackingID: 'UA-141789564-1',
anonymizeIP: true,
};
```
### 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
gtag: {
trackingID: 'UA-141789564-1',
anonymizeIP: true,
},
// 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-google-gtag',
// highlight-start
{
trackingID: 'UA-141789564-1',
anonymizeIP: true,
},
// highlight-end
],
],
};
```

53
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-ideal-image.md
View file

@ -1,53 +0,0 @@
---
sidebar_position: 8
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 |

37
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-sitemap.md
View file

@ -1,37 +0,0 @@
---
sidebar_position: 10
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,
},
],
],
};
```

1052
website/versioned_docs/version-2.0.0-beta.14/guides/docs/sidebar.md
View file

File diff suppressed because it is too large Load diff

216
website/versioned_docs/version-2.0.0-beta.14/guides/docs/versioning.md
View file

@ -1,216 +0,0 @@
---
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-[versionName]/` folder.
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-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 versions 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 collocated assets {#global-or-versioned-collocated-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)
```

116
website/versioned_docs/version-2.0.0-beta.14/guides/markdown-features/markdown-features-math-equations.mdx
View file

@ -1,116 +0,0 @@
---
id: math-equations
title: Math Equations
description: Writing LaTeX Math Equations
slug: /markdown-features/math-equations
---
Mathematical equations can be rendered using [KaTeX](https://katex.org).
## Usage
Please read [KaTeX](https://katex.org) documentation for more details.
### Inline
Write inline math equations by wrapping LaTeX equations between `$`:
```mdx
Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
\int_{a}^{x}f(t)dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
```
Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
\int_{a}^{x}f(t)dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
### Blocks
For equation block or display mode, use line breaks and `$$`:
```mdx
$$
I = \int_0^{2\pi} \sin(x) dx
$$
```
$$
I = \int_0^{2\pi} \sin(x) dx
$$
## Configuration
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
```bash npm2yarn
npm install --save remark-math@3 rehype-katex@4 hast-util-is-element@1.1.0
```
:::caution
Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
:::
Import the plugins in `docusaurus.config.js`:
```js
const math = require('remark-math');
const katex = require('rehype-katex');
```
Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
```js
remarkPlugins: [math],
rehypePlugins: [katex],
```
Include the KaTeX CSS in your config under `stylesheets`:
```js
stylesheets: [
{
href: "https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css",
integrity: "sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc",
crossorigin: "anonymous",
},
],
```
Overall the changes look like:
```js title="docusaurus.config.js"
// highlight-start
const math = require('remark-math');
const katex = require('rehype-katex');
// highlight-end
module.exports = {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
// highlight-start
remarkPlugins: [math],
rehypePlugins: [katex],
// highlight-end
},
},
],
],
// highlight-start
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css',
integrity:
'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc',
crossorigin: 'anonymous',
},
],
// highlight-end
};
```

218
website/versioned_docs/version-2.0.0-beta.14/guides/markdown-features/markdown-features-react.mdx
View file

@ -1,218 +0,0 @@
---
id: react
title: MDX and React
description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
slug: /markdown-features/react
---
# MDX and React
```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';
```
## Using JSX in Markdown {#using-jsx-in-markdown}
Docusaurus has built-in support for [MDX v1](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components.
:::note
While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax.
:::
:::caution
MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018).
Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
:::
Try this block here:
```jsx
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
```
Notice how it renders both the markup from your React component and the Markdown syntax:
```mdx-code-block
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<BrowserWindow minHeight={240} url="http://localhost:3000">
<Highlight color="#25c2a0">Docusaurus green</Highlight>
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
</BrowserWindow>
```
<br />
You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
:::caution
Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
:::
## Importing code snippets {#importing-code-snippets}
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, first you need to install it in your project:
```bash npm2yarn
npm install --save raw-loader
```
Now you can import code snippets from another file as it is:
<!-- prettier-ignore-start -->
```jsx title="myMarkdownFile.mdx"
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
```
<!-- prettier-ignore-end -->
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!@site/src/pages/examples/_myComponent';
<BrowserWindow url="http://localhost:3000">
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
</BrowserWindow>
<br />
```
You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock:
```jsx
<CodeBlock className="language-jsx" title="/src/myComponent">
{MyComponentSource}
</CodeBlock>
```
:::note
You have to use `<CodeBlock>` rather than the Markdown triple-backtick ` ``` `, because the latter will ship out any of its content as-is, but you want JSX to insert the imported text here.
:::
:::warning
This feature is experimental and might be subject to API breaking changes in the future.
:::
## Importing Markdown {#importing-markdown}
You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.
By convention, using the **`_` filename prefix** will not create any doc page and means the markdown file is a **"partial"**, to be imported by other files.
```md title="_markdown-partial-example.mdx"
<span>Hello {props.name}</span>
This is text some content from `_markdown-partial-example.mdx`.
```
```jsx title="someOtherDoc.mdx"
import PartialExample from './_markdown-partial-example.mdx';
<PartialExample name="Sebastien" />;
```
```mdx-code-block
import PartialExample from './_markdown-partial-example.mdx';
<BrowserWindow url="http://localhost:3000">
<PartialExample name="Sebastien" />
</BrowserWindow>
<br />
```
This way, you can reuse contents among multiple pages and avoid duplicating materials.
:::caution
The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
:::
## Available exports
Within the MDX page, the following variables are available as globals:
- `frontMatter`: the front matter as a record of string keys and values;
- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case.
- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter).
```jsx
import TOCInline from '@theme/TOCInline';
import CodeBlock from '@theme/CodeBlock';
The table of contents for this page, serialized:
<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
The front matter of this page:
<ul>
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
</ul>
<p>The title of this page is: <b>{contentTitle}</b></p>
```
```mdx-code-block
import TOCInline from '@theme/TOCInline';
<BrowserWindow>
The table of contents for this page, serialized:
<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
The front matter of this page:
<ul>
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
</ul>
<p>The title of this page is: <b>{contentTitle}</b></p>
</BrowserWindow>
```

336
website/versioned_docs/version-2.0.0-beta.14/i18n/i18n-tutorial.md
View file

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

137
website/versioned_docs/version-2.0.0-beta.14/presets.md
View file

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

71
website/versioned_docs/version-2.0.0-beta.14/static-assets.md
View file

@ -1,71 +0,0 @@
---
id: static-assets
title: Static Assets
---
Every website needs assets: images, stylesheets, favicons etc. By default, you are suggested to put these assets in the `static` folder.
Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
This means that:
- for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`.
- for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`.
You can customize the static directory sources in `docusaurus.config.js`. For example, we can add `public` as another possible path:
```js title="docusaurus.config.js"
module.exports = {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};
```
Now, all files in `public` as well as `static` will be copied to the build output.
## Referencing your static asset {#referencing-your-static-asset}
In JSX, you can reference assets from the `static` folder in your code using absolute paths, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `<img src="/img/docusaurus.png" />` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
:::info
In Markdown, things are different: you can stick to use absolute paths because Docusaurus actually handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
:::
### Examples {#examples}
```jsx title="MyComponent.js"
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;
```
```jsx title="MyComponent.js"
<img src={require('@site/static/img/docusaurus.png').default} />
```
```jsx title="MyComponent.js"
import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;
```
You can also import SVG files: they will be transformed into React components.
```jsx title="MyComponent.js"
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
```
### Caveats {#caveats}
Keep in mind that:
- By default, none of the files in `static` folder will be post-processed, hashed or minified.
- Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting.

183
website/versioned_docs/version-2.0.0-beta.14/using-plugins.md
View file

@ -1,183 +0,0 @@
---
id: using-plugins
title: Plugins
---
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via [presets](presets.md).
## Available plugins {#available-plugins}
We maintain a [list of official plugins](./api/plugins/overview.md), but the community has also created some [unofficial plugins](/community/resources#community-plugins).
## Installing a plugin {#installing-a-plugin}
A plugin is usually a npm package, so you install them like other npm packages using npm.
```bash npm2yarn
npm install --save docusaurus-plugin-name
```
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
```jsx {3} title="docusaurus.config.js"
module.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};
```
Docusaurus can also load plugins from your local directory, you can do something like the following:
```jsx {5} title="docusaurus.config.js"
const path = require('path');
module.exports = {
// ...
plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
};
```
## Configuring plugins {#configuring-plugins}
For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.
However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
```js {4-9} title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};
```
Example:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
// Basic usage.
'@docusaurus/plugin-google-analytics',
// With options object (babel style)
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};
```
## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids}
All Docusaurus content plugins can support multiple plugin instances.
The Docs plugin has [additional multi-instance documentation](./guides/docs/docs-multi-instance.mdx)
It is required to assign a unique id to each plugin instance.
By default, the plugin id is `default`.
```js {6,13} title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-xxx',
{
id: 'plugin-xxx-1',
// other options
},
],
[
'@docusaurus/plugin-xxx',
{
id: 'plugin-xxx-2',
// other options
},
],
],
};
```
:::note
At most one plugin instance can be the "default plugin instance", by omitting the `id` attribute, or using `id: 'default'`.
:::
## Plugins design {#plugins-design}
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
## Creating plugins {#creating-plugins}
A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object. You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md).
### Functional definition {#functional-definition}
You can use a plugin as a function directly included in the Docusaurus config file:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
// highlight-start
function myPlugin(context, options) {
// ...
return {
name: 'my-plugin',
async loadContent() {
// ...
},
async contentLoaded({content, actions}) {
// ...
},
/* other lifecycle API */
};
},
// highlight-end
],
};
```
### Module definition {#module-definition}
You can use a plugin as a module path referencing a separate file or NPM package:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
// without options:
'./my-plugin',
// or with options:
['./my-plugin', options],
],
};
```
Then in the folder `my-plugin` you can create an index.js such as this:
```js title="my-plugin.js"
module.exports = function myPlugin(context, options) {
// ...
return {
name: 'my-plugin',
async loadContent() {
/* ... */
},
async contentLoaded({content, actions}) {
/* ... */
},
/* other lifecycle API */
};
};
```

249
website/versioned_docs/version-2.0.0-beta.14/using-themes.md
View file

@ -1,249 +0,0 @@
---
id: using-themes
title: Themes
---
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.
**Themes are for providing UI components to present the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy.
For example, a Docusaurus blog consists of a blog plugin and a blog theme.
:::note
This is a contrived example: in practice, `@docusaurus/theme-classic` provides the theme for docs, blog, and layouts.
:::
```js title="docusaurus.config.js"
module.exports = {
themes: ['theme-blog'],
plugins: ['plugin-content-blog'],
};
```
And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme):
```js title="docusaurus.config.js"
module.exports = {
themes: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
};
```
## Available themes {#available-themes}
We maintain a [list of official themes](./api/themes/overview.md).
## Using themes {#using-themes}
To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes:
```js {3} title="docusaurus.config.js"
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};
```
## Theme components {#theme-components}
Most of the time, theme is used to provide a set of React components, e.g. `Navbar`, `Layout`, `Footer`.
Users can use these components in their code by importing them using the `@theme` webpack alias:
```js
import Navbar from '@theme/Navbar';
```
The alias `@theme` can refer to a few directories, in the following priority:
1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
2. A Docusaurus theme packages's `theme` directory.
3. Fallback components provided by Docusaurus core (usually not needed).
## Swizzling theme components {#swizzling-theme-components}
```mdx-code-block
import SwizzleWarning from "./_partials/swizzleWarning.mdx"
<SwizzleWarning/>
```
Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`. Given the following structure:
```
website
├── node_modules
│ └── docusaurus-theme
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js
```
`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. In iOS, method swizzling is the process of changing the implementation of an existing selector (method). In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.
To swizzle a component for a theme, run the following command in your doc site:
```bash npm2yarn
npm run swizzle <theme name> [component name]
```
As an example, to swizzle the `<Footer />` component in `@docusaurus/theme-classic` for your site, run:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Footer
```
This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.
Although we highly discourage swizzling of all components, if you wish to do that, run:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic
```
**Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component.
## Wrapping theme components {#wrapping-theme-components}
Sometimes, you just want to wrap an existing theme component with additional logic, and it can be a pain to have to maintain an almost duplicate copy of the original theme component.
In such case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it.
### For site owners {#for-site-owners}
The `@theme-original` alias allows you to import the original theme component.
Here is an example to display some text just above the footer, with minimal code duplication.
```js title="src/theme/Footer.js"
// Note: importing from "@theme/Footer" would fail due to the file importing itself
import OriginalFooter from '@theme-original/Footer';
import React from 'react';
export default function Footer(props) {
return (
<>
<div>Before footer</div>
<OriginalFooter {...props} />
</>
);
}
```
### For plugin authors {#for-plugin-authors}
One theme can wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
```js
import InitialCodeBlock from '@theme-init/CodeBlock';
import React from 'react';
export default function CodeBlock(props) {
return props.live ? (
<ReactLivePlayground {...props} />
) : (
<InitialCodeBlock {...props} />
);
}
```
Check the code of `docusaurus-theme-live-codeblock` for details.
:::caution
Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-codeblock`), you likely don't need `@theme-init`.
:::
<details>
<summary>How are theme aliases resolved?</summary>
It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup where three themes/plugins and the site itself all try to define the same component. Internally, Docusaurus loads these themes as a "stack".
```text
+-------------------------------------------------+
| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top
+-------------------------------------------------+
| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component
+-------------------------------------------------+
| `plugin-awesome-codeblock/theme/CodeBlock.js` |
+-------------------------------------------------+
| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom
+-------------------------------------------------+
```
The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
`@theme/*` always points to the topmost component—when code block is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
`@theme-init/*` always points to the bottommost component—usually this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
</details>
## Wrapping your site with `<Root>` {#wrapper-your-site-with-root}
A `<Root>` theme component is rendered at the very top of your Docusaurus site. It allows you to wrap your site with additional logic, by creating a file at `src/theme/Root.js`:
```js title="website/src/theme/Root.js"
import React from 'react';
// Default implementation, that you can customize
function Root({children}) {
return <>{children}</>;
}
export default Root;
```
This component is applied above the router and the theme `<Layout>`, and will **never unmount**.
:::tip
Use this component to render React Context providers and global stateful logic.
:::
## Themes design {#themes-design}
While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.
Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by a `src/theme` directory full of components.
To summarize:
- Themes share the same lifecycle methods with Plugins
- Themes are run after all existing Plugins
- Themes exist to add component aliases by extending the webpack config
## Writing customized Docusaurus themes {#writing-customized-docusaurus-themes}
A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:
```shell {5-7}
website
├── package.json
└── src
├── index.js
└── theme
├── MyThemeComponent
└── AnotherThemeComponent.js
```
There are two lifecycle methods that are essential to theme implementation:
- [`getThemePath()`](./api/plugin-methods/extend-infrastructure.md#getThemePath)
- [`getClientModules()`](./api/plugin-methods/lifecycle-apis.md#getClientModules)
These lifecycle methods are not essential but recommended:
- [`validateThemeConfig({themeConfig, validate})`](./api/plugin-methods/static-methods.md#validateThemeConfig)
- [`validateOptions({options, validate})`](./api/plugin-methods/static-methods.md#validateOptions)

28
website/versioned_docs/version-2.0.0-beta.16/advanced/architecture.md Normal file
View file

@ -0,0 +1,28 @@
---
description: How Docusaurus works to build your app
---
# Architecture
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Zoom from '@site/src/components/Zoom';
```
<Zoom>
![Architecture overview](/img/architecture.png)
</Zoom>
This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle.
Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments:
- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d.
- The theme code is built with Webpack. They can be provided as ESM—following React conventions.
Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options).
During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.md#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable.

77
website/versioned_docs/version-2.0.0-beta.16/advanced/client.md Normal file
View file

@ -0,0 +1,77 @@
# Client architecture
## Theme aliases {#theme-aliases}
A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias:
```js
import Navbar from '@theme/Navbar';
```
The alias `@theme` can refer to a few directories, in the following priority:
1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
2. A Docusaurus theme package's `theme` directory.
3. Fallback components provided by Docusaurus core (usually not needed).
This is called a _layered architecture_: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. Given the following structure:
```
website
├── node_modules
│ └── @docusaurus/theme-classic
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js
```
`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. If you are familiar with Objective C where a function's implementation can be swapped during runtime, it's the exact same concept here with changing the target `@theme/Navbar` is pointing to!
We already talked about how the "userland theme" in `src/theme` can re-use a theme component through the [`@theme-original`](#wrapping) alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
```js
import InitialCodeBlock from '@theme-init/CodeBlock';
import React from 'react';
export default function CodeBlock(props) {
return props.live ? (
<ReactLivePlayground {...props} />
) : (
<InitialCodeBlock {...props} />
);
}
```
Check the code of `@docusaurus/theme-live-codeblock` for details.
:::caution
Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`.
:::
It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack".
```text
+-------------------------------------------------+
| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top
+-------------------------------------------------+
| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component
+-------------------------------------------------+
| `plugin-awesome-codeblock/theme/CodeBlock.js` |
+-------------------------------------------------+
| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom
+-------------------------------------------------+
```
The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!

12
website/versioned_docs/version-2.0.0-beta.16/advanced/index.md Normal file
View file

@ -0,0 +1,12 @@
# Advanced Tutorials
This section is not going to be very structured, but we will cover the following topics:
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
We will assume that you have finished the guides, and know the basics like how to configure plugins, how to write React components, etc. These sections will have plugin authors and code contributors in mind, so we may occasionally refer to [plugin APIs](../api/plugin-methods/README.md) or other architecture details. Don't panic if you don't understand everything😉

129
website/versioned_docs/version-2.0.0-beta.16/advanced/plugins.md Normal file
View file

@ -0,0 +1,129 @@
# Plugins
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets.
## Creating plugins {#creating-plugins}
A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md).
### Function definition {#function-definition}
You can use a plugin as a function directly included in the Docusaurus config file:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
// highlight-start
async function myPlugin(context, options) {
// ...
return {
name: 'my-plugin',
async loadContent() {
// ...
},
async contentLoaded({content, actions}) {
// ...
},
/* other lifecycle API */
};
},
// highlight-end
],
};
```
### Module definition {#module-definition}
You can use a plugin as a module path referencing a separate file or NPM package:
```js title="docusaurus.config.js"
module.exports = {
// ...
plugins: [
// without options:
'./my-plugin',
// or with options:
['./my-plugin', options],
],
};
```
Then in the folder `my-plugin`, you can create an `index.js` such as this:
```js title="my-plugin.js"
module.exports = async function myPlugin(context, options) {
// ...
return {
name: 'my-plugin',
async loadContent() {
/* ... */
},
async contentLoaded({content, actions}) {
/* ... */
},
/* other lifecycle API */
};
};
```
---
You can view all plugins installed in your site using the [debug plugin's metadata panel](/__docusaurus/debug/metadata).
Plugins come as several types:
- `package`: an external package you installed
- `project`: a plugin you created in your project, given to Docusaurus as a local file path
- `local`: a plugin created using the function definition
- `synthetic`: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail.
You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`.
## Plugin design {#plugin-design}
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.
### Theme design {#theme-design}
When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`...
**Themes provide the set of UI components to render the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy.
For example, a Docusaurus blog may consist of a blog plugin and a blog theme.
:::note
This is a contrived example: in practice, `@docusaurus/theme-classic` provides the theme for docs, blog, and layouts.
:::
```js title="docusaurus.config.js"
module.exports = {
// highlight-next-line
themes: ['theme-blog'],
plugins: ['plugin-content-blog'],
};
```
And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme):
```js title="docusaurus.config.js"
module.exports = {
// highlight-next-line
themes: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
};
```
Now, although the theme receives the same data from the plugin, how the theme chooses to _render_ the data as UI can be drastically different.
While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives.
Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use [`loadContent`](../api/plugin-methods/lifecycle-apis.md#loadContent), since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an `src/theme` directory full of components, which are made known to the core through the [`getThemePath`](../api/plugin-methods/extend-infrastructure.md#getThemePath) lifecycle.
To summarize:
- Themes share the same lifecycle methods with Plugins
- Themes are run after all existing Plugins
- Themes add component aliases by providing `getThemePath`.

279
website/versioned_docs/version-2.0.0-beta.16/advanced/routing.md Normal file
View file

@ -0,0 +1,279 @@
---
description: "Docusaurus' routing system follows single-page application conventions: one route, one component."
---
# Routing
```mdx-code-block
import Link from '@docusaurus/Link';
import {useLatestVersion, useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
import {useLocation} from '@docusaurus/router';
import BrowserWindow from '@site/src/components/BrowserWindow';
```
Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system.
## Routing in content plugins {#routing-in-content-plugins}
Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this:
![plugin routes model](/img/routes.png#gh-light-mode-only)![plugin routes model](/img/routes-dark.png#gh-dark-mode-only)
Any route will be matched against this nested route config until a good match is found. For example, when given a route `/docs/configuration`, Docusaurus first enters the `/docs` branch, and then searches among the subroutes created by the docs plugin.
Changing `routeBasePath` can effectively alter your site's route structure. For example, in [Docs-only mode](../guides/docs/docs-introduction.md#docs-only-mode), we mentioned that configuring `routeBasePath: '/'` for docs means that all routes that the docs plugin create would not have the `/docs` prefix, yet it doesn't prevent you from having more subroutes like `/blog` created by other plugins.
Next, let's look at how the three plugins structure their own "boxes of subroutes".
### Pages routing {#pages-routing}
Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information.
The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component.
### Blog routing {#blog-routing}
The blog creates the following routes:
- **Posts list pages**: `/`, `/page/2`, `/page/3`...
- The component is `@theme/BlogListPage`.
- **Post pages**: `/2021/11/21/algolia-docsearch-migration`, `/2021/05/12/announcing-docusaurus-two-beta`...
- Generated from each Markdown post.
- The routes are fully customizable through the `slug` front matter.
- The component is `@theme/BlogPostPage`.
- **Tags list page**: `/tags`
- The route is customizable through the `tagsBasePath` option.
- The component is `@theme/BlogTagsListPage`.
- **Tag pages**: `/tags/adoption`, `/tags/beta`...
- Generated through the tags defined in each post's front matter.
- The routes always have base defined in `tagsBasePath`, but the subroutes are customizable through the tag's `permalink` field.
- The component is `@theme/BlogTagsPostsPage`.
- **Archive page**: `/archive`
- The route is customizable through the `archiveBasePath` option.
- The component is `@theme/BlogArchivePage`.
### Docs routing {#docs-routing}
The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`.
```mdx-code-block
export const URLPath = () => <code>{useLocation().pathname}</code>;
export const FilePath = () => {
const currentVersion = useActiveDocContext('default').activeVersion.name;
return <code>{currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md</code>;
}
```
The individual docs are rendered in the remaining space after the navbar, footer, sidebar, etc. have all been provided by the `DocPage` component. For example, this page, <URLPath />, is generated from the file at <FilePath />. The component used is `@theme/DocItem`.
The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`.
### File paths and URL paths {#file-paths-and-url-paths}
Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure.
When writing links in Markdown, you could either mean a _file path_, or a _URL path_, which Docusaurus would use several heuristics to determine.
- If the path has a `@site` prefix, it is _always_ an asset file path.
- If the path has an `http(s)://` prefix, it is _always_ a URL path.
- If the path doesn't have an extension, it is a URL path. For example, a link `[page](../plugins)` on a page with URL `/docs/advanced/routing` will link to `/docs/plugins`. Docusaurus will only detect broken links when building your site (when it knows the full route structure), but will make no assumptions about the existence of a file. It is exactly equivalent to writing `<a href="../plugins">page</a>` in a JSX file.
- If the path has an `.md(x)` extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path.
- If the path has any other extension, Docusaurus would treat it as [an asset](../guides/markdown-features/markdown-features-assets.mdx) and bundle it.
The following directory structure may help you visualize this file -> URL mapping. Assume that there's no slug customization in any page.
<details>
<summary>A sample site structure</summary>
```bash
.
├── blog # blog plugin has routeBasePath: '/blog'
│ ├── 2019-05-28-first-blog-post.md # -> /blog/2019/05/28/first-blog-post
│ ├── 2019-05-29-long-blog-post.md # -> /blog/2019/05/29/long-blog-post
│ ├── 2021-08-01-mdx-blog-post.mdx # -> /blog/2021/08/01/mdx-blog-post
│ └── 2021-08-26-welcome
│ ├── docusaurus-plushie-banner.jpeg
│ └── index.md # -> /blog/2021/08/26/welcome
├── docs # docs plugin has routeBasePath: '/docs'; current version has base path '/'
│ ├── intro.md # -> /docs/intro
│ ├── tutorial-basics
│ │ ├── _category_.json
│ │ ├── congratulations.md # -> /docs/tutorial-basics/congratulations
│ │ └── markdown-features.mdx # -> /docs/tutorial-basics/congratulations
│ └── tutorial-extras
│ ├── _category_.json
│ ├── manage-docs-versions.md # -> /docs/tutorial-extras/manage-docs-versions
│ └── translate-your-site.md # -> /docs/tutorial-extras/translate-your-site
├── src
│ └── pages # pages plugin has routeBasePath: '/'
│ ├── index.module.css
│ ├── index.tsx # -> /
│ └── markdown-page.md # -> /markdown-page
└── versioned_docs
└── version-1.0.0 # version has base path '/1.0.0'
├── intro.md # -> /docs/1.0.0/intro
├── tutorial-basics
│ ├── _category_.json
│ ├── congratulations.md # -> /docs/1.0.0/tutorial-basics/congratulations
│ └── markdown-features.mdx # -> /docs/1.0.0/tutorial-basics/congratulations
└── tutorial-extras
├── _category_.json
├── manage-docs-versions.md # -> /docs/1.0.0/tutorial-extras/manage-docs-versions
└── translate-your-site.md # -> /docs/1.0.0/tutorial-extras/translate-your-site
```
</details>
So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general.
## Routes become HTML files {#routes-become-html-files}
Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that.
The `/docs/advanced/routing` route can correspond to either `/docs/advanced/routing/index.html` or `/docs/advanced/routing.html`. Some hosting providers differentiate between them using the presence of a trailing slash, and may or may not tolerate the other. Read more in the [trailing slash guide](https://github.com/slorber/trailing-slash-guide).
For example, the build output of the directory above is (ignoring other assets and JS bundle):
<details>
<summary>Output of the above workspace</summary>
```bash
build
├── 404.html # /404/
├── blog
│ ├── archive
│ │ └── index.html # /blog/archive/
│ ├── first-blog-post
│ │ └── index.html # /blog/first-blog-post/
│ ├── index.html # /blog/
│ ├── long-blog-post
│ │ └── index.html # /blog/long-blog-post/
│ ├── mdx-blog-post
│ │ └── index.html # /blog/mdx-blog-post/
│ ├── tags
│ │ ├── docusaurus
│ │ │ └── index.html # /blog/tags/docusaurus/
│ │ ├── hola
│ │ │ └── index.html # /blog/tags/hola/
│ │ └── index.html # /blog/tags/
│ └── welcome
│ └── index.html # /blog/welcome/
├── docs
│ ├── 1.0.0
│ │ ├── intro
│ │ │ └── index.html # /docs/1.0.0/intro/
│ │ ├── tutorial-basics
│ │ │ ├── congratulations
│ │ │ │ └── index.html # /docs/1.0.0/tutorial-basics/congratulations/
│ │ │ └── markdown-features
│ │ │ └── index.html # /docs/1.0.0/tutorial-basics/markdown-features/
│ │ └── tutorial-extras
│ │ ├── manage-docs-versions
│ │ │ └── index.html # /docs/1.0.0/tutorial-extras/manage-docs-versions/
│ │ └── translate-your-site
│ │ └── index.html # /docs/1.0.0/tutorial-extras/translate-your-site/
│ ├── intro
│ │ └── index.html # /docs/1.0.0/intro/
│ ├── tutorial-basics
│ │ ├── congratulations
│ │ │ └── index.html # /docs/tutorial-basics/congratulations/
│ │ └── markdown-features
│ │ └── index.html # /docs/tutorial-basics/markdown-features/
│ └── tutorial-extras
│ ├── manage-docs-versions
│ │ └── index.html # /docs/tutorial-extras/manage-docs-versions/
│ └── translate-your-site
│ └── index.html # /docs/tutorial-extras/translate-your-site/
├── index.html # /
└── markdown-page
└── index.html # /markdown-page/
```
</details>
If `trailingSlash` is set to `false`, the build would emit `intro.html` instead of `intro/index.html`.
All HTML files will reference its JS assets using absolute URLs, so in order for the correct assets to be located, you have to configure the `baseUrl` field. Note that `baseUrl` doesn't affect the emitted bundle's file structure: the base URL is one level above the Docusaurus routing system. You can see the aggregate of `url` and `baseUrl` as the actual location of your Docusaurus site.
For example, the emitted HTML would contain links like `<link rel="preload" href="/assets/js/runtime~main.7ed5108a.js" as="script">`. Because absolute URLs are resolved from the host, if the bundle placed under the path `https://example.com/base/`, the link will point to `https://example.com/assets/js/runtime~main.7ed5108a.js`, which is, well, non-existent. By specifying `/base/` as base URL, the link will correctly point to `/base/assets/js/runtime~main.7ed5108a.js`.
Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`.
## Generating and accessing routes {#generating-and-accessing-routes}
The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files.
All routes are aggregated in `.docusaurus/routes.js`, which you can view with the debug plugin's [routes panel](/__docusaurus/debug/routes).
On the client side, we offer `@docusaurus/router` to access the page's route. `@docusaurus/router` is a re-export of the [`react-router-dom`](https://www.npmjs.com/package/react-router-dom/v/5.3.0) package. For example, you can use `useLocation` to get the current page's [location](https://developer.mozilla.org/en-US/docs/Web/API/Location), and `useHistory` to access the [history object](https://developer.mozilla.org/en-US/docs/Web/API/History). (They are not the same as the browser API, although similar in functionality. Refer to the React Router documentation for specific APIs.)
This API is **SSR safe**, as opposed to the browser-only `window.location`.
```jsx title="myComponent.js"
import React from 'react';
import {useLocation} from '@docusaurus/router';
export function PageRoute() {
// React router provides the current component's route, even in SSR
const location = useLocation();
return (
<span>
We are currently on <code>{location.pathname}</code>
</span>
);
}
```
```mdx-code-block
export function PageRoute() {
const location = useLocation();
return (
<span>
We are currently on <code>{location.pathname}</code>
</span>
);
}
<BrowserWindow>
<PageRoute />
</BrowserWindow>
```
## Escaping from SPA redirects {#escaping-from-spa-redirects}
Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead.
If you put some HTML pages under the `static` folder, they will be copied to the build output and therefore become accessible as part of your website, yet it's not part of the Docusaurus route system. We provide a `pathname://` protocol that allows you to redirect to another part of your domain in a non-SPA fashion, as if this route is an external link. Try the following two links:
```md
- [/pure-html](/pure-html)
- [pathname:///pure-html](pathname:///pure-html)
```
<BrowserWindow>
- <Link data-noBrokenLinkCheck="true" to="/pure-html">/pure-html</Link>
- [pathname:///pure-html](pathname:///pure-html)
</BrowserWindow>
:::tip
The first link will trigger a "broken links detected" check during the production build.
:::
The `pathname://` protocol is useful for referencing any content in the static folder. For example, Docusaurus would convert [all Markdown static assets to require() calls](../guides/markdown-features/markdown-features-assets.mdx#static-assets). You can use `pathname://` to keep it a regular link instead of being hashed by Webpack.
```md title="my-doc.md"
![An image from the static](pathname:///img/docusaurus.png)
[An asset from the static](pathname:///files/asset.pdf)
```
Docusaurus will only strip the `pathname://` prefix without processing the content.

206
website/versioned_docs/version-2.0.0-beta.16/advanced/ssg.md Normal file
View file

@ -0,0 +1,206 @@
---
sidebar_label: Static site generation
description: Docusaurus statically renders your React code into HTML, allowing faster load speed and better SEO.
---
# Static site generation (SSG)
In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice:
- During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages.
- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript.
:::info SSR or SSG?
_Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably.
:::
Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either.
```jsx
import React from 'react';
export default function WhereAmI() {
return <span>{window.location.href}</span>;
}
```
This looks like idiomatic React, but if you run `docusaurus build`, you will get an error:
```
ReferenceError: window is not defined
```
This is because during server-side rendering, the Docusaurus app isn't actually run in browser, and it doesn't know what `window` is.
<details id="node-env">
<summary>What about <code>process.env.NODE_ENV</code>?</summary>
One exception to the "no Node globals" rule is `process.env.NODE_ENV`. In fact, you can use it in React, because Webpack injects this variable as a global:
```jsx
import React from 'react';
export default function expensiveComp() {
if (process.env.NODE_ENV === 'development') {
return <>This component is not shown in development</>;
}
const res = someExpensiveOperationThatLastsALongTime();
return <>{res}</>;
}
```
During Webpack build, the `process.env.NODE_ENV` will be replaced with the value, either `'development'` or `'production'`. You will then get different build results after dead code elimination:
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="Development">
```diff
import React from 'react';
export default function expensiveComp() {
// highlight-next-line
if ('development' === 'development') {
+ return <>This component is not shown in development</>;
}
- const res = someExpensiveOperationThatLastsALongTime();
- return <>{res}</>;
}
```
</TabItem>
<TabItem value="Production">
```diff
import React from 'react';
export default function expensiveComp() {
// highlight-next-line
- if ('production' === 'development') {
- return <>This component is not shown in development</>;
- }
+ const res = someExpensiveOperationThatLastsALongTime();
+ return <>{res}</>;
}
```
</TabItem>
</Tabs>
</details>
## Understanding SSR {#understanding-ssr}
React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs.
These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your site—anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading.
In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app.
## Escape hatches {#escape-hatches}
If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example:
- Our [live codeblock](../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor), which runs in the browser's JS runtime
- Our [themed image](../guides/markdown-features/markdown-features-assets.mdx#themed-images) that detects the user's color scheme to display different images
- The JSON viewer of our debug panel which uses the `window` global for styling
You may need to escape from SSR since static HTML can't display anything useful without knowing the client state.
:::caution
It is important for the first client-side render to produce the exact same DOM structure as server-side rendering, otherwise, React will correlate virtual DOM with the wrong DOM elements.
Therefore, the naïve attempt of `if (typeof window !== 'undefined) {/* render something */}` won't work appropriately as a browser vs. server detection, because the first client render would instantly render different markup from the server-generated one.
You can read more about this pitfall in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
:::
We provide several more reliable ways to escape SSR.
### `<BrowserOnly>` {#browseronly}
If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [`<BrowserOnly>`](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR.
```jsx
import BrowserOnly from '@docusaurus/BrowserOnly';
function MyComponent(props) {
return (
// highlight-start
<BrowserOnly fallback={<div>Loading...</div>}>
{() => {
const LibComponent =
require('some-lib-that-accesses-window').LibComponent;
return <LibComponent {...props} />;
}}
</BrowserOnly>
// highlight-end
);
}
```
It's important to realize that the children of `<BrowserOnly>` is not a JSX element, but a function that _returns_ an element. This is a design decision. Consider this code:
```jsx
import BrowserOnly from '@docusaurus/BrowserOnly';
function MyComponent() {
return (
<BrowserOnly>
{/* highlight-start */}
{/* DON'T DO THIS - doesn't actually work */}
<span>page url = {window.location.href}</span>
{/* highlight-end */}
</BrowserOnly>
);
}
```
While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed.
### `useIsBrowser` {#useisbrowser}
You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI.
```jsx
import useIsBrowser from '@docusaurus/useIsBrowser';
function MyComponent() {
const isBrowser = useIsBrowser();
const location = isBrowser ? window.location.href : 'fetching location...';
return <span>{location}</span>;
}
```
### `useEffect` {#useeffect}
Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state.
```jsx
function MyComponent() {
useEffect(() => {
// Only logged in the browser console; nothing is logged during server-side rendering
console.log("I'm now in the browser");
}, []);
return <span>Some content...</span>;
}
```
### `ExecutionEnvironment` {#executionenvironment}
The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment.
Beware that it essentially checked `typeof window !== 'undefined'` under the hood, so you should not use it for rendering-related logic, but only imperative code, like reacting to user input by sending web requests, or dynamically importing libraries, where DOM isn't updated at all.
```js title="a-client-module.js"
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
if (ExecutionEnvironment.canUseDOM) {
document.title = "I'm loaded!";
}
```

81
website/versioned_docs/version-2.0.0-beta.14/api/docusaurus.config.js.md → website/versioned_docs/version-2.0.0-beta.16/api/docusaurus.config.js.md
View file

@ -11,6 +11,41 @@ slug: /api/docusaurus-config
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
It usually exports a site configuration object:
```js title="docusaurus.config.js"
module.exports = {
// site config...
};
```
<details>
<summary>Config files also support config creator functions and async code.</summary>
```js title="docusaurus.config.js"
module.exports = function configCreator() {
return {
// site config...
};
};
```
```js title="docusaurus.config.js"
module.exports = async function configCreatorAsync() {
return {
// site config...
};
};
```
```js title="docusaurus.config.js"
module.exports = Promise.resolve({
// site config...
});
```
</details>
## Required fields {#required-fields}
### `title` {#title}
@ -41,7 +76,7 @@ module.exports = {
- Type: `string`
Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
```js title="docusaurus.config.js"
module.exports = {
@ -55,9 +90,7 @@ module.exports = {
- Type: `string | undefined`
Path to your site favicon
Example, if your favicon is in `static/img/favicon.ico`:
Path to your site favicon. For example, if your favicon is in `static/img/favicon.ico`:
```js title="docusaurus.config.js"
module.exports = {
@ -77,7 +110,7 @@ Allow to customize the presence/absence of a trailing slash at the end of URLs/l
:::tip
Each static hosting provider serve static files differently (this behavior may even change over time).
Each static hosting provider serves static files differently (this behavior may even change over time).
Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting.
@ -100,10 +133,12 @@ module.exports = {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
},
fr: {
label: 'Français',
direction: 'ltr',
htmlLang: 'fr-FR',
},
},
},
@ -112,6 +147,7 @@ module.exports = {
- `label`: the label to use for this locale
- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Arabic, Hebrew, etc.)
- `htmlLang`: BCP 47 language tag to use in `<html lang="...">` and in `<link ... hreflang="...">`
### `noIndex` {#noindex}
@ -243,6 +279,7 @@ Example:
module.exports = {
themeConfig: {
hideableSidebar: false,
autoCollapseSidebarCategories: false,
colorMode: {
defaultMode: 'light',
disableSwitch: false,
@ -306,33 +343,45 @@ module.exports = {
### `plugins` {#plugins}
<!-- TODO: configuration for plugins -->
- Type: `PluginConfig[]`
- Type: `any[]`
```ts
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
```
See [plugin method references](./plugin-methods/README.md) for the shape of a `PluginModule`.
```js title="docusaurus.config.js"
module.exports = {
plugins: [],
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};
```
### `themes` {#themes}
<!-- TODO: configuration for plugins -->
- Type: `any[]`
- Type: `PluginConfig[]`
```js title="docusaurus.config.js"
module.exports = {
themes: [],
themes: ['@docusaurus/theme-classic'],
};
```
### `presets` {#presets}
<!-- TODO: configuration for presets -->
- Type: `PresetConfig[]`
- Type: `any[]`
```ts
type PresetConfig = string | [string, any];
```
```js title="docusaurus.config.js"
module.exports = {
@ -355,7 +404,7 @@ module.exports = {
};
```
Attempting to add unknown field in the config will lead to error in build time:
Attempting to add unknown fields in the config will lead to errors during build time:
```bash
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
@ -513,7 +562,7 @@ module.exports = {
:::caution
This banner need to inline CSS / JS.
This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL.
If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it.

12
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/README.md → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/README.md
View file

@ -8,16 +8,16 @@ This section is a work in progress. Anchor links or even URLs are not guaranteed
Plugin APIs are shared by themes and plugins—themes are loaded just like plugins.
## Plugin module
## Plugin module {#plugin-module}
Every plugin is imported as a module. The module is expected to have the following members:
- A **default export**: the constructor function for the plugin.
- **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized.
## Plugin constructor
## Plugin constructor {#plugin-constructor}
The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin`.
The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>`.
### `context` {#context}
@ -37,17 +37,17 @@ interface LoadContext {
`options` are the [second optional parameter when the plugins are used](../../using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. If there's a [`validateOptions`](./static-methods.md#validateOptions) function exported, the `options` will be validated and normalized beforehand.
Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
Alternatively, if a preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to the individual plugin to define what options it takes.
## Example {#example}
Here's a mind model for a presumptuous plugin implementation.
Here's a mental model for a presumptuous plugin implementation.
```js
// A JavaScript function that returns an object.
// `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
// `opts` is the user-defined options.
function myPlugin(context, opts) {
async function myPlugin(context, opts) {
return {
// A compulsory field used as the namespace for directories to cache
// the intermediate data for each plugin.

0
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/_category_.yml → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/_category_.yml
View file

30
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/extend-infrastructure.md → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/extend-infrastructure.md
View file

@ -8,26 +8,30 @@ Docusaurus has some infrastructure like hot reloading, CLI, and swizzling, that
## `getPathsToWatch()` {#getPathsToWatch}
Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site. Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server.
Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site.
Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server.
Example:
```js {5-7} title="docusaurus-plugin/src/index.js"
```js title="docusaurus-plugin/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
getPathsToWatch() {
const contentPath = path.resolve(context.siteDir, options.path);
return [`${contentPath}/**/*.{ts,tsx}`];
},
// highlight-end
};
};
```
## `extendCli(cli)` {#extendCli}
Register an extra command to enhance the CLI of Docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander/v/5.1.0) object.
Register an extra command to enhance the CLI of Docusaurus. `cli` is a [commander](https://www.npmjs.com/package/commander/v/5.1.0) object.
:::caution
@ -37,10 +41,11 @@ The commander version matters! We use commander v5, and make sure you are referr
Example:
```js {4-11} title="docusaurus-plugin/src/index.js"
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
extendCli(cli) {
cli
.command('roll')
@ -49,32 +54,35 @@ module.exports = function (context, options) {
console.log(Math.floor(Math.random() * 1000 + 1));
});
},
// highlight-end
};
};
```
## `getThemePath()` {#getThemePath}
Returns the path to the directory where the theme components can be found. When your users calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
Returns the path to the directory where the theme components can be found. When your users call `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
For example, your `getThemePath` can be:
```js {6-8} title="my-theme/src/index.js"
```js title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'my-theme',
// highlight-start
getThemePath() {
return path.resolve(__dirname, './theme');
},
// highlight-end
};
};
```
## `getTypeScriptThemePath()` {#getTypeScriptThemePath}
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make path returned by `getThemePath()` be the compiled JavaScript output.
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement for `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make the path returned by `getThemePath()` be the compiled JavaScript output.
:::tip
@ -86,12 +94,13 @@ You should also format these files with Prettier. Remember—JS files can and wi
Example:
```js {6-13} title="my-theme/src/index.js"
```js title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
return {
name: 'my-theme',
// highlight-start
getThemePath() {
// Where compiled JavaScript output lives
return path.join(__dirname, '../lib/theme');
@ -100,6 +109,7 @@ module.exports = function (context, options) {
// Where TypeScript source code lives
return path.resolve(__dirname, '../src/theme');
},
// highlight-end
};
};
```
@ -108,9 +118,9 @@ module.exports = function (context, options) {
**This is a static method, not attached to any plugin instance.**
Returns a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all component are considered stable.
Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without `--danger`. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all components are considered stable.
```js {0-12} title="my-theme/src/index.js"
```js title="my-theme/src/index.js"
const swizzleAllowedComponents = [
'CodeBlock',
'DocSidebar',

2
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/i18n-lifecycles.md → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/i18n-lifecycles.md
View file

@ -103,7 +103,7 @@ module.exports = function (context, options) {
Themes using the `<Translate>` API can provide default code translation messages.
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site current locale.
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site's current locale.
Example:

41
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/lifecycle-apis.md → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/lifecycle-apis.md
View file

@ -5,7 +5,7 @@ toc_max_heading_level: 4
# Lifecycle APIs
During build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files.
During the build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files.
## `async loadContent()` {#loadContent}
@ -13,13 +13,15 @@ Plugins should use this lifecycle to fetch from data sources (filesystem, remote
For example, this plugin below return a random integer between 1 to 10 as content.
```js {5-6} title="docusaurus-plugin/src/index.js"
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
async loadContent() {
return 1 + Math.floor(Math.random() * 10);
},
// highlight-end
};
};
```
@ -63,9 +65,9 @@ type Module =
#### `createData(name: string, data: any): Promise<string>` {#createData}
A declarative callback to create static data (generally json or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
A declarative callback to create static data (generally JSON or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
```jsx title="website/src/components/Friends.js"
import React from 'react';
@ -75,10 +77,11 @@ export default function FriendsComponent({friends}) {
}
```
```js {4-23} title="docusaurus-friends-plugin/src/index.js"
```js title="docusaurus-friends-plugin/src/index.js"
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
// highlight-start
async contentLoaded({content, actions}) {
const {createData, addRoute} = actions;
// Create friends.json
@ -99,13 +102,14 @@ export default function friendsPlugin(context, options) {
exact: true,
});
},
// highlight-end
};
}
```
#### `setGlobalData(data: any): void`
#### `setGlobalData(data: any): void` {#setGlobalData}
This function permits to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout.
This function permits one to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout.
This data becomes accessible to your client-side/theme code through the [`useGlobalData`](../../docusaurus-core.md#useGlobalData) and [`usePluginData`](../../docusaurus-core.md#usePluginData) hooks.
@ -115,7 +119,7 @@ Global data is... global: its size affects the loading time of all pages of your
:::
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
```jsx title="website/src/components/Friends.js"
import React from 'react';
@ -127,10 +131,11 @@ export default function FriendsComponent() {
}
```
```js {4-14} title="docusaurus-friends-plugin/src/index.js"
```js title="docusaurus-friends-plugin/src/index.js"
export default function friendsPlugin(context, options) {
return {
name: 'docusaurus-friends-plugin',
// highlight-start
async contentLoaded({content, actions}) {
const {setGlobalData, addRoute} = actions;
// Create friends global data
@ -143,6 +148,7 @@ export default function friendsPlugin(context, options) {
exact: true,
});
},
// highlight-end
};
}
```
@ -174,7 +180,7 @@ The API of `configureWebpack` will be modified in the future to accept an object
You may use them to return your webpack configures conditionally.
For example, this plugin below modify the webpack config to transpile `.foo` file.
For example, this plugin below modify the webpack config to transpile `.foo` files.
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
@ -199,7 +205,7 @@ module.exports = function (context, options) {
};
```
### `content` {#content}
### `content` {#content-1}
`configureWebpack` will be called both with the content loaded by the plugin.
@ -275,21 +281,24 @@ interface Props {
postBodyTags: string;
routesPaths: string[];
plugins: Plugin<any>[];
content: Content;
}
```
Example:
```js {4-11} title="docusaurus-plugin/src/index.js"
```js title="docusaurus-plugin/src/index.js"
module.exports = function (context, options) {
return {
name: 'docusaurus-plugin',
// highlight-start
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// Print out to console all the rendered routes.
routesPaths.map((route) => {
console.log(route);
});
},
// highlight-end
};
};
```
@ -300,7 +309,7 @@ Inject head and/or body HTML tags to Docusaurus generated HTML.
`injectHtmlTags` will be called both with the content loaded by the plugin.
```typescript
```ts
function injectHtmlTags(): {
headTags?: HtmlTags;
preBodyTags?: HtmlTags;
@ -369,20 +378,22 @@ module.exports = function (context, options) {
## `getClientModules()` {#getClientModules}
Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.
Returns an array of paths to the modules that are to be imported into the client bundle. These modules are imported globally before React even renders the initial UI.
As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
```js {7-9} title="my-theme/src/index.js"
```js title="my-theme/src/index.js"
const path = require('path');
module.exports = function (context, options) {
const {customCss, customJs} = options || {};
return {
name: 'name-of-my-theme',
// highlight-start
getClientModules() {
return [customCss, customJs];
},
// highlight-end
};
};
```

22
website/versioned_docs/version-2.0.0-beta.14/api/plugin-methods/static-methods.md → website/versioned_docs/version-2.0.0-beta.16/api/plugin-methods/static-methods.md
View file

@ -8,7 +8,7 @@ Static methods are not part of the plugin instance—they are attached to the co
## `validateOptions({options, validate})` {#validateOptions}
Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during initialization.
Returns validated and normalized options for the plugin. This method is called before the plugin is initialized. You must return the options since they will be passed to the plugin during initialization.
### `options` {#options}
@ -16,7 +16,7 @@ Return validated and normalized options for the plugin. This method is called be
### `validate` {#validate}
`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config.
:::tip
@ -28,7 +28,7 @@ To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-vali
If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options and return options in case of success.
```js {8-11} title="my-plugin/src/index.js"
```js title="my-plugin/src/index.js"
function myPlugin(context, options) {
return {
name: 'docusaurus-plugin',
@ -36,17 +36,19 @@ function myPlugin(context, options) {
};
}
// highlight-start
myPlugin.validateOptions = ({options, validate}) => {
const validatedOptions = validate(myValidationSchema, options);
return validationOptions;
};
// highlight-end
module.exports = myPlugin;
```
In TypeScript, you can also choose to export this as a separate named export.
```ts {8-11} title="my-plugin/src/index.ts"
```ts title="my-plugin/src/index.ts"
export default function (context, options) {
return {
name: 'docusaurus-plugin',
@ -54,10 +56,12 @@ export default function (context, options) {
};
}
// highlight-start
export function validateOptions({options, validate}) {
const validatedOptions = validate(myValidationSchema, options);
return validationOptions;
}
// highlight-end
```
## `validateThemeConfig({themeConfig, validate})` {#validateThemeConfig}
@ -70,7 +74,7 @@ Return validated and normalized configuration for the theme.
### `validate` {#validate-1}
`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config.
:::tip
@ -82,7 +86,7 @@ To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-vali
If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options.
```js {8-11} title="my-theme/src/index.js"
```js title="my-theme/src/index.js"
function myPlugin(context, options) {
return {
name: 'docusaurus-plugin',
@ -90,17 +94,19 @@ function myPlugin(context, options) {
};
}
// highlight-start
myPlugin.validateThemeConfig = ({themeConfig, validate}) => {
const validatedThemeConfig = validate(myValidationSchema, options);
return validatedThemeConfig;
};
// highlight-end
module.exports = validateThemeConfig;
```
In TypeScript, you can also choose to export this as a separate named export.
```ts {8-11} title="my-theme/src/index.ts"
```ts title="my-theme/src/index.ts"
export default function (context, options) {
return {
name: 'docusaurus-plugin',
@ -108,8 +114,10 @@ export default function (context, options) {
};
}
// highlight-start
export function validateThemeConfig({themeConfig, validate}) {
const validatedThemeConfig = validate(myValidationSchema, options);
return validatedThemeConfig;
}
// highlight-end
```

0
website/versioned_docs/version-2.0.0-beta.14/api/plugins/_category_.yml → website/versioned_docs/version-2.0.0-beta.16/api/plugins/_category_.yml
View file

0
website/versioned_docs/version-2.0.0-beta.14/api/plugins/overview.md → website/versioned_docs/version-2.0.0-beta.16/api/plugins/overview.md
View file

98
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-client-redirects.md Normal file
View file

@ -0,0 +1,98 @@
---
sidebar_position: 4
id: plugin-client-redirects
title: '📦 plugin-client-redirects'
slug: '/api/plugins/@docusaurus/plugin-client-redirects'
---
import APITable from '@site/src/components/APITable';
Docusaurus Plugin to generate **client-side redirects**.
This plugin will write additional HTML pages to your static site that redirect the user to your existing Docusaurus pages with JavaScript.
:::caution production only
This plugin is always inactive in development and **only active in production** because it works on the build output.
:::
:::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}
Accepted fields:
<APITable>
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `fromExtensions` | `string[]` | `[]` | The extensions to be removed from the route after redirecting. |
| `toExtensions` | `string[]` | `[]` | The extensions to be appended to the route after redirecting. |
| `redirects` | `RedirectRule[]` | `[]` | The list of redirect rules. |
| `createRedirects` | `CreateRedirectsFn` | `undefined` | A callback to create a redirect rule. |
</APITable>
```ts
type RedirectRule = {
to: string;
from: string | string[];
};
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;
```
### Example configuration {#ex-config}
Here's an example configuration:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
// highlight-start
{
fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists)
redirects: [
// /docs/oldDoc -> /docs/newDoc
{
to: '/docs/newDoc',
from: '/docs/oldDoc',
},
// Redirect from multiple old paths to the new path
{
to: '/docs/newDoc2',
from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
},
],
createRedirects(existingPath) {
if (existingPath.includes('/community')) {
// Redirect from /docs/team/X to /community/X and /docs/support/X to /community/X
return [
existingPath.replace('/community', '/docs/team'),
existingPath.replace('/community', '/docs/support'),
];
}
return undefined; // Return a falsy value: no redirect created
},
},
// highlight-end
],
],
};
```

84
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-blog.md → website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-blog.md
View file

@ -9,6 +9,12 @@ import APITable from '@site/src/components/APITable';
Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
:::caution some features production only
The [feed feature](../../blog.mdx#feed) works by extracting the build output, and is **only active in production**.
:::
## Installation {#installation}
```bash npm2yarn
@ -40,7 +46,7 @@ Accepted fields:
| `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. |
| `tagsBasePath` | `string` | `'tags'` | URL route for the tags list page of your site. It is prepended to the `routeBasePath`. |
| `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. |
| `archiveBasePath` | <code>string \| null</code> | `'/archive'` | URL route for the archive blog section of your site. It is prepended to the `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to disable generation of archive. |
| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
| `postsPerPage` | <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. |
@ -48,6 +54,7 @@ Accepted fields:
| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. |
| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page |
| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. |
| `blogArchiveComponent` | `string` | `'@theme/BlogArchivePage'` | Root component of the blog archive page. |
| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
@ -66,7 +73,7 @@ Accepted fields:
</APITable>
```typescript
```ts
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
@ -94,27 +101,27 @@ type ReadingTimeFunctionOption = (params: {
type FeedType = 'rss' | 'atom' | 'json';
```
## Example configuration {#ex-config}
### Example configuration {#ex-config}
Here's an example configuration object.
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
Most Docusaurus users configure this plugin through the preset options.
:::
```js
```js config-tabs
// Preset Options: blog
// Plugin Options: @docusaurus/plugin-content-blog
const config = {
path: 'blog',
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Advanced use-case: functional editUrl
editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
},
editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
`https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
editLocalizedFiles: false,
blogTitle: 'Blog title',
blogDescription: 'Blog',
@ -149,51 +156,9 @@ const config = {
};
```
### Preset options {#ex-config-preset}
## Markdown front matter {#markdown-front-matter}
If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-start
blog: {
path: 'blog',
// ... configuration object here
},
// highlight-end
},
],
],
};
```
### Plugin options {#ex-config-plugin}
If you are using a standalone plugin, provide options directly to the plugin:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
// highlight-start
{
path: 'blog',
// ... configuration object here
},
// highlight-end
],
],
};
```
## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.
Accepted fields:
@ -201,7 +166,7 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. |
| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` front matter fields, even for single author blog posts. |
| `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. |
| `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
| `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. |
@ -220,7 +185,7 @@ Accepted fields:
</APITable>
```typescript
```ts
type Tag = string | {label: string; permalink: string};
// An author key references an author from the global plugin authors.yml file
@ -234,13 +199,13 @@ type Author = {
image_url?: string;
};
// The FrontMatter authors field allows various possible shapes
// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];
```
Example:
```yml
```md
---
title: Welcome Docusaurus v2
authors:
@ -255,6 +220,7 @@ description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
A Markdown blog post
```

105
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-docs.md → website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-docs.md
View file

@ -19,7 +19,7 @@ npm install --save @docusaurus/plugin-content-docs
If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
You can configure this plugin through the [preset options](#ex-config-preset).
You can configure this plugin through the preset options.
:::
@ -32,6 +32,7 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. |
| `breadcrumbs` | `boolean` | `true` | To enable or disable the breadcrumbs on docs pages. |
| `editUrl` | <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. |
@ -55,15 +56,15 @@ Accepted fields:
| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. |
| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. |
| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). |
| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory). <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. |
| `disableVersioning` | `boolean` | `false` | Explicitly disable versioning even with versions. This will make the site only include the current version. |
| `includeCurrentVersion` | `boolean` | `true` | Include the current version of your docs. |
| `lastVersion` | `string` | First version in `versions.json` | Set the version navigated to in priority and displayed by default for docs navbar items. |
| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. |
| `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |
</APITable>
```typescript
```ts
type EditUrlFunction = (params: {
version: string;
versionDocsDirPath: string;
@ -77,6 +78,12 @@ type PrefixParser = (filename: string) => {
numberPrefix?: number;
};
type CategoryIndexMatcher = (doc: {
fileName: string;
directories: string[];
extension: string;
}) => boolean;
type SidebarGenerator = (generatorArgs: {
item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"
version: {contentPath: string; versionName: string}; // the current version
@ -88,6 +95,8 @@ type SidebarGenerator = (generatorArgs: {
sidebarPosition?: number | undefined;
}>; // all the docs of that version (unfiltered)
numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
categoriesMetadata: Record<string, CategoryMetadata>; // key is the path relative to the doc directory, value is the category metadata file's content
isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override
defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
}) => Promise<SidebarItem[]>;
@ -103,21 +112,23 @@ type Versions = Record<
>;
```
## Example configuration {#ex-config}
### Example configuration {#ex-config}
Here's an example configuration object.
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
Most Docusaurus users configure this plugin through the preset options.
:::
```js
```js config-tabs
// Preset Options: docs
// Plugin Options: @docusaurus/plugin-content-docs
const config = {
path: 'docs',
breadcrumbs: true,
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Advanced use-case: functional editUrl
@ -134,12 +145,13 @@ const config = {
'**/__tests__/**',
],
sidebarPath: 'sidebars.js',
sidebarItemsGenerator: async function ({
async sidebarItemsGenerator({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
isCategoryIndex,
}) {
// Use the provided data to generate a custom sidebar slice
return [
@ -154,7 +166,7 @@ const config = {
},
];
},
numberPrefixParser: function (filename) {
numberPrefixParser(filename) {
// Implement your own logic to extract a potential number prefix
const numberPrefix = findNumberPrefix(filename);
// Prefix found: return it with the cleaned filename
@ -194,51 +206,9 @@ const config = {
};
```
### Preset options {#ex-config-preset}
## Markdown front matter {#markdown-front-matter}
If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-start
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.
Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.
Accepted fields:
@ -252,7 +222,7 @@ Accepted fields:
| `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 metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
| `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
| `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_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, 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. |
| `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
| `toc_max_heading_level` | `number` | `3` | The max heading level shown in the table of contents. Must be between 2 and 6. |
@ -268,13 +238,13 @@ Accepted fields:
</APITable>
```typescript
```ts
type Tag = string | {label: string; permalink: string};
```
Example:
```yml
```md
---
id: doc-markdown
title: Docs Markdown Features
@ -291,6 +261,7 @@ keywords:
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---
# Markdown Features
My Document Markdown content
@ -314,15 +285,15 @@ website/i18n/[locale]/docusaurus-plugin-content-docs
│
│ # translations for website/docs
├── current
│   ├── api
│   │   └── config.md
│   └── getting-started.md
│ ├── 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
│ ├── api
│ │ └── config.md
│ └── getting-started.md
└── version-1.0.0.json
```

57
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-content-pages.md → website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-content-pages.md
View file

@ -19,7 +19,7 @@ npm install --save @docusaurus/plugin-content-pages
If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
You can configure this plugin through the [preset options](#ex-config-preset).
You can configure this plugin through the preset options.
:::
@ -43,19 +43,20 @@ Accepted fields:
</APITable>
## Example configuration {#ex-config}
### Example configuration {#ex-config}
Here's an example configuration object.
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
Most Docusaurus users configure this plugin through the preset options.
:::
```js
```js config-tabs
// Preset Options: pages
// Plugin Options: @docusaurus/plugin-content-pages
const config = {
path: 'src/pages',
routeBasePath: '',
@ -74,48 +75,6 @@ const config = {
};
```
### 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.

102
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-debug.md Normal file
View file

@ -0,0 +1,102 @@
---
sidebar_position: 5
id: plugin-debug
title: '📦 plugin-debug'
slug: '/api/plugins/@docusaurus/plugin-debug'
---
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```
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.
:::info
If you use the plugin via the classic preset, the preset will **enable the plugin in development and disable it in production** by default (`debug: undefined`) to avoid exposing potentially sensitive information. You can use `debug: true` to always enable it or `debug: false` to always disable it.
If you use a standalone plugin, you may need to achieve the same effect by checking the environment:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
// highlight-next-line
process.env.NODE_ENV === 'production' && '@docusaurus/plugin-debug',
].filter(Boolean),
};
```
:::
:::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](/__docusaurus/debug).
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-debug
```
:::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.
:::
## Configuration {#configuration}
This plugin currently has no options.
### Example configuration {#ex-config}
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the preset options.
:::
<Tabs>
<TabItem value="Preset Options">
If you use a preset, configure this plugin through the [preset options](../../using-plugins.md#docusauruspreset-classic):
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-next-line
debug: true, // This will enable the plugin in production
},
],
],
};
```
</TabItem>
<TabItem value="Plugin Options">
If you are using a standalone plugin, provide options directly to the plugin:
```js title="docusaurus.config.js"
module.exports = {
// highlight-next-line
plugins: ['@docusaurus/plugin-debug'],
};
```
</TabItem>
</Tabs>

63
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-google-analytics.md Normal file
View file

@ -0,0 +1,63 @@
---
sidebar_position: 6
id: plugin-google-analytics
title: '📦 plugin-google-analytics'
slug: '/api/plugins/@docusaurus/plugin-google-analytics'
---
import APITable from '@site/src/components/APITable';
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.
:::caution production only
This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-google-analytics
```
:::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.
:::
## Configuration {#configuration}
Accepted fields:
<APITable>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trackingID` | `string` | **Required** | The tracking ID of your analytics service. |
| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
</APITable>
### Example configuration {#ex-config}
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the preset options.
:::
```js config-tabs
// Preset Options: googleAnalytics
// Plugin Options: @docusaurus/plugin-google-analytics
const config = {
trackingID: 'UA-141789564-1',
anonymizeIP: true,
};
```

69
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-google-gtag.md Normal file
View file

@ -0,0 +1,69 @@
---
sidebar_position: 7
id: plugin-google-gtag
title: '📦 plugin-google-gtag'
slug: '/api/plugins/@docusaurus/plugin-google-gtag'
---
import APITable from '@site/src/components/APITable';
The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
:::tip
You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if your gtag is set up correctly!
:::
:::caution production only
This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-google-gtag
```
:::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.
:::
## Configuration {#configuration}
Accepted fields:
<APITable>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trackingID` | `string` | **Required** | The tracking ID of your gtag service. |
| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
</APITable>
### Example configuration {#ex-config}
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the preset options.
:::
```js config-tabs
// Preset Options: gtag
// Plugin Options: @docusaurus/plugin-google-gtag
const config = {
trackingID: '141789564',
anonymizeIP: true,
};
```

79
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-ideal-image.md Normal file
View file

@ -0,0 +1,79 @@
---
sidebar_position: 8
id: plugin-ideal-image
title: '📦 plugin-ideal-image'
slug: '/api/plugins/@docusaurus/plugin-ideal-image'
---
import APITable from '@site/src/components/APITable';
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).
:::info
By default, the plugin is **inactive in development** so you could always view full-scale images. If you want to debug the ideal image behavior, you could set the [`disableInDev`](#disableInDev) option to `false`.
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @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')} />
```
## Configuration {#configuration}
Accepted fields:
<APITable>
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. |
| `sizes` | `number[]` | _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` | `number` | _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` | `number` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
| `max` | `number` | | See `min` above |
| `steps` | `number` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
| `quality` | `number` | `85` | JPEG compression quality |
| `disableInDev` | `boolean` | `true` | You can test ideal image behavior in dev mode by setting this to `false`. **Tip**: use [network throttling](https://www.browserstack.com/guide/how-to-perform-network-throttling-in-chrome) in your browser to simulate slow networks. |
</APITable>
### Example configuration {#ex-config}
Here's an example configuration:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-ideal-image',
// highlight-start
{
quality: 70,
max: 1030, // max resized image's size.
min: 640, // min resized image's size. if original is lower, use that size.
steps: 2, // the max number of images generated between min and max (inclusive)
disableInDev: false,
},
// highlight-end
],
],
};
```

0
website/versioned_docs/version-2.0.0-beta.14/api/plugins/plugin-pwa.md → website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-pwa.md
View file

74
website/versioned_docs/version-2.0.0-beta.16/api/plugins/plugin-sitemap.md Normal file
View file

@ -0,0 +1,74 @@
---
sidebar_position: 10
id: plugin-sitemap
title: '📦 plugin-sitemap'
slug: '/api/plugins/@docusaurus/plugin-sitemap'
---
import APITable from '@site/src/components/APITable';
This plugin creates sitemaps for your site so that search engine crawlers can crawl your site more accurately.
:::caution production only
This plugin is always inactive in development and **only active in production** because it works on the build output.
:::
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/plugin-sitemap
```
:::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:
<APITable>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `changefreq` | `string` | `'weekly'` | See [sitemap docs](https://www.sitemaps.org/protocol.html#xmlTagDefinitions) |
| `priority` | `number` | `0.5` | See [sitemap docs](https://www.sitemaps.org/protocol.html#xmlTagDefinitions) |
</APITable>
:::info
This plugin also respects some site config:
- [`noIndex`](../docusaurus.config.js.md#noindex): results in no sitemap generated
- [`trailingSlash`](../docusaurus.config.js.md#trailing-slash): determines if the URLs in the sitemap have trailing slashes
:::
### Example configuration {#ex-config}
You can configure this plugin through preset options or plugin options.
:::tip
Most Docusaurus users configure this plugin through the preset options.
:::
```js config-tabs
// Preset Options: sitemap
// Plugin Options: @docusaurus/plugin-sitemap
const config = {
changefreq: 'weekly',
priority: 0.5,
};
```
You can find your sitemap at `/sitemap.xml`.

0
website/versioned_docs/version-2.0.0-beta.14/api/themes/_category_.yml → website/versioned_docs/version-2.0.0-beta.16/api/themes/_category_.yml
View file

0
website/versioned_docs/version-2.0.0-beta.14/api/themes/overview.md → website/versioned_docs/version-2.0.0-beta.16/api/themes/overview.md
View file

0
website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-classic.md → website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-classic.md
View file

80
website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-configuration.md → website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-configuration.md
View file

@ -124,7 +124,7 @@ module.exports = {
### 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.
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 dismissible panel above the navbar. All configuration are in the `announcementBar` object.
Accepted fields:
@ -163,7 +163,7 @@ module.exports = {
Accepted fields:
<APITable name="navbar">
<APITable name="navbar-overview">
| Name | Type | Default | Description |
| --- | --- | --- | --- |
@ -325,6 +325,7 @@ 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)
- [Navbar doc sidebar](#navbar-doc-sidebar)
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).
@ -412,6 +413,71 @@ module.exports = {
};
```
#### Navbar linked to a sidebar {#navbar-doc-sidebar}
You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.
Accepted fields:
<APITable name="navbar-doc-sidebar">
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'docSidebar'` | **Required** | Sets the type of this navbar item to a sidebar's first document. |
| `sidebarId` | `string` | **Required** | The ID of the sidebar that this item is linked to. |
| `label` | `string` | First document link's sidebar label | 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 sidebar belongs to. |
</APITable>
:::tip
Use this navbar item type if your sidebar is updated often and the order is not stable.
:::
Example configuration:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'docSidebar',
position: 'left',
sidebarId: 'api',
label: 'API',
},
// highlight-end
],
},
},
};
```
```js title="sidebars.js"
module.exports = {
tutorial: [
{
type: 'autogenerated',
dirName: 'guides',
},
],
api: [
// highlight-next-line
'cli', // The navbar item will be linking to this doc
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
```
#### 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.
@ -839,20 +905,20 @@ module.exports = {
## Hooks {#hooks}
### `useThemeContext` {#usethemecontext}
### `useColorMode` {#use-color-mode}
React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
A React hook to access the color context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
import {useColorMode} from '@docusaurus/theme-common';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
const {isDarkTheme, setLightTheme, setDarkTheme} = useColorMode();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
@ -860,7 +926,7 @@ const Example = () => {
:::note
The component calling `useThemeContext` must be a child of the `Layout` component.
The component calling `useColorMode` must be a child of the `Layout` component.
```jsx
function ExamplePage() {

2
website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-live-codeblock.md → website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-live-codeblock.md
View file

@ -13,7 +13,7 @@ npm install --save @docusaurus/theme-live-codeblock
### Configuration {#configuration}
```jsx title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
plugins: ['@docusaurus/theme-live-codeblock'],
themeConfig: {

2
website/versioned_docs/version-2.0.0-beta.14/api/themes/theme-search-algolia.md → website/versioned_docs/version-2.0.0-beta.16/api/themes/theme-search-algolia.md
View file

@ -11,7 +11,7 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia
npm install --save @docusaurus/theme-search-algolia
```
This theme also adds search page available at `/search` (as swizzleable `SearchPage` component) path with OpenSearch support.
This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support. You can this default path via `themeConfig.algolia.searchPagePath`. Use `false` to disable search page.
:::tip

0
website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example-banner.png → website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example-banner.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 68 KiB

After

Width:  |  Height:  |  Size: 68 KiB

Before After
Before After

0
website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.docx → website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.docx
View file

0
website/versioned_docs/version-2.0.0-beta.14/assets/docusaurus-asset-example.xyz → website/versioned_docs/version-2.0.0-beta.16/assets/docusaurus-asset-example.xyz
View file

124
website/versioned_docs/version-2.0.0-beta.14/blog.mdx → website/versioned_docs/version-2.0.0-beta.16/blog.mdx
View file

@ -16,7 +16,7 @@ Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content
## Initial setup {#initial-setup}
To setup your site's blog, start by creating a `blog` directory.
To set up your site's blog, start by creating a `blog` directory.
Then, add an item link to your blog within `docusaurus.config.js`:
@ -41,7 +41,7 @@ To publish in the blog, create a Markdown file within the blog directory.
For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`:
```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md"
```md title="website/blog/2019-09-05-hello-docusaurus-v2.md"
---
title: Welcome Docusaurus v2
description: This is my first post on Docusaurus 2.
@ -59,6 +59,7 @@ tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
<!--truncate-->
@ -68,35 +69,7 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
```
:::note
Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
This naming convention is optional, and you can provide the date as FrontMatter.
<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).
The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
## Blog list {#blog-list}
@ -104,10 +77,11 @@ The blog's index page (by default, it is at `/blog`) is the _blog list page_, wh
Use the `<!--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
```md
---
title: Truncation Example
---
All these will be part of the blog post summary.
Even this.
@ -121,7 +95,7 @@ Not this.
Or this.
```
By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add meta description to the blog list page for better SEO:
By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add a meta description to the blog list page for better SEO:
```js title="docusaurus.config.js"
module.exports = {
@ -147,7 +121,7 @@ module.exports = {
The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed.
You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts":
You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may rather make it say "All posts":
```js title="docusaurus.config.js"
module.exports = {
@ -167,19 +141,61 @@ module.exports = {
};
```
## Blog post date {#blog-post-date}
Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
<details>
<summary>Example supported patterns</summary>
| Pattern | Example |
| --- | --- |
| Single file | `2021-05-28-my-blog-post-title.md` |
| MDX file | `2021-05-28-my-blog-post-title.mdx` |
| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` |
| Folder named by date | `2021-05-28/my-blog-post-title.md` |
| Nested folders by date | `2021/05/28/my-blog-post-title.md` |
| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` |
| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` |
| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` |
The date will be excised from the path and appended to the beginning of the URL slug.
</details>
:::tip
Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
:::
This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:
```md title="earlier-post.md"
---
date: 2021-09-13T10:00
---
```
```md title="later-post.md"
---
date: 2021-09-13T18:00
---
```
## Blog post authors {#blog-post-authors}
Use the `authors` FrontMatter field to declare blog post authors.
Use the `authors` front matter field to declare blog post authors.
### Inline authors {#inline-authors}
Blog post authors can be declared directly inside the FrontMatter:
Blog post authors can be declared directly inside the front matter:
````mdx-code-block
<Tabs groupId="author-frontmatter">
<Tabs groupId="author-front-matter">
<TabItem value="single" label="Single author">
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors:
name: Joel Marcey
@ -192,7 +208,7 @@ authors:
</TabItem>
<TabItem value="multiple" label="Multiple authors">
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors:
- name: Joel Marcey
@ -218,9 +234,9 @@ 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:
Prefer using the `authors` front matter, but the legacy `author_*` front matter remains supported:
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
@ -233,9 +249,9 @@ author_image_url: https://github.com/JoelMarcey.png
### Global authors {#global-authors}
For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post.
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:
It is possible to declare those authors globally in a configuration file:
```yml title="website/blog/authors.yml"
jmarcey:
@ -257,13 +273,13 @@ Use the `authorsMapPath` plugin option to configure the path. JSON is also suppo
:::
In blog posts FrontMatter, you can reference the authors declared in the global configuration file:
In blog posts front matter, you can reference the authors declared in the global configuration file:
````mdx-code-block
<Tabs groupId="author-frontmatter">
<Tabs groupId="author-front-matter">
<TabItem value="single" label="Single author">
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors: jmarcey
---
@ -272,7 +288,7 @@ authors: jmarcey
</TabItem>
<TabItem value="multiple" label="Multiple authors">
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors: [jmarcey, slorber]
---
@ -291,7 +307,7 @@ The `authors` system is very flexible and can suit more advanced use-case:
You can use global authors most of the time, and still use inline authors:
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors:
- jmarcey
@ -310,7 +326,7 @@ authors:
You can customize the global author's data on per-blog-post basis:
```yml title="my-blog-post.md"
```md title="my-blog-post.md"
---
authors:
- key: jmarcey
@ -335,6 +351,8 @@ website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
:::
An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See [this test post](/tests/blog/2022/01/20/image-only-authors) for the effect.
## Reading time {#reading-time}
Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.
@ -393,7 +411,7 @@ module.exports = {
Usage:
```yml "my-blog-post.md"
```md "my-blog-post.md"
---
hide_reading_time: true
---
@ -473,7 +491,7 @@ type BlogOptions = {
Example usage:
```js {8-11} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -481,10 +499,12 @@ module.exports = {
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
// highlight-end
},
},
],
@ -552,7 +572,7 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t
:::tip
There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborated explanation of `routeBasePath`.
There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborate explanation of `routeBasePath`.
:::

60
website/versioned_docs/version-2.0.0-beta.14/browser-support.md → website/versioned_docs/version-2.0.0-beta.16/browser-support.md
View file

@ -7,13 +7,34 @@ Docusaurus allows sites to define the list of supported browsers through a [brow
## 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.
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.
For example, you may use the [optional chaining syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining):
```js
const value = obj?.prop?.val;
```
...which unfortunately is only recognized by browser versions released after 2020. To be compatible with earlier browser versions, when building your site for production, our JS loader will transpile your code to a more verbose syntax:
```js
var _obj, _obj$prop;
const value =
(_obj = obj) === null || _obj === void 0
? void 0
: (_obj$prop = _obj.prop) === null || _obj$prop === void 0
? void 0
: _obj$prop.val;
```
However, this penalizes all other users with increased site load time because the 29-character line now becomes 168 characters—a 6-fold increase! (In practice, it will be better because the names used will be shorter.) As a tradeoff, the JS loader only transpiles the syntax to the degree that's supported by all 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.
On old browsers, the compiled output will use unsupported (too recent) JS syntax, causing React to fail to initialize and end up with a static website with only HTML/CSS and no JS.
:::
@ -21,10 +42,11 @@ On old browsers, the compiled output will use unsupported (too recent) JS syntax
Websites initialized with the default classic template has the following in `package.json`:
```json {4-11} title="package.json"
```json title="package.json"
{
"name": "docusaurus",
// ...
// highlight-start
"browserslist": {
"production": [">0.5%", "not dead", "not op_mini all"],
"development": [
@ -33,6 +55,7 @@ Websites initialized with the default classic template has the following in `pac
"last 1 safari version"
]
}
// highlight-end
// ...
}
```
@ -47,29 +70,34 @@ 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:
You can "evaluate" any config with the `browserslist` 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:
The output is all browsers supported in production. Below is the output in January 2022:
```text
and_chr 89
and_chr 96
and_uc 12.12
chrome 89
chrome 88
chrome 87
edge 89
edge 88
firefox 86
chrome 96
chrome 95
chrome 94
edge 96
firefox 95
firefox 94
ie 11
ios_saf 14.0-14.5
ios_saf 13.4-13.7
safari 14
ios_saf 15.2
ios_saf 15.0-15.1
ios_saf 14.5-14.8
ios_saf 14.0-14.4
ios_saf 12.2-12.5
opera 82
opera 81
safari 15.1
safari 14.1
safari 13.1
samsung 13.0
```
## Read more {#read-more}

56
website/versioned_docs/version-2.0.0-beta.14/cli.md → website/versioned_docs/version-2.0.0-beta.16/cli.md
View file

@ -39,7 +39,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
| --- | --- | --- |
| `--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). |
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a 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). |
@ -60,7 +60,7 @@ There are multiple ways to obtain a certificate. We will use [mkcert](https://gi
3. Start the app with Docusaurus HTTPS env variables:
```shell
```bash
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
```
@ -85,55 +85,37 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
:::
### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
### `docusaurus swizzle [themeName] [componentName] [siteDir]` {#docusaurus-swizzle}
```mdx-code-block
import SwizzleWarning from "./_partials/swizzleWarning.mdx"
<SwizzleWarning/>
```
Change any Docusaurus theme components to your liking with `npm run swizzle`.
[Swizzle](./swizzling.md) a theme component to customize it.
```bash npm2yarn
npm run swizzle [themeName] [componentName] [siteDir]
# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic DocSidebar
npm run swizzle @docusaurus/theme-classic Footer -- --eject
```
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.
The swizzle CLI is interactive and will guide you through the whole [swizzle process](./swizzling.md).
`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-swizzle}
#### 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
```
| Name | Description |
| --------------- | ---------------------------------------------------- |
| `themeName` | The name of the theme to swizzle from. |
| `componentName` | The name of the theme component to swizzle. |
| `--list` | Display components available for swizzling |
| `--eject` | [Eject](./swizzling.md#ejecting) the theme component |
| `--wrap` | [Wrap](./swizzling.md#wrapping) the theme component |
| `--danger` | Allow immediate swizzling of unsafe components |
| `--typescript` | Swizzle the TypeScript variant component |
:::caution
Unstable Components: components that have a higher risk of breaking changes due to internal refactorings.
Unsafe components 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.
@ -143,7 +125,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
| 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. |
| `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
@ -175,7 +157,7 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
| `--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 |
| `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings |
### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir}

63
website/versioned_docs/version-2.0.0-beta.14/configuration.md → website/versioned_docs/version-2.0.0-beta.16/configuration.md
View file

@ -5,9 +5,9 @@ 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.
Docusaurus has a unique take on configurations. We encourage you to congregate information about 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.
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors to 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}
@ -23,9 +23,9 @@ For exact reference to each of the configurable fields, you may refer to [**`doc
### Site metadata {#site-metadata}
Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl` and `favicon`.
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.
They are used in several 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}
@ -35,7 +35,7 @@ It is recommended to check the [deployment docs](deployment.mdx) for more inform
### 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:
List the [themes](./using-plugins.md#using-themes), [plugins](./using-plugins.md), and [presets](./using-plugins.md#using-presets) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
```js title="docusaurus.config.js"
module.exports = {
@ -50,7 +50,7 @@ module.exports = {
:::tip
Docusaurus supports **module shorthands**, allowing you to simplify the above configuration as:
Docusaurus supports [**module shorthands**](./using-plugins.md#module-shorthands), allowing you to simplify the above configuration as:
```js title="docusaurus.config.js"
module.exports = {
@ -60,51 +60,6 @@ module.exports = {
};
```
<details>
<summary>How are shorthands resolved?</summary>
When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:
- `[name]`
- `@docusaurus/[moduleType]-[name]`
- `docusaurus-[moduleType]-[name]`,
where `moduleType` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded.
If the name is scoped (beginning with `@`), the name is first split into scope and package name by the first slash:
```
@scope
^----^
scope (no name!)
@scope/awesome
^----^ ^-----^
scope name
@scope/awesome/main
^----^ ^----------^
scope name
```
If the name is not specified, `{scope}/docusaurus-{type}` is loaded. Otherwise, the following are attempted:
- `{scope}/{name}`
- `{scope}/docusaurus-{type}-{name}`
Below are some examples, for a plugin registered in the `plugins` field. Note that unlike [ESLint](https://eslint.org/docs/user-guide/configuring/plugins#configuring-plugins) or [Babel](https://babeljs.io/docs/en/options#name-normalization) where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.
| Declaration | May be resolved as |
| --- | --- |
| `awesome` | `docusaurus-plugin-awesome` |
| `sitemap` | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) |
| `@mycompany` | `@mycompany/docusaurus-plugin` (the only possible resolution!) |
| `@mycompany/awesome` | `@mycompany/docusaurus-plugin-awesome` |
| `@mycompany/awesome/web` | `@mycompany/docusaurus-plugin-awesome/web` |
</details>
:::
They can also be loaded from local directories:
@ -165,7 +120,7 @@ The `presets: [['classic', {...}]]` shorthand works as well.
:::
For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
For further help configuring themes, plugins, and presets, see [Using Plugins](./using-plugins.md).
### Custom configurations {#custom-configurations}
@ -215,7 +170,7 @@ If you just want to use those fields on the client side, you could create your o
## Customizing Babel Configuration {#customizing-babel-configuration}
For new Docusaurus projects, we automatically generated a `babel.config.js` in project root.
For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root.
```js title="babel.config.js"
module.exports = {
@ -223,4 +178,4 @@ module.exports = {
};
```
Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.
Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.

144
website/versioned_docs/version-2.0.0-beta.14/deployment.mdx → website/versioned_docs/version-2.0.0-beta.16/deployment.mdx
View file

@ -25,7 +25,7 @@ A Docusaurus site is statically rendered, and it can generally work without Java
## Configuration {#configuration}
The following parameters are required in `docusaurus.config.js` in order for Docusaurus to optimize routing and serve files from the correct location:
The following parameters are required in `docusaurus.config.js` to optimize routing and serve files from the correct location:
| Name | Description |
| --- | --- |
@ -34,7 +34,7 @@ The following parameters are required in `docusaurus.config.js` in order for Doc
## Testing your Build Locally {#testing-build-locally}
It is important to test your build locally before deploying to production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
It is important to test your build locally before deploying it for production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
```bash npm2yarn
npm run serve
@ -54,7 +54,38 @@ Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-gui
:::
## Choosing a hosting provider
## Using environment variables {#using-environment-variables}
Putting potentially sensitive information in the environment is common practice. However, in a typical Docusaurus website, the `docusaurus.config.js` file is the only interface to the Node.js environment (see [our architecture overview](advanced/architecture.md)), while everything else—MDX pages, React components... are client side and do not have direct access to the `process` global. In this case, you can consider using [`customFields`](api/docusaurus.config.js.md#customfields) to pass environment variables to the client side.
```js title="docusaurus.config.js"
// If you are using dotenv (https://www.npmjs.com/package/dotenv)
require('dotenv').config();
module.exports = {
title: '...',
url: process.env.URL, // You can use environment variables to control site specifics as well
// highlight-start
customFields: {
// Put your custom environment here
teamEmail: process.env.EMAIL,
},
// highlight-end
};
```
```jsx title="home.jsx"
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
export default function Home() {
const {
siteConfig: {customFields},
} = useDocusaurusContext();
return <div>Contact us through {customFields.teamEmail}!</div>;
}
```
## Choosing a hosting provider {#choosing-a-hosting-provider}
There are a few common hosting options:
@ -70,8 +101,8 @@ If you are unsure of which one to choose, ask the following questions:
How much resource (person-hours, money) am I willing to invest in this?
</summary>
- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services is almost never free, and setting up an on-site server and connecting it to the WAN can be more costly.
- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quota even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details.
- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services are almost never free, and setting up an on-site server and connecting it to the WAN can be even more costly.
- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quotas even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details.
- 🟡 The GitHub Pages deployment workflow can be tedious to set up. (Evidence: see the length of [Deploying to GitHub Pages](#deploying-to-github-pages)!) However, this service (including build and deployment) is always free for public repositories, and we have detailed instructions to help you make it work.
</details>
@ -124,10 +155,12 @@ For the same concern of up-to-datedness, we have stopped accepting PRs adding ne
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
```js {2-3} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// highlight-start
url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// highlight-end
// ...
};
```
@ -192,7 +225,7 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu
### Overview {#github-pages-overview}
Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively.
Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial, they will be referred to as **"source"** and **"deployment"**, respectively.
Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
@ -228,14 +261,16 @@ GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommen
Example:
```jsx {3-6} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
// highlight-start
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// highlight-end
// ...
};
```
@ -296,7 +331,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
Beginning in August 2021, GitHub requires every command-line sign-in to use the **personal access token** instead of the password. When GitHub prompts for your password, enter the PAT instead. See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for more information.
Alternatively, you can use SSH (`USE_SSH=true`) to login.
Alternatively, you can use SSH (`USE_SSH=true`) to log in.
:::
@ -309,7 +344,7 @@ The workflow examples below assume your website source resides in the `main` bra
Our goal is that:
1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new built output will be served on the GitHub Pages site. This job will be called `deploy`.
2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`.
Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below:
@ -320,7 +355,7 @@ Here are two approaches to deploying your docs with GitHub Actions. Based on the
<Tabs>
<TabItem value="same" label="Same">
While you can have both jobs defined in the same workflow file, the `deploy` job will always be listed as skipped in the PR check suite status. That's added noise providing no value to the review process, and as you cannot easily share common snippets, it is better to manage them as separate workflows instead.
While you can have both jobs defined in the same workflow file, the original `deploy` workflow will always be listed as skipped in the PR check suite status, which is not communicative of the actual status and provides no value to the review process. We therefore propose to manage them as separate workflows instead.
We will use a popular third-party deployment action: [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus).
@ -330,10 +365,12 @@ We will use a popular third-party deployment action: [peaceiris/actions-gh-pages
Add these two workflow files:
:::warning
:::warning Tweak the parameters for your setup
These files assume you are using yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
If your Docusaurus project is not at the root of the repo, you would need to change the paths as well.
:::
```yml title=".github/workflows/deploy.yml"
@ -341,8 +378,10 @@ name: Deploy to GitHub Pages
on:
push:
branches: [main]
paths: [website/**]
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
deploy:
@ -352,13 +391,13 @@ jobs:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: 14.x
node-version: 16.x
cache: yarn
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Build website
working-directory: website
run: |
yarn install --frozen-lockfile
yarn build
run: yarn build
# Popular action to deploy to GitHub Pages:
# Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
@ -367,8 +406,9 @@ jobs:
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# Build output to publish to the `gh-pages` branch:
publish_dir: ./website/build
# Assign commit authorship to the official GH-Actions bot for deploys to `gh-pages` branch:
publish_dir: ./build
# The following lines assign commit authorship to the official
# GH-Actions bot for deploys to `gh-pages` branch:
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# The GH actions bot is used by default if you didn't specify the two fields.
# You can swap them out with your own user credentials.
@ -381,8 +421,10 @@ name: Test deployment
on:
pull_request:
branches: [main]
paths: [website/**]
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
test-deploy:
@ -392,13 +434,13 @@ jobs:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: 14.x
node-version: 16.x
cache: yarn
- name: Test build
working-directory: website
run: |
yarn install --frozen-lockfile
yarn build
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
```
</details>
@ -444,12 +486,12 @@ jobs:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: 14.x
node-version: 16.x
cache: yarn
- name: Test deployment
run: |
yarn install --frozen-lockfile
yarn build
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
deploy:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
@ -571,10 +613,10 @@ steps:
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.
2. 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).
3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in our public key you just generated.
4. Open your Drone.io dashboard and login. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in the public key you just generated.
4. Open your Drone.io dashboard and log in. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
5. 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.
6. Create a `.drone.yml` on the root of your repository with below text.
6. Create a `.drone.yml` on the root of your repository with the below text.
```yml title=".drone.yml"
kind: pipeline
@ -600,13 +642,17 @@ trigger:
Now, whenever you push a new tag to GitHub, this trigger will start the drone CI job to publish your website.
## Deploying to Koyeb {#deploying-to-koyeb}
[Koyeb](https://www.koyeb.com) is a developer-friendly serverless platform to deploy apps globally. The platform lets you seamlessly run Docker containers, web apps, and APIs with git-based deployment, native autoscaling, a global edge network, and built-in service mesh and discovery. Check out the [Koyeb's Docusaurus deployment guide](https://www.koyeb.com/tutorials/deploy-docusaurus-on-koyeb) to get started.
## 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).
[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.
[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.
@ -637,13 +683,13 @@ That's it. Watch the status and wait till the app is deployed. To open the appli
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.
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).
Choose the project you want to deploy. It must contain the directory with the project's files (e.g. `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.
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.
@ -686,7 +732,7 @@ Deploy your app in a matter of seconds using surge with the following steps:
surge build/
```
First-time users of Surge would be prompted to create an account from the command line(happens only once).
First-time users of Surge would be prompted to create an account from the command line (which 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).
@ -695,10 +741,10 @@ Confirm that the site you want to publish is in the `build` directory, a randoml
If you have a domain name you can deploy your site using surge to your domain using the command:
```bash
surge build/ yourdomain.com
surge build/ your-domain.com
```
Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose.
Your site is now deployed for free at `subdomain.surge.sh` or `your-domain.com` depending on the method you chose.
### Setting up CNAME file {#setting-up-cname-file}
@ -724,3 +770,11 @@ You can deploy any other changes in the future with the command `surge`.
```
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.
## Deploying to Layer0 {#deploying-to-layer0}
[Layer0](https://www.layer0.co) is an all-in-one platform to develop, deploy, preview, experiment on, monitor, and run your headless frontend. It is focused on large, dynamic websites and best-in-class performance through EdgeJS (a JavaScript-based Content Delivery Network), predictive prefetching, and performance monitoring. Layer0 offers a free tier. Get started in just a few minutes by following [Layer0's guide to deploying Docusaurus](https://docs.layer0.co/guides/docusaurus).
## Deploying to Cloudflare Pages {#deploying-to-cloudflare-pages}
[Cloudflare Pages](https://pages.cloudflare.com/) is a Jamstack platform for frontend developers to collaborate and deploy websites. Get started within a few minutes by following [this article](https://dev.to/apidev234/deploying-docusaurus-to-cloudflare-pages-565g).

104
website/versioned_docs/version-2.0.0-beta.14/docusaurus-core.md → website/versioned_docs/version-2.0.0-beta.16/docusaurus-core.md
View file

@ -49,7 +49,7 @@ Docusaurus uses this component to catch errors within the theme's layout, and al
:::note
This component doesn't catch build-time errors, and only protects against client-side render errors that can happen when using stateful React components.
This component doesn't catch build-time errors and only protects against client-side render errors that can happen when using stateful React components.
:::
@ -63,33 +63,40 @@ This reusable React component will manage all of your changes to the document he
Usage Example:
```jsx {2,5,10}
```jsx
import React from 'react';
// highlight-next-line
import Head from '@docusaurus/Head';
const MySEO = () => (
// highlight-start
<Head>
<meta property="og:description" content="My custom description" />
<meta charSet="utf-8" />
<title>My Title</title>
<link rel="canonical" href="http://mysite.com/example" />
</Head>
// highlight-end
);
```
Nested or latter components will override duplicate usages:
```jsx {2,5,8,11}
```jsx
<Parent>
{/* highlight-start */}
<Head>
<title>My Title</title>
<meta name="description" content="Helmet application" />
</Head>
{/* highlight-end */}
<Child>
{/* highlight-start */}
<Head>
<title>Nested Title</title>
<meta name="description" content="Nested component" />
</Head>
{/* highlight-end */}
</Child>
</Parent>
```
@ -111,16 +118,19 @@ The component is a wrapper around react-router’s `<Link>` component that adds
External links also work, and automatically have these props: `target="_blank" rel="noopener noreferrer"`.
```jsx {2,7}
```jsx
import React from 'react';
// highlight-next-line
import Link from '@docusaurus/Link';
const Page = () => (
<div>
<p>
{/* highlight-next-line */}
Check out my <Link to="/blog">blog</Link>!
</p>
<p>
{/* highlight-next-line */}
Follow me on <Link to="https://twitter.com/docusaurus">Twitter</Link>!
</p>
</div>
@ -135,17 +145,25 @@ The target location to navigate to. Example: `/docs/introduction`.
<Link to="/courses" />
```
:::tip
Prefer this component to vanilla `<a>` tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use `<Link>`.
:::
### `<Redirect/>` {#redirect}
Rendering a `<Redirect>` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props.
Rendering a `<Redirect>` will navigate to a new location. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props.
Example usage:
```jsx {2,5}
```jsx
import React from 'react';
// highlight-next-line
import {Redirect} from '@docusaurus/router';
const Home = () => {
// highlight-next-line
return <Redirect to="/docs/test" />;
};
```
@ -158,11 +176,11 @@ const Home = () => {
### `<BrowserOnly/>` {#browseronly}
The `<BrowserOnly>` component permits to render React components only in the browser, after the React app has hydrated.
The `<BrowserOnly>` 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.
Use it for integrating with code that can't run in Node.js, because the `window` or `document` objects are being accessed.
:::
@ -249,20 +267,20 @@ export default function VisitMyWebsiteMessage() {
When [localizing your site](./i18n/i18n-introduction.md), the `<Translate/>` component will allow providing **translation support to React components**, such as your homepage. The `<Translate>` component supports [interpolation](#interpolate).
The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/[locale]`.
The translation strings will statically extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and a `code.json` translation file will be created in `website/i18n/[locale]`.
:::note
The `<Translate/>` props **must be hardcoded strings**.
Apart the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work.
Apart from 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
- `id`: optional value to be used as the key in JSON translation files
- `description`: optional text to help the translator
- `values`: optional object containing interpolation placeholder values
@ -302,7 +320,7 @@ export default function Home() {
:::note
You can even omit a children prop and specify a translation string in your `code.json` file manually after running the `docusaurus write-translations` CLI command.
You can even omit the children prop and specify a translation string in your `code.json` file manually after running the `docusaurus write-translations` CLI command.
```jsx
<Translate id="homepage.title" />
@ -314,7 +332,7 @@ You can even omit a children prop and specify a translation string in your `code
### `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.
React hook to access Docusaurus Context. The context contains the `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md) and some additional site metadata.
```ts
type DocusaurusPluginVersionInformation =
@ -352,22 +370,31 @@ interface DocusaurusContext {
Usage example:
```jsx {5,8-10}
```jsx
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const MyComponent = () => {
// highlight-next-line
const {siteConfig, siteMetadata} = useDocusaurusContext();
return (
<div>
{/* highlight-start */}
<h1>{siteConfig.title}</h1>
<div>{siteMetadata.siteVersion}</div>
<div>{siteMetadata.docusaurusVersion}</div>
{/* highlight-end */}
</div>
);
};
```
:::note
The `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side.
:::
### `useIsBrowser` {#useIsBrowser}
Returns `true` when the React app has successfully hydrated in the browser.
@ -376,9 +403,7 @@ Returns `true` when the React app has successfully hydrated in the browser.
Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic.
The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js).
Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
:::
@ -450,7 +475,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
- `withBaseUrl`: useful if you need to add base urls to multiple urls at once.
- `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once.
```jsx
import React from 'react';
@ -470,11 +495,11 @@ const Component = () => {
React hook to access Docusaurus global data created by all the plugins.
Global data is namespaced by plugin name, and plugin id.
Global data is namespaced by plugin name then by plugin ID.
:::info
Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
:::
@ -490,14 +515,17 @@ type GlobalData = Record<
Usage example:
```jsx {2,5-7}
```jsx
import React from 'react';
// highlight-next-line
import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const globalData = useGlobalData();
const myPluginData = globalData['my-plugin']['default'];
return <div>{myPluginData.someAttribute}</div>;
// highlight-end
};
```
@ -511,23 +539,26 @@ Inspect your site's global data at `./docusaurus/globalData.json`
Access global data created by a specific plugin instance.
This is the most convenient hook to access plugin global data, and should be used most of the time.
This is the most convenient hook to access plugin global data and should be used most of the time.
`pluginId` is optional if you don't use multi-instance plugins.
```ts
usePluginData(pluginName: string, pluginId?: string)
function usePluginData(pluginName: string, pluginId?: string);
```
Usage example:
```jsx {2,5-6}
```jsx
import React from 'react';
// highlight-next-line
import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const myPluginData = usePluginData('my-plugin');
return <div>{myPluginData.someAttribute}</div>;
// highlight-end
};
```
@ -541,14 +572,17 @@ useAllPluginInstancesData(pluginName: string)
Usage example:
```jsx {2,5-7}
```jsx
import React from 'react';
// highlight-next-line
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
const myPluginData = allPluginInstancesData['default'];
return <div>{myPluginData.someAttribute}</div>;
// highlight-end
};
```
@ -573,10 +607,9 @@ function interpolate(
#### Example {#example-1}
```jsx
// highlight-start
```js
// highlight-next-line
import {interpolate} from '@docusaurus/Interpolate';
// highlight-end
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});
```
@ -610,17 +643,14 @@ function translate(
import React from 'react';
import Layout from '@theme/Layout';
// highlight-start
// highlight-next-line
import {translate} from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout
// highlight-start
title={translate({message: 'My page meta title'})}
// highlight-end
>
// highlight-next-line
title={translate({message: 'My page meta title'})}>
<img
src={'https://docusaurus.io/logo.png'}
aria-label={
@ -646,7 +676,7 @@ export default function Home() {
### `ExecutionEnvironment` {#executionenvironment}
A module which exposes a few boolean variables to check the current rendering environment.
A module that exposes a few boolean variables to check the current rendering environment.
:::caution
@ -656,7 +686,7 @@ For React rendering logic, use [`useIsBrowser()`](#useIsBrowser) or [`<BrowserOn
Example:
```jsx
```js
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
if (ExecutionEnvironment.canUseDOM) {
@ -675,7 +705,7 @@ if (ExecutionEnvironment.canUseDOM) {
A module exposing useful constants to client-side theme code.
```jsx
```js
import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
```

35
website/versioned_docs/version-2.0.0-beta.14/guides/creating-pages.md → website/versioned_docs/version-2.0.0-beta.16/guides/creating-pages.md
View file

@ -7,7 +7,7 @@ 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.
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`.
@ -27,6 +27,8 @@ Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-con
## Add a React page {#add-a-react-page}
React is used as the UI library to create pages. Every page component should export a React component, and you can leverage the expressiveness of React to build rich and interactive content.
Create a file `/src/pages/helloReact.js`:
```jsx title="/src/pages/helloReact.js"
@ -55,7 +57,7 @@ function Hello() {
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.
Once you save the file, the development server will automatically reload the changes. Now open `http://localhost:3000/helloReact` and 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.
@ -83,7 +85,7 @@ 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.
Markdown pages are less flexible than React pages because it always uses the theme layout.
Here's an [example Markdown page](/examples/markdownPageExample).
@ -102,20 +104,31 @@ If you are familiar with other static site generators like Jekyll and Next, this
- `/src/pages/foo/test.js` → `[baseUrl]/foo/test`
- `/src/pages/foo/index.js` → `[baseUrl]/foo/`
In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:
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).
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.
```sh
:::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).
```bash
my-website
├── src
│ └── pages
│ ├── styles.module.css
│ ├── index.js
| ├──_ignored.js
│ ├── _ignored.js
│ ├── _ignored-folder
│ │ ├── Component1.js
│ │ └── Component2.js
│ └── support
│ ├── index.js
│ └── styles.module.css
@ -124,14 +137,10 @@ my-website
:::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).
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}
### 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.

18
website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-create-doc.mdx → website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-create-doc.mdx
View file

@ -10,16 +10,16 @@ Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
```bash
website # root directory of your site
├── docs
│   └── greeting.md
│ └── greeting.md
├── src
│   └── pages
│ └── 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
```md
---
id: greeting
title: Hello
@ -35,7 +35,7 @@ will show up on the table of contents on the upper right
So that your users will know what this page is all about without scrolling down or even without reading too much.
### Only h2 and h3 will be in the toc by default.
### Only h2 and h3 will be in the TOC by default.
You can configure the TOC heading levels either per-document or in the theme configuration.
@ -57,7 +57,7 @@ This will render in the browser as follows:
```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';
<BrowserWindow url="http://localhost:3000">
<BrowserWindow>
<h2>Hello from Docusaurus</h2>
@ -69,9 +69,9 @@ will show up on the table of contents on the upper right
So that your users will know what this page is all about without scrolling down or even without reading too much.
<h3>Only h2 and h3 will be in the toc by default.</h3>
<h3>Only h2 and h3 will be in the TOC by default.</h3>
You can configure the TOC heading levels either per-document or in the theme configuration.
You can configure the TOC heading levels either per document or in the theme configuration.
The headers are well-spaced so that the hierarchy is clear.
@ -98,9 +98,9 @@ Read more about [importing partial pages](../markdown-features/markdown-features
## Doc tags {#doc-tags}
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels:
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels:
```yml "your-doc-page.md"
```md "your-doc-page.md"
---
id: doc-with-tags
title: A doc with tags

20
website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-introduction.md → website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-introduction.md
View file

@ -27,22 +27,24 @@ website # Root directory of your site
└── hello.md
```
However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
```yml
```md
---
id: part1
---
Lorem ipsum
```
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
```yml
```md
---
id: part1
slug: part1.html
---
Lorem ipsum
```
@ -57,13 +59,14 @@ It is possible to use:
## Home page docs {#home-page-docs}
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter:
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
```yml
```md
---
id: my-home-doc
slug: /
---
Lorem ipsum
```
@ -83,7 +86,7 @@ example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-m
...
```
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root?
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting them at the root?
Assume that you have the following in your configuration:
@ -126,15 +129,16 @@ module.exports = {
};
```
Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
Note that you **don't necessarily have to give up on using the blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
Don't forget to put some page at the root (`https://example.com/`) through adding the front matter:
```yml title="docs/intro.md"
```md title="docs/intro.md"
---
# highlight-next-line
slug: /
---
This page will be the home page when users visit https://example.com/.
```

8
website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-markdown-features.mdx → website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-markdown-features.mdx
View file

@ -5,11 +5,11 @@ description: Docusaurus Markdown features that are specific to the docs plugin
slug: /docs-markdown-features
---
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional docs-specific Markdown features.
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features.
## Markdown frontmatter {#markdown-frontmatter}
## Markdown front matter {#markdown-front-matter}
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
## Referencing other documents {#referencing-other-documents}
@ -29,7 +29,7 @@ Reference to another [document in a subfolder](subfolder/doc3.md).
:::tip
It is better to use relative file paths links instead of relative links:
Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits:
- links will keep working on the GitHub interface
- you can customize the document slugs without having to update all the links

4
website/versioned_docs/version-2.0.0-beta.14/guides/docs/docs-multi-instance.mdx → website/versioned_docs/version-2.0.0-beta.16/guides/docs/docs-multi-instance.mdx
View file

@ -9,7 +9,7 @@ The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../
:::note
This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page.
This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar/multiple-sidebars.md), you can do so within one plugin.
:::
@ -26,7 +26,7 @@ If you build a cross-platform mobile SDK, you may have 2 documentations:
- Android SDK documentation (`v1.0`, `v1.1`)
- iOS SDK documentation (`v1.0`, `v2.0`)
In such case, you can use a distinct docs plugin instance per mobile SDK documentation.
In this case, you can use a distinct docs plugin instance per mobile SDK documentation.
:::caution

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