3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-17 19:16:58 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore(v2): prepare v2.0.0-beta.15 release (#6473)

Browse source
This commit is contained in:
Sébastien Lorber 2022-01-26 19:28:16 +01:00 • committed by GitHub
parent 24a895fbc5
commit d6cff8c754
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
142 changed files with 6704 additions and 4110 deletions
Download patch file Download diff file Expand all files Collapse all files

314
CHANGELOG.md
View file

@ -1,5 +1,319 @@
# Docusaurus 2 Changelog
## 2.0.0-beta.15 (2022-01-26)
#### :rocket: New Feature
- `docusaurus-plugin-content-docs`
- [#6451](https://github.com/facebook/docusaurus/pull/6451) feat(content-docs): expose isCategoryIndex matcher to customize conventions ([@Josh-Cena](https://github.com/Josh-Cena))
- [#5782](https://github.com/facebook/docusaurus/pull/5782) feat(content-docs): displayed_sidebar front matter ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`, `docusaurus-theme-common`
- [#6466](https://github.com/facebook/docusaurus/pull/6466) feat(theme-classic): add stable class for DocSidebarContainer ([@homotechsual](https://github.com/homotechsual))
- [#3811](https://github.com/facebook/docusaurus/pull/3811) feat(theme-classic): auto-collapse sibling categories in doc sidebar ([@josephriosIO](https://github.com/josephriosIO))
- [#6216](https://github.com/facebook/docusaurus/pull/6216) feat(theme-classic): usable CodeBlock outside markdown ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
- [#6416](https://github.com/facebook/docusaurus/pull/6416) feat(content-blog): allow authors list to contain images only ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`
- [#6415](https://github.com/facebook/docusaurus/pull/6415) feat(content-blog): allow disabling generating archive ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6245](https://github.com/facebook/docusaurus/pull/6245) feat(content-blog): parse date from middle of file path ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6388](https://github.com/facebook/docusaurus/pull/6388) feat(content-blog): include tags in feed ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus`
- [#6371](https://github.com/facebook/docusaurus/pull/6371) feat(core, theme-classic): allow overriding htmlLang ([@noomorph](https://github.com/noomorph))
- `docusaurus-mdx-loader`
- [#6323](https://github.com/facebook/docusaurus/pull/6323) feat(mdx-loader): preserve hash in image src; support GH themed images ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
- [#6139](https://github.com/facebook/docusaurus/pull/6139) feat(theme-classic): new navbar item linking to a sidebar ([@lmpham1](https://github.com/lmpham1))
- [#6239](https://github.com/facebook/docusaurus/pull/6239) feat(content-docs): allow SEO metadata for category index pages ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-sitemap`
- [#6248](https://github.com/facebook/docusaurus/pull/6248) feat(sitemap): remove trailingSlash option; respect noIndex config ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-ideal-image`, `docusaurus-theme-translations`
- [#6173](https://github.com/facebook/docusaurus/pull/6173) feat(ideal-image): allow translating status messages ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-ideal-image`
- [#6155](https://github.com/facebook/docusaurus/pull/6155) feat(ideal-image): new option disableInDev ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-translations`
- [#6169](https://github.com/facebook/docusaurus/pull/6169) feat(theme-translations): add Italian translations ([@mcallisto](https://github.com/mcallisto))
- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-types`, `docusaurus`
- [#6166](https://github.com/facebook/docusaurus/pull/6166) feat: async plugin creator functions ([@slorber](https://github.com/slorber))
- `docusaurus`
- [#6165](https://github.com/facebook/docusaurus/pull/6165) feat(core): async docusaurus.config.js creator function ([@slorber](https://github.com/slorber))
#### :boom: Breaking Change
- `docusaurus-theme-search-algolia`
- [#6407](https://github.com/facebook/docusaurus/pull/6407) feat(search): enable contextual search by default ([@slorber](https://github.com/slorber))
- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`
- [#6289](https://github.com/facebook/docusaurus/pull/6289) refactor: move @theme/hooks to @docusaurus/theme-common ([@slorber](https://github.com/slorber))
- `docusaurus-theme-classic`
- [#6283](https://github.com/facebook/docusaurus/pull/6283) refactor(theme-classic): apply import/no-named-export eslint rule ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-sitemap`
- [#6248](https://github.com/facebook/docusaurus/pull/6248) feat(sitemap): remove trailingSlash option; respect noIndex config ([@Josh-Cena](https://github.com/Josh-Cena))
#### :bug: Bug Fix
- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus`
- [#6454](https://github.com/facebook/docusaurus/pull/6454) fix(content-blog): generate feed by reading build output ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`
- [#6468](https://github.com/facebook/docusaurus/pull/6468) fix(init): cd to correct path when installing ([@gabrielcsapo](https://github.com/gabrielcsapo))
- `docusaurus-mdx-loader`
- [#4827](https://github.com/facebook/docusaurus/pull/4827) fix: allow links to JSON in .md files to be transformed as asset links ([@antmcc49](https://github.com/antmcc49))
- `docusaurus-plugin-content-docs`
- [#6435](https://github.com/facebook/docusaurus/pull/6435) fix(content-docs): make getActivePlugin match plugin paths more exactly ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6310](https://github.com/facebook/docusaurus/pull/6310) fix: highlight appropriate navItem when browsing generated category index ([@tapanchudasama](https://github.com/tapanchudasama))
- [#6202](https://github.com/facebook/docusaurus/pull/6202) fix(content-docs): quotify path when retrieving git history ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus`
- [#6424](https://github.com/facebook/docusaurus/pull/6424) fix(core): fix css url("image.png"), use css-loader v6 with esModules: false ([@slorber](https://github.com/slorber))
- [#6378](https://github.com/facebook/docusaurus/pull/6378) fix(core): do not coerce webpack warning to string ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6197](https://github.com/facebook/docusaurus/pull/6197) fix(cli): quotify temp path in deploy command ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6168](https://github.com/facebook/docusaurus/pull/6168) fix(core): update webpack-dev-server + fix deprecation warning ([@slorber](https://github.com/slorber))
- `docusaurus-logger`, `docusaurus-utils`
- [#6384](https://github.com/facebook/docusaurus/pull/6384) fix(logger): properly stringify objects for logging ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus`
- [#6338](https://github.com/facebook/docusaurus/pull/6338) fix(core): error boundary should allow no children ([@slorber](https://github.com/slorber))
- `docusaurus-theme-classic`
- [#6314](https://github.com/facebook/docusaurus/pull/6314) fix(theme-classic): fix mobile version dropdown label with only one version ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6288](https://github.com/facebook/docusaurus/pull/6288) fix(theme-classic): add missing role=region to SkipToContent ([@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg))
- [#6213](https://github.com/facebook/docusaurus/pull/6213) refactor(theme-classic): extract common PaginatorNavLink component ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6177](https://github.com/facebook/docusaurus/pull/6177) fix(theme-classic): make React elements in pre render correctly ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`
- [#6300](https://github.com/facebook/docusaurus/pull/6300) refactor: move exported type definitions to declaration file ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`
- [#6276](https://github.com/facebook/docusaurus/pull/6276) fix(migrate): migration CLI should correctly migrate gtag options ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`
- [#6244](https://github.com/facebook/docusaurus/pull/6244) fix(content-blog): always convert front matter date as UTC ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-utils`, `docusaurus`
- [#6190](https://github.com/facebook/docusaurus/pull/6190) fix(utils): properly escape Windows paths ([@Josh-Cena](https://github.com/Josh-Cena))
#### :nail_care: Polish
- `docusaurus-module-type-aliases`
- [#6469](https://github.com/facebook/docusaurus/pull/6469) fix(module-type-aliases): fix type def for translate params ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-search-algolia`
- [#6407](https://github.com/facebook/docusaurus/pull/6407) feat(search): enable contextual search by default ([@slorber](https://github.com/slorber))
- `docusaurus-mdx-loader`
- [#6443](https://github.com/facebook/docusaurus/pull/6443) refactor(mdx-loader): use vfile.path to access Markdown file path ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`
- [#6427](https://github.com/facebook/docusaurus/pull/6427) feat(theme-classic): add aria-current to sidebar category link ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6391](https://github.com/facebook/docusaurus/pull/6391) refactor(theme-classic): add comments to Prism setup; minor refactor ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6240](https://github.com/facebook/docusaurus/pull/6240) refactor(theme-classic): use front matter from metadata for BlogPostPage ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus`
- [#6419](https://github.com/facebook/docusaurus/pull/6419) feat(core): warn users about hand-modifying generated files ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6405](https://github.com/facebook/docusaurus/pull/6405) feat(core): check imported API name when extracting translations ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6291](https://github.com/facebook/docusaurus/pull/6291) feat(core): improve error message for BrowserOnly; better docs ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`
- [#5822](https://github.com/facebook/docusaurus/pull/5822) feat: update website & init template palette to pass WCAG test; include contrast check in ColorGenerator ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6368](https://github.com/facebook/docusaurus/pull/6368) fix(create-docusaurus): add useBaseUrl for image URLs ([@alias-mac](https://github.com/alias-mac))
- `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`
- [#6400](https://github.com/facebook/docusaurus/pull/6400) feat(content-pages): front matter validation, include front matter in metadata ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-theme-classic`
- [#6339](https://github.com/facebook/docusaurus/pull/6339) feat(mdx-loader): read image dimensions when processing Markdown ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-content-blog`
- [#6388](https://github.com/facebook/docusaurus/pull/6388) feat(content-blog): include tags in feed ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6189](https://github.com/facebook/docusaurus/pull/6189) feat(content-blog): include front matter in loaded content metadata ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-common`
- [#6317](https://github.com/facebook/docusaurus/pull/6317) feat(theme-classic): autoscroll TOC with active link ([@cerkiewny](https://github.com/cerkiewny))
- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
- [#6303](https://github.com/facebook/docusaurus/pull/6303) test(utils, mdx-loader, core): improve coverage ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-preset-classic`
- [#6284](https://github.com/facebook/docusaurus/pull/6284) fix(preset-classic): throw if preset finds GA options in theme config ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus`
- [#6186](https://github.com/facebook/docusaurus/pull/6186) refactor: print trailing new line when outputting JSON ([@Josh-Cena](https://github.com/Josh-Cena))
#### :memo: Documentation
- Other
- [#6296](https://github.com/facebook/docusaurus/pull/6296) docs: add advanced guides ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6459](https://github.com/facebook/docusaurus/pull/6459) docs: add replicad to showcase ([@sgenoud](https://github.com/sgenoud))
- [#6334](https://github.com/facebook/docusaurus/pull/6334) docs: 2021 recap blog post ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6458](https://github.com/facebook/docusaurus/pull/6458) docs: add Kuizuo's Personal Website to showcase ([@kuizuo](https://github.com/kuizuo))
- [#6431](https://github.com/facebook/docusaurus/pull/6431) docs: add Koyeb as a deployment option ([@edouardb](https://github.com/edouardb))
- [#6455](https://github.com/facebook/docusaurus/pull/6455) docs: add Sass Fairy to showcase ([@roydukkey](https://github.com/roydukkey))
- [#6453](https://github.com/facebook/docusaurus/pull/6453) docs: document embedding generated index in doc page ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6450](https://github.com/facebook/docusaurus/pull/6450) docs: split sidebar documentation into sections ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6449](https://github.com/facebook/docusaurus/pull/6449) docs: multiple doc improvements ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6448](https://github.com/facebook/docusaurus/pull/6448) fix(website): update colors correctly when palette is only customized in one color mode ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6385](https://github.com/facebook/docusaurus/pull/6385) chore: add height/width for front page images ([@nschonni](https://github.com/nschonni))
- [#6445](https://github.com/facebook/docusaurus/pull/6445) docs: update showcase data of InfraQL ([@jeffreyaven](https://github.com/jeffreyaven))
- [#6433](https://github.com/facebook/docusaurus/pull/6433) docs: add kube-green to showcase ([@davidebianchi](https://github.com/davidebianchi))
- [#6428](https://github.com/facebook/docusaurus/pull/6428) docs: elaborate on i18n tutorial ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6422](https://github.com/facebook/docusaurus/pull/6422) docs: add 404Lab wiki to showcase ([@HiChen404](https://github.com/HiChen404))
- [#6420](https://github.com/facebook/docusaurus/pull/6420) fix(website): restore some site CSS in light mode ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6410](https://github.com/facebook/docusaurus/pull/6410) docs: add SODA for SPARC to showcase ([@megasanjay](https://github.com/megasanjay))
- [#6417](https://github.com/facebook/docusaurus/pull/6417) docs: fix accessibility of search modal ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6406](https://github.com/facebook/docusaurus/pull/6406) docs(i18n): add docs for htmlLang config ([@noomorph](https://github.com/noomorph))
- [#6393](https://github.com/facebook/docusaurus/pull/6393) docs: update Algolia docs for new DocSearch infra ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6383](https://github.com/facebook/docusaurus/pull/6383) docs: elaborate on different CSS class names ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6348](https://github.com/facebook/docusaurus/pull/6348) docs: add KaustubhK24's site to showcase ([@kaustubhk24](https://github.com/kaustubhk24))
- [#6333](https://github.com/facebook/docusaurus/pull/6333) feat(website): search in showcase ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6344](https://github.com/facebook/docusaurus/pull/6344) fix(website): make ColorGenerator functional ([@shwaka](https://github.com/shwaka))
- [#6340](https://github.com/facebook/docusaurus/pull/6340) docs: minor fix in the sample config for ESM ([@pranabdas](https://github.com/pranabdas))
- [#6336](https://github.com/facebook/docusaurus/pull/6336) docs: make upgrade guide always show the latest version ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6320](https://github.com/facebook/docusaurus/pull/6320) chore: upgrade rehype-katex with ESM support, update docs ([@pranabdas](https://github.com/pranabdas))
- [#6335](https://github.com/facebook/docusaurus/pull/6335) docs: add Pglet website to showcase ([@FeodorFitsner](https://github.com/FeodorFitsner))
- [#6327](https://github.com/facebook/docusaurus/pull/6327) docs: remove typo bracket ([@MorookaKotaro](https://github.com/MorookaKotaro))
- [#6316](https://github.com/facebook/docusaurus/pull/6316) docs: add bandwidth.com to showcase ([@ajrice6713](https://github.com/ajrice6713))
- [#6313](https://github.com/facebook/docusaurus/pull/6313) docs: add Refine site to showcase ([@omeraplak](https://github.com/omeraplak))
- [#6318](https://github.com/facebook/docusaurus/pull/6318) fix(website): various anchor link fixes ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6308](https://github.com/facebook/docusaurus/pull/6308) fix(website): wrap details in mdx-code-block ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6307](https://github.com/facebook/docusaurus/pull/6307) docs: document MD and JSX interoperability issues ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6299](https://github.com/facebook/docusaurus/pull/6299) docs: add icodex to showcase ([@wood3n](https://github.com/wood3n))
- [#6297](https://github.com/facebook/docusaurus/pull/6297) docs: mention setup in monorepo ([@PatelN123](https://github.com/PatelN123))
- [#6293](https://github.com/facebook/docusaurus/pull/6293) docs: remove GraphQL mesh from showcase ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6231](https://github.com/facebook/docusaurus/pull/6231) docs: update showcase images; remove GraphQL Code Generator site ([@PatelN123](https://github.com/PatelN123))
- [#6285](https://github.com/facebook/docusaurus/pull/6285) refactor(website): further optimize showcase images ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6281](https://github.com/facebook/docusaurus/pull/6281) docs: Add kwatch to showcase ([@abahmed](https://github.com/abahmed))
- [#6280](https://github.com/facebook/docusaurus/pull/6280) docs: elaborate on doc versioning ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6043](https://github.com/facebook/docusaurus/pull/6043) fix(website): resize showcase images, tighten CI check ([@armano2](https://github.com/armano2))
- [#6274](https://github.com/facebook/docusaurus/pull/6274) docs: add dyte docs to showcase ([@vaibhavshn](https://github.com/vaibhavshn))
- [#6278](https://github.com/facebook/docusaurus/pull/6278) docs: add Khyron Realm to showcase ([@alexgrigoras](https://github.com/alexgrigoras))
- [#6271](https://github.com/facebook/docusaurus/pull/6271) docs: add FlatifyCSS to showcase ([@amir2mi](https://github.com/amir2mi))
- [#6275](https://github.com/facebook/docusaurus/pull/6275) fix(website): fix config-tabs breaking after translation ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6269](https://github.com/facebook/docusaurus/pull/6269) docs: add Ionic to showcase ([@ltm](https://github.com/ltm))
- [#6272](https://github.com/facebook/docusaurus/pull/6272) docs: make tsconfig work OOTB in typescript guide ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6265](https://github.com/facebook/docusaurus/pull/6265) docs: add Eric JiuRan's blog to showcase ([@1084350607](https://github.com/1084350607))
- [#6242](https://github.com/facebook/docusaurus/pull/6242) docs(showcase): update oxidizer website url ([@vandreleal](https://github.com/vandreleal))
- [#6226](https://github.com/facebook/docusaurus/pull/6226) docs: update showcase data for digital support notes ([@PatelN123](https://github.com/PatelN123))
- [#6224](https://github.com/facebook/docusaurus/pull/6224) docs: add TalentBrick to showcase ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6223](https://github.com/facebook/docusaurus/pull/6223) docs: normalize CodeBlock highlighting ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6214](https://github.com/facebook/docusaurus/pull/6214) feat(website): improve prism themes ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6215](https://github.com/facebook/docusaurus/pull/6215) docs: use BrowserWindow for Markdown demos ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6193](https://github.com/facebook/docusaurus/pull/6193) docs: normalize plugin API documentation ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6209](https://github.com/facebook/docusaurus/pull/6209) docs: elaborate on static asset resolution ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6207](https://github.com/facebook/docusaurus/pull/6207) docs: add default value for BrowserWindow URL field ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6206](https://github.com/facebook/docusaurus/pull/6206) docs: fix highlighting of YAML front matter ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6191](https://github.com/facebook/docusaurus/pull/6191) docs: fix react live scope button color in dark mode ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6188](https://github.com/facebook/docusaurus/pull/6188) docs: add Layer0 to deployment guide ([@rishi-raj-jain](https://github.com/rishi-raj-jain))
- [#6184](https://github.com/facebook/docusaurus/pull/6184) docs: remove mention of 'UA-' in gtag ([@johnnyreilly](https://github.com/johnnyreilly))
- [#6181](https://github.com/facebook/docusaurus/pull/6181) docs: add GTFS-to-HTML to showcase ([@brendannee](https://github.com/brendannee))
- [#6178](https://github.com/facebook/docusaurus/pull/6178) docs: add Digital Support Notes to showcase ([@PatelN123](https://github.com/PatelN123))
- [#6170](https://github.com/facebook/docusaurus/pull/6170) docs: add LabVIEW coding experience to showcase ([@ruanqizhen](https://github.com/ruanqizhen))
- [#6164](https://github.com/facebook/docusaurus/pull/6164) docs: fix import module name of theme/Admonition ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6158](https://github.com/facebook/docusaurus/pull/6158) docs: add Astronomer to showcase ([@jwitz](https://github.com/jwitz))
- `create-docusaurus`
- [#5822](https://github.com/facebook/docusaurus/pull/5822) feat: update website & init template palette to pass WCAG test; include contrast check in ColorGenerator ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6187](https://github.com/facebook/docusaurus/pull/6187) docs: make installation guide more beginner-friendly ([@PatelN123](https://github.com/PatelN123))
- `docusaurus-utils`
- [#6204](https://github.com/facebook/docusaurus/pull/6204) docs: recommend highlighting with comments than number range ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-theme-classic`
- [#6203](https://github.com/facebook/docusaurus/pull/6203) docs: audit grammar issues ([@Josh-Cena](https://github.com/Josh-Cena))
#### :house: Internal
- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
- [#6456](https://github.com/facebook/docusaurus/pull/6456) chore: add cSpell for spell checking ([@nschonni](https://github.com/nschonni))
- Other
- [#6444](https://github.com/facebook/docusaurus/pull/6444) misc: update nvmrc to 14.17.0 to meet dependency requirements ([@jodyheavener](https://github.com/jodyheavener))
- [#6441](https://github.com/facebook/docusaurus/pull/6441) misc: fix stylelint erroring when lint-staged passed ignored file ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6421](https://github.com/facebook/docusaurus/pull/6421) chore: fix yarn build:website:fast ([@slorber](https://github.com/slorber))
- [#6381](https://github.com/facebook/docusaurus/pull/6381) chore(website): set cache-control for static assets ([@nschonni](https://github.com/nschonni))
- [#6364](https://github.com/facebook/docusaurus/pull/6364) chore: remove Intl polyfills for Jest ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6325](https://github.com/facebook/docusaurus/pull/6325) chore: add Dependabot for dependency updates ([@nschonni](https://github.com/nschonni))
- [#6328](https://github.com/facebook/docusaurus/pull/6328) chore(ci): upgrade actions/github-script to v5 ([@nschonni](https://github.com/nschonni))
- [#6332](https://github.com/facebook/docusaurus/pull/6332) chore(deps): bump follow-redirects from 1.14.5 to 1.14.7 ([@dependabot[bot]](https://github.com/apps/dependabot))
- [#6326](https://github.com/facebook/docusaurus/pull/6326) misc(ci): remove redundant "CI: true" env ([@nschonni](https://github.com/nschonni))
- [#6304](https://github.com/facebook/docusaurus/pull/6304) chore: upgrade to Husky 7 ([@nschonni](https://github.com/nschonni))
- [#6222](https://github.com/facebook/docusaurus/pull/6222) test: ensure consistent CSS ordering ([@slorber](https://github.com/slorber))
- [#6159](https://github.com/facebook/docusaurus/pull/6159) docs: remove useless comment ([@slorber](https://github.com/slorber))
- [#6148](https://github.com/facebook/docusaurus/pull/6148) chore(examples): update examples to 2.0.0-beta.14 ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-debug`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus`
- [#6442](https://github.com/facebook/docusaurus/pull/6442) chore: enable stylelint standard config ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus`
- [#6440](https://github.com/facebook/docusaurus/pull/6440) chore: remove some unused dependencies from package.json ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`
- [#6436](https://github.com/facebook/docusaurus/pull/6436) refactor(theme-classic): render BlogPostItem as one JSX element ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6283](https://github.com/facebook/docusaurus/pull/6283) refactor(theme-classic): apply import/no-named-export eslint rule ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-content-pages`
- [#6413](https://github.com/facebook/docusaurus/pull/6413) fix(content-pages): declare hide_table_of_contents as boolean ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-migrate`, `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus`
- [#6399](https://github.com/facebook/docusaurus/pull/6399) refactor: clean up TODO comments ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-cssnano-preset`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-common`, `docusaurus-theme-translations`, `docusaurus`
- [#6387](https://github.com/facebook/docusaurus/pull/6387) test: improve test coverage ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-utils`
- [#6380](https://github.com/facebook/docusaurus/pull/6380) chore: enable a few fixable ESLint rules ([@nschonni](https://github.com/nschonni))
- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-utils`, `docusaurus`
- [#6377](https://github.com/facebook/docusaurus/pull/6377) refactor: use findAsyncSequential in a few places ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus`, `stylelint-copyright`
- [#6375](https://github.com/facebook/docusaurus/pull/6375) chore: enable eslint-plugin-jest ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`
- [#6373](https://github.com/facebook/docusaurus/pull/6373) chore: enable react/jsx-closing-bracket-location ([@nschonni](https://github.com/nschonni))
- `docusaurus-theme-classic`, `stylelint-copyright`
- [#6374](https://github.com/facebook/docusaurus/pull/6374) feat(stylelint-copyright): autofix, stricter config ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-cssnano-preset`, `docusaurus-theme-classic`
- [#6372](https://github.com/facebook/docusaurus/pull/6372) chore: add baseline stylelint rules ([@nschonni](https://github.com/nschonni))
- `create-docusaurus`, `docusaurus-plugin-debug`, `docusaurus-theme-classic`
- [#6369](https://github.com/facebook/docusaurus/pull/6369) chore: upgrade lint-staged and globs ([@nschonni](https://github.com/nschonni))
- `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus`
- [#6341](https://github.com/facebook/docusaurus/pull/6341) chore: regenerate yarn.lock ([@slorber](https://github.com/slorber))
- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-pages`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus`
- [#6324](https://github.com/facebook/docusaurus/pull/6324) chore: minor typo cleanup ([@nschonni](https://github.com/nschonni))
- `create-docusaurus`, `docusaurus-logger`, `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-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `lqip-loader`, `stylelint-copyright`
- [#6286](https://github.com/facebook/docusaurus/pull/6286) misc: convert all internal scripts to ESM ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`
- [#6289](https://github.com/facebook/docusaurus/pull/6289) refactor: move @theme/hooks to @docusaurus/theme-common ([@slorber](https://github.com/slorber))
- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`
- [#6287](https://github.com/facebook/docusaurus/pull/6287) refactor: new @docusaurus/plugin-content-docs/client interface ([@slorber](https://github.com/slorber))
- `docusaurus`
- [#6279](https://github.com/facebook/docusaurus/pull/6279) refactor(core): use native types from webpack-dev-server ([@RDIL](https://github.com/RDIL))
- `docusaurus-plugin-content-docs`
- [#6277](https://github.com/facebook/docusaurus/pull/6277) refactor(content-docs): make readVersionsMetadata async ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-types`, `docusaurus`
- [#6237](https://github.com/facebook/docusaurus/pull/6237) refactor(core): convert serverEntry.js to TS ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `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-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `lqip-loader`
- [#6230](https://github.com/facebook/docusaurus/pull/6230) refactor: enforce type import specifiers ([@Josh-Cena](https://github.com/Josh-Cena))
- `create-docusaurus`, `docusaurus-plugin-content-blog`, `docusaurus-utils`, `docusaurus`
- [#6229](https://github.com/facebook/docusaurus/pull/6229) refactor(utils): reorganize functions; move authors file resolution to utils ([@Josh-Cena](https://github.com/Josh-Cena))
- `docusaurus-theme-translations`
- [#6225](https://github.com/facebook/docusaurus/pull/6225) refactor(theme-translations): improve typing for update script ([@Josh-Cena](https://github.com/Josh-Cena))
- [#6174](https://github.com/facebook/docusaurus/pull/6174) misc(theme-translations): multiple improvements to the update CLI ([@Josh-Cena](https://github.com/Josh-Cena))
#### Committers: 46
- AJ Rice ([@ajrice6713](https://github.com/ajrice6713))
- Abdelrahman Ahmed ([@abahmed](https://github.com/abahmed))
- Alexandru Grigoras ([@alexgrigoras](https://github.com/alexgrigoras))
- Amir M. Mohamadi ([@amir2mi](https://github.com/amir2mi))
- Anthony McCaigue ([@antmcc49](https://github.com/antmcc49))
- Armano ([@armano2](https://github.com/armano2))
- Brendan Nee ([@brendannee](https://github.com/brendannee))
- Chen ([@HiChen404](https://github.com/HiChen404))
- Davide Bianchi ([@davidebianchi](https://github.com/davidebianchi))
- Devtato ([@cerkiewny](https://github.com/cerkiewny))
- Edouard Bonlieu ([@edouardb](https://github.com/edouardb))
- Feodor Fitsner ([@FeodorFitsner](https://github.com/FeodorFitsner))
- Filipe Guerra ([@alias-mac](https://github.com/alias-mac))
- Gabriel Csapo ([@gabrielcsapo](https://github.com/gabrielcsapo))
- Jake Witz ([@jwitz](https://github.com/jwitz))
- Jeffrey Aven ([@jeffreyaven](https://github.com/jeffreyaven))
- Jody Heavener ([@jodyheavener](https://github.com/jodyheavener))
- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly))
- Joseph ([@josephriosIO](https://github.com/josephriosIO))
- Josh Goldberg ([@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg))
- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
- Kaustubh Kulkarni ([@kaustubhk24](https://github.com/kaustubhk24))
- Lars Mikkelsen ([@ltm](https://github.com/ltm))
- Mikey O'Toole ([@homotechsual](https://github.com/homotechsual))
- Minh Pham ([@lmpham1](https://github.com/lmpham1))
- Morooka Kotaro ([@MorookaKotaro](https://github.com/MorookaKotaro))
- Nayan Patel ([@PatelN123](https://github.com/PatelN123))
- Nick Schonning ([@nschonni](https://github.com/nschonni))
- Pranab Das ([@pranabdas](https://github.com/pranabdas))
- Reece Dunham ([@RDIL](https://github.com/RDIL))
- Rishi Raj Jain ([@rishi-raj-jain](https://github.com/rishi-raj-jain))
- Sanjay Soundarajan ([@megasanjay](https://github.com/megasanjay))
- Shun Wakatsuki ([@shwaka](https://github.com/shwaka))
- Sébastien Lorber ([@slorber](https://github.com/slorber))
- Tapan Chudasama ([@tapanchudasama](https://github.com/tapanchudasama))
- Vaibhav Shinde ([@vaibhavshn](https://github.com/vaibhavshn))
- Vandré Leal ([@vandreleal](https://github.com/vandreleal))
- Yaroslav Serhieiev ([@noomorph](https://github.com/noomorph))
- [@mcallisto](https://github.com/mcallisto)
- [@ruanqizhen](https://github.com/ruanqizhen)
- [@wood3n](https://github.com/wood3n)
- kuizuo ([@kuizuo](https://github.com/kuizuo))
- sgenoud ([@sgenoud](https://github.com/sgenoud))
- trent ([@roydukkey](https://github.com/roydukkey))
- Ömer Faruk APLAK ([@omeraplak](https://github.com/omeraplak))
- 久染 | JiuRan ([@1084350607](https://github.com/1084350607))
## 2.0.0-beta.14 (2021-12-21)
#### :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.14",
"version": "2.0.0-beta.15",
"private": true,
"scripts": {
"start": "netlify dev"

2
lerna.json
View file

@ -1,5 +1,5 @@
{
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"description": "Create Docusaurus apps easily.",
"repository": {
"type": "git",
@ -21,7 +21,7 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.15",
"commander": "^5.1.0",
"fs-extra": "^10.0.0",
"lodash": "^4.17.20",

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.14",
"version": "2.0.0-beta.15",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -15,8 +15,8 @@
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/preset-classic": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@mdx-js/react": "^1.6.21",
"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.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@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.14",
"version": "2.0.0-beta.15",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -14,8 +14,8 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/preset-classic": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@mdx-js/react": "^1.6.21",
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/preset-classic": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@mdx-js/react": "^1.6.21",
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"description": "Docusaurus Loader for MDX",
"main": "lib/index.js",
"types": "src/mdx-loader.d.ts",
@ -20,8 +20,8 @@
"dependencies": {
"@babel/parser": "^7.16.4",
"@babel/traverse": "^7.16.3",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@mdx-js/mdx": "^1.6.21",
"escape-html": "^1.0.3",
"file-loader": "^6.2.0",
@ -36,7 +36,7 @@
"webpack": "^5.61.0"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.15",
"@types/escape-html": "^1.0.1",
"@types/mdast": "^3.0.7",
"@types/stringify-object": "^3.3.1",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/migrate",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"description": "A CLI tool to migrate from older versions of Docusaurus.",
"main": "lib/index.js",
"license": "MIT",
@ -24,7 +24,7 @@
},
"dependencies": {
"@babel/preset-env": "^7.16.4",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.15",
"@mapbox/hast-util-to-jsx": "^1.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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/types": "2.0.0-beta.15",
"@types/react": "*",
"@types/react-helmet": "*",
"@types/react-router-config": "*",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-client-redirects",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-common": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"eta": "^1.12.3",
"fs-extra": "^10.0.0",
"lodash": "^4.17.20",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/mdx-loader": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-common": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"cheerio": "^1.0.0-rc.10",
"feed": "^4.2.2",
"fs-extra": "^10.0.0",
@ -35,7 +35,7 @@
"webpack": "^5.61.0"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"description": "Docs plugin for Docusaurus.",
"main": "lib/index.js",
"exports": {
@ -22,11 +22,11 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/mdx-loader": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"combine-promises": "^1.1.0",
"fs-extra": "^10.0.0",
"import-fresh": "^3.2.2",
@ -39,8 +39,8 @@
"webpack": "^5.61.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@types/js-yaml": "^4.0.0",
"@types/picomatch": "^2.2.1",
"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.14",
"version": "2.0.0-beta.15",
"description": "Pages plugin for Docusaurus.",
"main": "lib/index.js",
"types": "src/plugin-content-pages.d.ts",
@ -18,10 +18,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/mdx-loader": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"fs-extra": "^10.0.0",
"globby": "^11.0.2",
"remark-admonitions": "^1.2.1",
@ -29,7 +29,7 @@
"webpack": "^5.61.0"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"fs-extra": "^10.0.0",
"react-json-view": "^1.21.3",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/lqip-loader": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/lqip-loader": "2.0.0-beta.15",
"@docusaurus/responsive-loader": "1.5.0",
"@docusaurus/theme-translations": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@docusaurus/theme-translations": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@endiliey/react-ideal-image": "^0.0.11",
"react-waypoint": "^10.1.0",
"sharp": "^0.29.1",
@ -33,8 +33,8 @@
"webpack": "^5.61.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"fs-extra": "^10.0.0"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-pwa",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"description": "Docusaurus Plugin to add PWA support.",
"main": "lib/index.js",
"types": "src/plugin-pwa.d.ts",
@ -23,11 +23,11 @@
"@babel/plugin-proposal-nullish-coalescing-operator": "^7.16.0",
"@babel/plugin-proposal-optional-chaining": "^7.16.0",
"@babel/preset-env": "^7.16.4",
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-translations": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"babel-loader": "^8.2.2",
"clsx": "^1.1.1",
"core-js": "^3.18.0",
@ -40,7 +40,7 @@
"workbox-window": "^6.1.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"fs-extra": "^10.0.0"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/plugin-sitemap",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-common": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"fs-extra": "^10.0.0",
"sitemap": "^7.0.0",
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/plugin-content-blog": "2.0.0-beta.14",
"@docusaurus/plugin-content-docs": "2.0.0-beta.14",
"@docusaurus/plugin-content-pages": "2.0.0-beta.14",
"@docusaurus/plugin-debug": "2.0.0-beta.14",
"@docusaurus/plugin-google-analytics": "2.0.0-beta.14",
"@docusaurus/plugin-google-gtag": "2.0.0-beta.14",
"@docusaurus/plugin-sitemap": "2.0.0-beta.14",
"@docusaurus/theme-classic": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-search-algolia": "2.0.0-beta.14"
"@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"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/plugin-content-blog": "2.0.0-beta.14",
"@docusaurus/plugin-content-docs": "2.0.0-beta.14",
"@docusaurus/plugin-content-pages": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-translations": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-common": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"@mdx-js/react": "^1.6.21",
"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.14",
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@types/mdx-js__react": "^1.5.4",
"@types/parse-numeric-range": "^0.0.1",
"@types/prismjs": "^1.16.2",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-common",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"description": "Common code for Docusaurus themes.",
"main": "./lib/index.js",
"types": "./lib/index.d.ts",
@ -18,18 +18,18 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/plugin-content-blog": "2.0.0-beta.14",
"@docusaurus/plugin-content-docs": "2.0.0-beta.14",
"@docusaurus/plugin-content-pages": "2.0.0-beta.14",
"@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",
"clsx": "^1.1.1",
"parse-numeric-range": "^1.3.0",
"tslib": "^2.3.1",
"utility-types": "^3.10.0"
},
"devDependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@testing-library/react-hooks": "^7.0.2",
"fs-extra": "^10.0.0",
"lodash": "^4.17.20"

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-live-codeblock",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"description": "Docusaurus live code block component.",
"main": "lib/index.js",
"publishConfig": {
@ -17,10 +17,10 @@
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-translations": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"@philpl/buble": "^0.19.7",
"clsx": "^1.1.1",
"fs-extra": "^10.0.0",
@ -30,7 +30,7 @@
"tslib": "^2.3.1"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.15",
"@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.14",
"version": "2.0.0-beta.15",
"description": "Algolia search component for Docusaurus.",
"main": "lib/index.js",
"exports": {
@ -25,12 +25,12 @@
},
"dependencies": {
"@docsearch/react": "^3.0.0-alpha.39",
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-translations": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@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",
"algoliasearch": "^4.10.5",
"algoliasearch-helper": "^3.5.5",
"clsx": "^1.1.1",
@ -40,7 +40,7 @@
"utility-types": "^3.10.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"fs-extra": "^10.0.0"
},
"peerDependencies": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/theme-translations",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"lodash": "^4.17.20"
},
"engines": {

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/types",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"version": "2.0.0-beta.15",
"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.14"
"@docusaurus/types": "2.0.0-beta.15"
},
"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.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"joi": "^17.4.2",
"tslib": "^2.3.1"
},

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/utils",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"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.14",
"@docusaurus/logger": "2.0.0-beta.15",
"@mdx-js/runtime": "^1.6.22",
"@svgr/webpack": "^6.0.0",
"file-loader": "^6.2.0",
@ -39,7 +39,7 @@
"node": ">=14"
},
"devDependencies": {
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.15",
"@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.14",
"version": "2.0.0-beta.15",
"license": "MIT",
"publishConfig": {
"access": "public"
@ -41,13 +41,13 @@
"@babel/runtime": "^7.16.3",
"@babel/runtime-corejs3": "^7.16.3",
"@babel/traverse": "^7.16.3",
"@docusaurus/cssnano-preset": "2.0.0-beta.14",
"@docusaurus/logger": "2.0.0-beta.14",
"@docusaurus/mdx-loader": "2.0.0-beta.14",
"@docusaurus/cssnano-preset": "2.0.0-beta.15",
"@docusaurus/logger": "2.0.0-beta.15",
"@docusaurus/mdx-loader": "2.0.0-beta.15",
"@docusaurus/react-loadable": "5.5.2",
"@docusaurus/utils": "2.0.0-beta.14",
"@docusaurus/utils-common": "2.0.0-beta.14",
"@docusaurus/utils-validation": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.15",
"@docusaurus/utils-common": "2.0.0-beta.15",
"@docusaurus/utils-validation": "2.0.0-beta.15",
"@slorber/static-site-generator-webpack-plugin": "^4.0.0",
"@svgr/webpack": "^6.0.0",
"autoprefixer": "^10.3.5",
@ -105,8 +105,8 @@
"webpackbar": "^5.0.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.14",
"@docusaurus/types": "2.0.0-beta.14",
"@docusaurus/module-type-aliases": "2.0.0-beta.15",
"@docusaurus/types": "2.0.0-beta.15",
"@types/copy-webpack-plugin": "^8.0.1",
"@types/detect-port": "^1.3.0",
"@types/mini-css-extract-plugin": "^1.4.3",

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

@ -1,6 +1,6 @@
{
"name": "@docusaurus/lqip-loader",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"description": "Low Quality Image Placeholders (LQIP) loader for webpack.",
"main": "lib/index.js",
"publishConfig": {

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

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

20
website/package.json
View file

@ -1,6 +1,6 @@
{
"name": "website",
"version": "2.0.0-beta.14",
"version": "2.0.0-beta.15",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -32,15 +32,15 @@
"dependencies": {
"@crowdin/cli": "^3.7.1",
"@crowdin/crowdin-api-client": "^1.10.6",
"@docusaurus/core": "2.0.0-beta.14",
"@docusaurus/plugin-client-redirects": "2.0.0-beta.14",
"@docusaurus/plugin-ideal-image": "2.0.0-beta.14",
"@docusaurus/plugin-pwa": "2.0.0-beta.14",
"@docusaurus/preset-classic": "2.0.0-beta.14",
"@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.14",
"@docusaurus/theme-common": "2.0.0-beta.14",
"@docusaurus/theme-live-codeblock": "2.0.0-beta.14",
"@docusaurus/utils": "2.0.0-beta.14",
"@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/theme-common": "2.0.0-beta.15",
"@docusaurus/theme-live-codeblock": "2.0.0-beta.15",
"@docusaurus/utils": "2.0.0-beta.15",
"@popperjs/core": "^2.10.2",
"clsx": "^1.1.1",
"color": "^4.0.1",

17
website/versioned_docs/version-2.0.0-beta.13/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.13/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.13/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.13/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.13/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.13/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.13/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,
},
],
],
};
```

86
website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-introduction.md
View file

@ -1,86 +0,0 @@
---
id: introduction
title: Docs Introduction
sidebar_label: Introduction
slug: /docs-introduction
---
The docs feature provides users with a way to organize Markdown files in a hierarchical format.
:::info
Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options.
:::
## Document ID {#document-id}
Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
```bash
website # Root directory of your site
└── docs
   ├── greeting.md
└── guide
└── hello.md
```
However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
```yml
---
id: part1
---
Lorem ipsum
```
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
```yml
---
id: part1
slug: part1.html
---
Lorem ipsum
```
:::note
It is possible to use:
- absolute slugs: `slug: /mySlug`, `slug: /`...
- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
:::
## Home page docs {#home-page-docs}
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter:
```yml
---
id: my-home-doc
slug: /
---
Lorem ipsum
```
## Docs-only mode {#docs-only-mode}
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more info](#home-page-docs)).
:::caution
You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
:::
:::tip
There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
:::

809
website/versioned_docs/version-2.0.0-beta.13/guides/docs/sidebar.md
View file

@ -1,809 +0,0 @@
---
id: sidebar
title: Sidebar
toc_max_heading_level: 5
slug: /sidebar
---
Creating a sidebar is useful to:
- Group multiple **related documents**
- **Display a sidebar** on each of those documents
- Provide a **paginated navigation**, with next/previous button
To use sidebars on your Docusaurus site:
1. Define a file that exports a [sidebar object](#sidebar-object).
1. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};
```
## Default sidebar
By default, Docusaurus [automatically generates a sidebar](#sidebar-item-autogenerated) for you, by using the filesystem structure of the `docs` folder:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/<version>)
},
],
};
```
You can also define your sidebars explicitly.
## Sidebar object {#sidebar-object}
A sidebar is a **tree of [sidebar items](#understanding-sidebar-items)**.
```typescript
type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| Record<
string, // category label
SidebarItem[] // category items
>;
```
A sidebars file can contain **multiple sidebar objects**.
```typescript
type SidebarsFile = Record<
string, // sidebar id
Sidebar
>;
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: ['doc1'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc2', 'doc3'],
},
],
};
```
Notice the following:
- There is a single sidebar `mySidebar`, containing 5 [sidebar items](#understanding-sidebar-items)
- `Getting Started` and `Docusaurus` are sidebar categories
- `doc1`, `doc2` and `doc3` are sidebar documents
:::tip
Use the **shorthand syntax** to express this sidebar more concisely:
```js title="sidebars.js"
module.exports = {
mySidebar: {
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};
```
:::
## Using multiple sidebars {#using-multiple-sidebars}
You can create a sidebar for each **set of Markdown files** that you want to **group together**.
:::tip
The Docusaurus site is a good example of using multiple sidebars:
- [Docs](../../introduction.md)
- [API](../../cli.md)
:::
Example:
```js title="sidebars.js"
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
```
:::note
The keys `tutorialSidebar` and `apiSidebar` are sidebar **technical ids** and do not matter much.
:::
When browsing:
- `doc1` or `doc2`: the `tutorialSidebar` will be displayed
- `doc3` or `doc4`: the `apiSidebar` will be displayed
A **paginated navigation** link documents inside the same sidebar with **next and previous buttons**.
## Understanding sidebar items {#understanding-sidebar-items}
`SidebarItem` is an item defined in a Sidebar tree.
There are different types of sidebar items:
- **[Doc](#sidebar-item-doc)**: link to a doc page, assigning it to the sidebar
- **[Ref](#sidebar-item-ref)**: link to a doc page, without assigning it to the sidebar
- **[Link](#sidebar-item-link)**: link to any internal or external page
- **[Category](#sidebar-item-category)**: create a hierarchy of sidebar items
- **[Autogenerated](#sidebar-item-autogenerated)**: generate a sidebar slice automatically
### Doc: link to a doc {#sidebar-item-doc}
Use the `doc` type to link to a doc page and assign that doc to a sidebar:
```typescript
type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
className?: string; // Class name for sidebar label
}
// Shorthand syntax
| string; // docId shortcut
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
// Normal syntax:
// highlight-start
{
type: 'doc',
id: 'doc1', // document id
label: 'Getting started', // sidebar label
},
// highlight-end
// Shorthand syntax:
// highlight-start
'doc2', // document id
// highlight-end
],
};
```
The `sidebar_label` markdown frontmatter has a higher precedence over the `label` key in `SidebarItemDoc`.
:::note
Don't assign the same doc to multiple sidebars: use a [ref](#sidebar-item-ref) instead.
:::
### Ref: link to a doc, without sidebar {#sidebar-item-ref}
Use the `ref` type to link to a doc page without assigning it to a sidebar.
```typescript
type SidebarItemRef = {
type: 'ref';
id: string;
};
```
Example:
```js title="sidebars.js"
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // Document id (string).
},
],
};
```
When browsing `doc1`, Docusaurus **will not display** the `mySidebar` sidebar.
### Link: link to any page {#sidebar-item-link}
Use the `link` type to link to any page (internal or external) that is not a doc.
```typescript
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
};
```
Example:
```js title="sidebars.js"
module.exports = {
myLinksSidebar: [
// highlight-start
// External link
{
type: 'link',
label: 'Facebook', // The link label
href: 'https://facebook.com', // The external URL
},
// highlight-end
// highlight-start
// Internal link
{
type: 'link',
label: 'Home', // The link label
href: '/', // The internal path
},
// highlight-end
],
};
```
### Category: create a hierarchy {#sidebar-item-category}
Use the `category` type to create a hierarchy of sidebar items.
```typescript
type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
className?: string;
// Category options:
collapsible: boolean; // Set the category to be collapsible
collapsed: boolean; // Set the category to be initially collapsed or open by default
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
```
Example:
```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
```
:::tip
Use the **shorthand syntax** when you don't need **category options**:
```js title="sidebars.js"
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
```
:::
#### Category links {#category-link}
With category links, clicking on a category can navigate you to another page.
:::tip
Use category links to introduce a category of documents.
:::
##### Doc link {#category-doc-link}
A category can link to an existing document.
```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
// highlight-start
link: {type: 'doc', id: 'introduction'},
// highlight-end
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
```
See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md).
##### Generated index page {#generated-index-page}
You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/{{category name}}`.
```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
// highlight-start
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description: 'Learn about the most important Docusaurus concepts!',
slug: '/category/docusaurus-guides',
},
// highlight-end
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
```
See it in action in the [Docusaurus Guides pages](/docs/category/guides).
:::tip
Use `generated-index` links as a quick way to get an introductory document.
:::
#### Collapsible categories {#collapsible-categories}
We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
// highlight-next-line
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
```
To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-docs` to `false`:
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarCollapsible: false,
},
},
],
],
};
```
:::note
The option in `sidebars.js` takes precedence over plugin configuration, so it is possible to make certain categories collapsible when `sidebarCollapsible` is set to `false` globally.
:::
#### Expanded categories by default {#expanded-categories-by-default}
Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`:
```js title="sidebars.js"
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
// highlight-next-line
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
```
Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration.
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarCollapsed: false,
},
},
],
],
};
```
:::caution
When a category has `collapsed: true` but `collapsible: false` (either through `sidebars.js` or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.
:::
### Autogenerated: generate a sidebar {#sidebar-item-autogenerated}
Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category.
An `autogenerated` item is converted by Docusaurus to a **sidebar slice**: a list of items of type `doc` and `category`.
```typescript
type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};
```
Docusaurus can generate a sidebar from your docs folder:
```js title="sidebars.js"
module.exports = {
myAutogeneratedSidebar: [
// highlight-start
{
type: 'autogenerated',
dirName: '.', // '.' means the current docs folder
},
// highlight-end
],
};
```
You can also use **multiple `autogenerated` items** in a sidebar, and interleave them with regular sidebar items:
```js title="sidebars.js"
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Tutorials',
items: [
'tutorial-intro',
// highlight-start
{
type: 'autogenerated',
dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
},
// highlight-end
'tutorial-medium',
// highlight-start
{
type: 'autogenerated',
dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard
},
// highlight-end
'tutorial-end',
],
},
// highlight-start
{
type: 'autogenerated',
dirName: 'guides', // Generate sidebar slice from docs/guides
},
// highlight-end
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};
```
#### Category index convention {#category-index-convention}
Docusaurus can automatically link a category to its index document.
A category index document is a document following one of those filename conventions:
- Named as `index` (case-insensitive): `docs/Guides/index.md`
- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
- Same name as parent folder: `docs/Guides/Guides.md`
This is equivalent to using a category with a [doc link](#category-doc-link):
```js title="sidebars.js"
module.exports = {
docs: [
// highlight-start
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'Guides/index'},
items: [],
},
// highlight-end
],
};
```
:::tip
Naming your introductory document `README.md` makes it show up when browsing the folder using the GitHub interface, while using `index.md` makes the behavior more in line with how HTML files are served.
:::
#### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names).
If the generated sidebar does not look good, you can assign additional metadata to docs and categories.
**For docs**: use additional front matter:
```md title="docs/tutorials/tutorial-easy.md" {1-4}
---
sidebar_label: Easy
sidebar_position: 2
---
# Easy Tutorial
This is the easy tutorial!
```
**For categories**: add a `_category_.json` or `_category_.yml` file in the appropriate folder:
```json title="docs/tutorials/_category_.json"
{
"label": "Tutorial",
"position": 3,
"className": "red",
"link": {
"type": "generated-index",
"title": "Tutorial overview"
}
}
```
:::info
If the `link` is explicitly specified, Docusaurus will not apply any [default conventions](#category-index-convention).
The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist.
:::
```yaml title="docs/tutorials/_category_.yml"
label: 'Tutorial'
position: 2.5 # float position is supported
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
```
:::info
The position metadata is only used **inside a sidebar slice**: Docusaurus does not re-order other items of your sidebar.
:::
#### Using number prefixes
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes:
```bash
docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Hard
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md
```
To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**.
By default, Docusaurus will **remove the number prefix** from the doc id, title, label and URL paths.
:::caution
**Prefer using [additional metadata](#autogenerated-sidebar-metadata)**.
Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**:
```diff title="docs/02-Tutorial Easy/01-First Part.md"
- Check the [Tutorial End](../04-End.md);
+ Check the [Tutorial End](../05-End.md);
```
:::
#### Customize the sidebar items generator
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
}) {
// Example: return an hardcoded list of static sidebar items
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
// highlight-end
},
],
],
};
```
:::tip
**Re-use and enhance the default generator** instead of writing a generator from scratch.
**Add, update, filter, re-order** the sidebar items according to your use-case:
```js title="docusaurus.config.js"
// highlight-start
// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
// Reverse items in categories
const result = items.map((item) => {
if (item.type === 'category') {
return {...item, items: reverseSidebarItems(item.items)};
}
return item;
});
// Reverse items at current level
result.reverse();
return result;
}
// highlight-end
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// highlight-start
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
...args
}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
// highlight-end
},
],
],
};
```
:::
## Hideable sidebar {#hideable-sidebar}
Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-start
hideableSidebar: true,
// highlight-end
},
};
```
## Passing custom props {#passing-custom-props}
To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
```js
{
type: 'doc',
id: 'doc1',
customProps: {
/* props */
}
}
```
## Complex sidebars example {#complex-sidebars-example}
Real-world example from the Docusaurus site:
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
<CodeBlock className="language-js" title="sidebars.js">
{require('!!raw-loader!@site/sidebars.js')
.default
.split('\n')
// remove comments
.map((line) => !['#','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
.filter(Boolean)
.join('\n')}
</CodeBlock>
```

216
website/versioned_docs/version-2.0.0-beta.13/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-<version>/` folder.
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`.
## Docs {#docs}
### Creating new docs {#creating-new-docs}
1. Place the new file into the corresponding version folder.
1. Include the reference for the new file into the corresponding sidebar file, according to version number.
**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)
```

123
website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -1,123 +0,0 @@
---
id: admonitions
title: Admonitions
description: Handling admonitions/callouts in Docusaurus Markdown
slug: /markdown-features/admonitions
---
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.
Example:
:::note
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::tip
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::info
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::caution
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::note
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::tip
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::info
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::caution
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
## Specifying title {#specifying-title}
You may also specify an optional title
:::note Your Title
Some **content** with _markdown_ `syntax`.
:::
:::note Your Title
Some **content** with _markdown_ `syntax`.
:::
## Admonitions with MDX
You can use MDX inside admonitions too!
```jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::tip Use tabs in admonitions
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
</Tabs>
:::
```
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```
:::tip Use tabs in admonitions
```mdx-code-block
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
</Tabs>
```
:::

116
website/versioned_docs/version-2.0.0-beta.13/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.13/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.13/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.13/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.13/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.

209
website/versioned_docs/version-2.0.0-beta.13/using-plugins.md
View file

@ -1,209 +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, containing plugin [lifecycle APIs](./api/plugin-methods/README.md).
It can be defined as a function or a module.
### Functional definition {#functional-definition}
You can use a plugin as a function, directly 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, loading it from 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 */
};
};
```
#### `context` {#context}
`context` is plugin-agnostic, and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields:
```ts
interface LoadContext {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
}
```
#### `options` {#options}
`options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
#### Return value {#return-value}
The returned object value should implement the [lifecycle APIs](./api/plugin-methods/README.md).

247
website/versioned_docs/version-2.0.0-beta.13/using-themes.md
View file

@ -1,247 +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.
## 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.
1. A Docusaurus theme packages's `theme` directory.
1. Fallback components provided by Docusaurus core (usually not needed).
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.
**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, so it makes it easy to swap out the themes for other designs.
For example, a Docusaurus blog consists of a blog plugin and a blog theme.
```js title="docusaurus.config.js"
{
theme: ['theme-blog'],
plugins: ['plugin-content-blog'],
}
```
And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme):
```js title="docusaurus.config.js"
{
theme: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
}
```
## 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.
:::
## 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`.
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>
## 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)

0
website/versioned_docs/version-2.0.0-beta.13/_partials/swizzleWarning.mdx → website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx
View file

28
website/versioned_docs/version-2.0.0-beta.15/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.

12
website/versioned_docs/version-2.0.0-beta.15/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.15/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
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
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`.

277
website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md Normal file
View file

@ -0,0 +1,277 @@
---
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
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 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
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
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
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 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
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
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
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.15/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
React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs.
These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your site—anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading.
In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app.
## Escape hatches
If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example:
- Our [live codeblock](../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor), which runs in the browser's JS runtime
- Our [themed image](../guides/markdown-features/markdown-features-assets.mdx#themed-images) that detects the user's color scheme to display different images
- The JSON viewer of our debug panel which uses the `window` global for styling
You may need to escape from SSR since static HTML can't display anything useful without knowing the client state.
:::caution
It is important for the first client-side render to produce the exact same DOM structure as server-side rendering, otherwise, React will correlate virtual DOM with the wrong DOM elements.
Therefore, the naïve attempt of `if (typeof window !== 'undefined) {/* render something */}` won't work appropriately as a browser vs. server detection, because the first client render would instantly render different markup from the server-generated one.
You can read more about this pitfall in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
:::
We provide several more reliable ways to escape SSR.
### `<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`
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`
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`
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!";
}
```

195
website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md Normal file
View file

@ -0,0 +1,195 @@
---
description: Customize your site's appearance through creating your own theme components
---
# Swizzling
In this section, we will introduce how customization of layout is done in Docusaurus.
> Déja vu...?
This section is similar to [Styling and Layout](../styling-layout.md), but this time, we are going to write more code and go deeper into the internals instead of playing with stylesheets. We will talk about a central concept in Docusaurus customization: **swizzling**, from how to swizzle, to how it works under the hood.
We know you are busy, so we will start with the "how" before going into the "why".
## Swizzling
```mdx-code-block
import SwizzleWarning from "../_partials/swizzleWarning.mdx"
<SwizzleWarning/>
```
Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, 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 gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`.
### Ejecting theme components
To eject a component provided by the 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 Docusaurus to an `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use the swizzled component in place of the original one from the theme.
:::note
You need to restart your webpack dev server in order for Docusaurus to know about the new component.
:::
If you run `swizzle` without `component name` or `theme name`, the command will give you a list to choose from. To only list available components, run with the `--list` option:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic --list
```
"Swizzle" is a central concept in Docusaurus, and is a natural product of our [layered theme architecture](#theme-aliases). Note that the command `docusaurus swizzle` is only an automated way to help you swizzle the component: you can still do it manually by creating the `src/theme/Footer.js` file, and Docusaurus will pick that one up when resolving theme components. There's no internal magic behind this command!
### Wrapping theme components {#wrapping-theme-components}
Ejecting a component is risky. It means you have to maintain an almost duplicate copy of the original theme component. Also, it's likely that we will change internal implementations in future versions and break your component, even if you never touched that part of the code.
Very often, you don't need to re-implement a component from scratch, but only to render additional items before or after it, or conditionally call some other logic. In this case, you are still going to swizzle the component—but not making a self-sustained one. Instead, you can delegate most of the logic and layout to the original theme component. The `@theme-original` alias allows you to import the original theme component and wrap it as a higher-order component.
Here is an example to display some text just above the footer, with minimal code duplication.
```js title="src/theme/Footer.js"
import OriginalFooter from '@theme-original/Footer';
import React from 'react';
export default function Footer(props) {
return (
<>
<div>Before footer</div>
<OriginalFooter {...props} />
</>
);
}
```
Should you be wondering why we have to use `'@theme-original/Footer'` instead of `'@theme/Footer'`, a short explanation is that once you have the swizzled component, the `'@theme/Footer'` alias will now point to your swizzled component, and thus cause a self-import. For a more in-depth explanation, see [theme aliases](#theme-aliases).
## Which component should I swizzle?
Currently, `theme-classic` has about 100 components[^source]! If you want to customize a part of your site's layout, which component should you choose?
[^source]: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme
You can follow the following steps to locate the component to swizzle:
1. **Search.** Our components are semantically named, so you should be able to infer its function from the name. The swizzle CLI allows you to enter part of a component name to narrow down the available choices. For example, if you run `yarn swizzle @docusaurus/theme-classic`, and enter `Doc`, only the docs-related components will be listed.
2. **Start with a higher-level component.** Components form a tree with some components importing others. Every route will be associated with one top-level component that the route will render (most of them listed in [Routing in content plugins](routing.md#routing-in-content-plugins)). For example, all blog post pages have `@theme/BlogPostPage` as the topmost component. You can start with swizzling this component, and then go down the component tree to locate the component that renders just what you are targeting. Don't forget to unswizzle the rest by deleting the files after you've found the correct one, so you don't maintain too many components.
3. **Read the source code and use search wisely.** Topmost components are registered by the plugin with `addRoute`, so you can search for `addRoute` and see which component the plugin references. Afterwards, read the code of all components that this component references.
4. **Ask.** If you still have no idea which component to swizzle to achieve the desired effect, you can reach out for help in one of our [support channels](/community/support).
### Wrapping your site with `<Root>` {#wrapper-your-site-with-root}
The `<Root>` component is one that you probably won't spot. Every component provided by `theme-classic` is ultimately only rendered on certain routes, and will be unmounted during route transition; however, the `<Root>` theme component is rendered at the very top of the Docusaurus SPA, above the router and the theme `<Layout>`, and will **never unmount**, allowing you to wrap your site with additional logic like global state. You can swizzle it 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;
```
:::tip
Use this component to render React Context providers and global stateful logic.
:::
## Do I need to swizzle?
Swizzling ultimately means you have to maintain part of the code directly used to build your site, and you have to interact with Docusaurus internal APIs. If you can, think about the following alternatives when customizing your site:
1. **Use CSS.** CSS rules and selectors can often help you achieve a decent degree of customization. Refer to [styling and layout](../styling-layout.md) for more details.
2. **Use translations.** It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is `en`, you can still run `yarn write-translations -l en` and edit the `code.json` emitted. Refer to [i18n tutorial](../i18n/i18n-tutorial.md) for more details.
3. **The smaller, the better.** If swizzling is inevitable, prefer to swizzle only the relevant part and maintain as little code on your own as possible. Swizzling a small component often means less risk of breaking during upgrade. [Wrapping](#wrapping-theme-components) is also a far safer alternative to [ejecting](#ejecting-theme-components).
## 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-theme-components) 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!

81
website/versioned_docs/version-2.0.0-beta.13/api/docusaurus.config.js.md → website/versioned_docs/version-2.0.0-beta.15/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.

8
website/versioned_docs/version-2.0.0-beta.13/api/plugin-methods/README.md → website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
View file

@ -17,7 +17,7 @@ Every plugin is imported as a module. The module is expected to have the followi
## Plugin constructor
The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin`.
The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | 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.13/api/plugin-methods/_category_.yml → website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/_category_.yml
View file

30
website/versioned_docs/version-2.0.0-beta.13/api/plugin-methods/extend-infrastructure.md → website/versioned_docs/version-2.0.0-beta.15/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',

4
website/versioned_docs/version-2.0.0-beta.13/api/plugin-methods/i18n-lifecycles.md → website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/i18n-lifecycles.md
View file

@ -12,7 +12,7 @@ Plugins declare the JSON translation files they want to use.
Returns translation files `{path: string, content: ChromeI18nJSON}`:
- `path`: relative to the plugin localized folder `i18n/<locale>/pluginName`. Extension `.json` should be omitted to remain generic.
- `path`: relative to the plugin localized folder `i18n/[locale]/[pluginName]`. Extension `.json` should be omitted to remain generic.
- `content`: using the Chrome i18n JSON format.
These files will be written by the [`write-translations` CLI](../../cli.md#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translateContent) and [`translateThemeConfig()`](#translateThemeConfig)
@ -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.13/api/plugin-methods/lifecycle-apis.md → website/versioned_docs/version-2.0.0-beta.15/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.13/api/plugin-methods/static-methods.md → website/versioned_docs/version-2.0.0-beta.15/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.13/api/plugins/_category_.yml → website/versioned_docs/version-2.0.0-beta.15/api/plugins/_category_.yml
View file

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

98
website/versioned_docs/version-2.0.0-beta.15/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
],
],
};
```

97
website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-content-blog.md → website/versioned_docs/version-2.0.0-beta.15/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. |
@ -56,8 +62,8 @@ Accepted fields:
| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. |
| `readingTime` | `ReadingTimeFunctionOption` | The default reading time | A callback to customize the reading time number displayed. |
| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file. |
| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. |
| `feedOptions.type` | <code>'rss' \| 'atom' \| 'all'</code> (or array of multiple options) | **Required** | Type of feed to be generated. |
| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. |
| `feedOptions.type` | <code>FeedType \| FeedType[] \| 'all' \| null</code> | **Required** | Type of feed to be generated. Use `null` to disable generation. |
| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
@ -66,7 +72,7 @@ Accepted fields:
</APITable>
```typescript
```ts
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
@ -90,29 +96,31 @@ type ReadingTimeFunctionOption = (params: {
frontMatter: BlogPostFrontMatter & Record<string, unknown>;
defaultReadingTime: ReadingTimeFunction;
}) => number | undefined;
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',
@ -147,51 +155,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:
@ -199,7 +165,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. |
@ -218,7 +184,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
@ -232,13 +198,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:
@ -253,6 +219,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
```
@ -262,15 +229,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-blog`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-blog
website/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── authors.yml

110
website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-content-docs.md → website/versioned_docs/version-2.0.0-beta.15/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.
:::
@ -55,15 +55,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 +77,12 @@ type PrefixParser = (filename: string) => {
numberPrefix?: number;
};
type CategoryIndexMatcher = (doc: {
fileName: string;
directories: string[];
extension: string;
}) => boolean;
type SidebarGenerator = (generatorArgs: {
item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"
version: {contentPath: string; versionName: string}; // the current version
@ -88,6 +94,7 @@ type SidebarGenerator = (generatorArgs: {
sidebarPosition?: number | undefined;
}>; // all the docs of that version (unfiltered)
numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override
defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
}) => Promise<SidebarItem[]>;
@ -103,19 +110,20 @@ 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',
// Simple use-case: string editUrl
@ -134,12 +142,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 +163,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 +203,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 +219,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 +235,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 +258,7 @@ keywords:
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---
# Markdown Features
My Document Markdown content
@ -302,27 +270,27 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-docs
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
```

65
website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-content-pages.md → website/versioned_docs/version-2.0.0-beta.15/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,63 +75,21 @@ 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.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-pages-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-pages`
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-plugin-content-pages
website/i18n/[locale]/docusaurus-plugin-content-pages
│
│ # translations for website/src/pages
├── first-markdown-page.md

102
website/versioned_docs/version-2.0.0-beta.15/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.15/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.15/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.15/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.13/api/plugins/plugin-pwa.md → website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-pwa.md
View file

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

@ -0,0 +1,72 @@
---
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,
};
```

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

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

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

130
website/versioned_docs/version-2.0.0-beta.13/api/themes/theme-configuration.md → website/versioned_docs/version-2.0.0-beta.15/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.
@ -672,7 +738,7 @@ Accepted fields:
| `logo` | `Logo` | `undefined` | Customization of the logo object. See [Navbar logo](#navbar-logo) for details. |
| `copyright` | `string` | `undefined` | The copyright message to be displayed at the bottom. |
| `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
| `items` | `FooterItem[]` | `[]` | The link groups to be present. |
| `links` | <code>(Column \| FooterLink)[]</code> | `[]` | The link groups to be present. |
</APITable>
@ -699,20 +765,20 @@ module.exports = {
### Footer Links {#footer-links}
You can add links to the footer via `themeConfig.footer.links`.
You can add links to the footer via `themeConfig.footer.links`. There are two types of footer configurations: **multi-column footers** and **simple footers**.
Accepted fields of each link section:
Multi-column footer links have a `title` and a list of `FooterItem`s for each column.
<APITable name="footer-links">
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `undefined` | Label of the section of these links. |
| `items` | `FooterLink[]` | `[]` | Links in this section. |
| `items` | `FooterItem[]` | `[]` | Links in this section. |
</APITable>
Accepted fields of each item in `items`:
Accepted fields of each `FooterItem`:
<APITable name="footer-items">
@ -725,7 +791,7 @@ Accepted fields of each item in `items`:
</APITable>
Example configuration:
Example multi-column configuration:
```js title="docusaurus.config.js"
module.exports = {
@ -775,6 +841,40 @@ module.exports = {
};
```
A simple footer just has a list of `FooterItem`s displayed in a row.
Example simple configuration:
```js title="docusaurus.config.js"
module.exports = {
footer: {
// highlight-start
links: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
{
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
</a>
`,
},
],
// highlight-end
},
};
```
## Table of Contents {#table-of-contents}
You can adjust the default table of contents via `themeConfig.tableOfContents`.
@ -805,20 +905,20 @@ module.exports = {
## Hooks {#hooks}
### `useThemeContext` {#usethemecontext}
### `useColorMode` {#use-color-mode}
React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
A React hook to access the color context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
import {useColorMode} from '@docusaurus/theme-common';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
const {isDarkTheme, setLightTheme, setDarkTheme} = useColorMode();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
@ -826,7 +926,7 @@ const Example = () => {
:::note
The component calling `useThemeContext` must be a child of the `Layout` component.
The component calling `useColorMode` must be a child of the `Layout` component.
```jsx
function ExamplePage() {
@ -846,7 +946,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Base path**: `website/i18n/[locale]/docusaurus-theme-[themeName]`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: N/A
@ -854,7 +954,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-theme-classic
website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json

2
website/versioned_docs/version-2.0.0-beta.13/api/themes/theme-live-codeblock.md → website/versioned_docs/version-2.0.0-beta.15/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.13/api/themes/theme-search-algolia.md → website/versioned_docs/version-2.0.0-beta.15/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.
:::tip

0
website/versioned_docs/version-2.0.0-beta.13/assets/docusaurus-asset-example-banner.png → website/versioned_docs/version-2.0.0-beta.15/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.13/assets/docusaurus-asset-example.docx → website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.docx
View file

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

122
website/versioned_docs/version-2.0.0-beta.13/blog.mdx → website/versioned_docs/version-2.0.0-beta.15/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-->
@ -72,19 +73,23 @@ A whole bunch of exploration to follow.
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.
This naming convention is optional, and you can provide the date as front matter.
<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`
- ...
| 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>
@ -96,7 +101,7 @@ Using a folder can be convenient to co-locate blog post images alongside the Mar
:::
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 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-front-matter).
## Blog list {#blog-list}
@ -104,10 +109,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 +127,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 +153,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 = {
@ -169,17 +175,17 @@ module.exports = {
## 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 +198,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 +224,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 +239,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 +263,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 +278,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 +297,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 +316,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
@ -328,13 +334,15 @@ authors:
The configuration file can be localized, just create a localized copy of it at:
```bash
website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml
website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
```
</details>
:::
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 +401,7 @@ module.exports = {
Usage:
```yml "my-blog-post.md"
```md "my-blog-post.md"
---
hide_reading_time: true
---
@ -455,12 +463,14 @@ module.exports = {
## Feed {#feed}
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
You can generate RSS / Atom / JSON feed by passing `feedOptions`. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
```ts
type FeedType = 'rss' | 'atom' | 'json';
type BlogOptions = {
feedOptions?: {
type?: 'rss' | 'atom' | 'all' | null;
type?: FeedType | 'all' | FeedType[] | null;
title?: string;
description?: string;
copyright: string;
@ -471,7 +481,7 @@ type BlogOptions = {
Example usage:
```js {8-11} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
@ -479,10 +489,12 @@ module.exports = {
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
// highlight-end
},
},
],
@ -490,37 +502,51 @@ module.exports = {
};
```
Accessing the feed:
The feeds can be found at:
The feed for RSS can be found at:
<Tabs>
<TabItem value="RSS">
```text
https://{your-domain}/blog/rss.xml
https://example.com/blog/rss.xml
```
and for Atom:
</TabItem>
<TabItem value="Atom">
```text
https://{your-domain}/blog/atom.xml
https://example.com/blog/atom.xml
```
</TabItem>
<TabItem value="JSON">
```text
https://example.com/blog/feed.json
```
</TabItem>
</Tabs>
## Advanced topics {#advanced-topics}
### Blog-only mode {#blog-only-mode}
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
You can run your Docusaurus 2 site without a dedicated landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to serve the blog through the root route `example.com/` instead of the subroute `example.com/blog/`.
```js {10} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false,
// highlight-next-line
docs: false, // Optional: disable the docs plugin
blog: {
path: './blog',
routeBasePath: '/', // Set this value to '/'.
// highlight-next-line
routeBasePath: '/', // Serve the blog at the site's root
/* other blog options */
},
},
],
@ -534,6 +560,12 @@ 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 elaborate explanation of `routeBasePath`.
:::
### Multiple blogs {#multiple-blogs}
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.

60
website/versioned_docs/version-2.0.0-beta.13/browser-support.md → website/versioned_docs/version-2.0.0-beta.15/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}

10
website/versioned_docs/version-2.0.0-beta.13/cli.md → website/versioned_docs/version-2.0.0-beta.15/cli.md
View file

@ -45,7 +45,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). |
@ -66,7 +66,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
```
@ -110,7 +110,7 @@ npm run swizzle @docusaurus/theme-classic DocSidebar
Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle <themeName>` without `componentName` lists all the components available for swizzling.
`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle [themeName]` without `componentName` lists all the components available for swizzling.
#### Options {#options-2}
@ -149,7 +149,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}
@ -181,7 +181,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.13/configuration.md → website/versioned_docs/version-2.0.0-beta.15/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/{type}-{name}`
- `docusaurus-{type}-{name}`,
where `type` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded.
If the name is scoped (beginning with `@`), the name is first split into scope and package name by the first slash:
```
@scope
^----^
scope (no name!)
@scope/awesome
^----^ ^-----^
scope name
@scope/awesome/main
^----^ ^----------^
scope name
```
If the name is not specified, `{scope}/docusaurus-{type}` is loaded. Otherwise, the following are attempted:
- `{scope}/{name}`
- `{scope}/docusaurus-{type}-{name}`
Below are some examples, for a plugin registered in the `plugins` field. Note that unlike [ESLint](https://eslint.org/docs/user-guide/configuring/plugins#configuring-plugins) or [Babel](https://babeljs.io/docs/en/options#name-normalization) where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.
| Declaration | May be resolved as |
| --- | --- |
| `awesome` | `docusaurus-plugin-awesome` |
| `sitemap` | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) |
| `@mycompany` | `@mycompany/docusaurus-plugin` (the only possible resolution!) |
| `@mycompany/awesome` | `@mycompany/docusaurus-plugin-awesome` |
| `@mycompany/awesome/web` | `@mycompany/docusaurus-plugin-awesome/web` |
</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.

52
website/versioned_docs/version-2.0.0-beta.13/deployment.mdx → website/versioned_docs/version-2.0.0-beta.15/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
@ -70,8 +70,8 @@ If you are unsure of which one to choose, ask the following questions:
How much resource (person-hours, money) am I willing to invest in this?
</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 +124,12 @@ For the same concern of up-to-datedness, we have stopped accepting PRs adding ne
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
```js {2-3} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// highlight-start
url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// highlight-end
// ...
};
```
@ -192,7 +194,7 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu
### Overview {#github-pages-overview}
Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively.
Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial, they will be referred to as **"source"** and **"deployment"**, respectively.
Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`.
@ -228,14 +230,16 @@ GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommen
Example:
```jsx {3-6} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
// highlight-start
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// highlight-end
// ...
};
```
@ -296,7 +300,7 @@ cmd /C 'set "GIT_USER=<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 +313,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:
@ -571,10 +575,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 +604,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 +645,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 +694,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 +703,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 +732,7 @@ 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
[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).

116
website/versioned_docs/version-2.0.0-beta.13/docusaurus-core.md → website/versioned_docs/version-2.0.0-beta.15/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" />
@ -312,9 +330,9 @@ You can even omit a children prop and specify a translation string in your `code
## Hooks {#hooks}
### `useDocusaurusContext` {#usedocusauruscontext}
### `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/).
:::
@ -396,7 +421,7 @@ const MyComponent = () => {
};
```
### `useBaseUrl` {#usebaseurl}
### `useBaseUrl` {#useBaseUrl}
React hook to prepend your site `baseUrl` to a string.
@ -446,11 +471,11 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
:::
### `useBaseUrlUtils` {#usebaseurlutils}
### `useBaseUrlUtils` {#useBaseUrlUtils}
Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
- `withBaseUrl`: useful if you need to add base urls to multiple urls at once.
- `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once.
```jsx
import React from 'react';
@ -466,15 +491,15 @@ const Component = () => {
};
```
### `useGlobalData` {#useglobaldata}
### `useGlobalData` {#useGlobalData}
React hook to access Docusaurus global data created by all the plugins.
Global data is namespaced by plugin name, and plugin id.
Global data is namespaced by plugin name then by plugin ID.
:::info
Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
:::
@ -490,14 +515,17 @@ type GlobalData = Record<
Usage example:
```jsx {2,5-7}
```jsx
import React from 'react';
// highlight-next-line
import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const globalData = useGlobalData();
const myPluginData = globalData['my-plugin']['default'];
return <div>{myPluginData.someAttribute}</div>;
// highlight-end
};
```
@ -507,31 +535,34 @@ Inspect your site's global data at `./docusaurus/globalData.json`
:::
### `usePluginData` {#useplugindata}
### `usePluginData` {#usePluginData}
Access global data created by a specific plugin instance.
This is the most convenient hook to access plugin global data, and should be used most of the time.
This is the most convenient hook to access plugin global data and should be used most of the time.
`pluginId` is optional if you don't use multi-instance plugins.
```ts
usePluginData(pluginName: string, pluginId?: string)
function usePluginData(pluginName: string, pluginId?: string);
```
Usage example:
```jsx {2,5-6}
```jsx
import React from 'react';
// highlight-next-line
import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const myPluginData = usePluginData('my-plugin');
return <div>{myPluginData.someAttribute}</div>;
// highlight-end
};
```
### `useAllPluginInstancesData` {#useallplugininstancesdata}
### `useAllPluginInstancesData` {#useAllPluginInstancesData}
Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
@ -541,14 +572,17 @@ useAllPluginInstancesData(pluginName: string)
Usage example:
```jsx {2,5-7}
```jsx
import React from 'react';
// highlight-next-line
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
// highlight-start
const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
const myPluginData = allPluginInstancesData['default'];
return <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';
```

43
website/versioned_docs/version-2.0.0-beta.13/guides/creating-pages.md → website/versioned_docs/version-2.0.0-beta.15/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).
@ -97,25 +99,36 @@ You can use the full power of React in Markdown pages too, refer to the [MDX](ht
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
- `/src/pages/index.js` → `<baseUrl>`
- `/src/pages/foo.js` → `<baseUrl>/foo`
- `/src/pages/foo/test.js` → `<baseUrl>/foo/test`
- `/src/pages/foo/index.js` → `<baseUrl>/foo/`
- `/src/pages/index.js` → `[baseUrl]`
- `/src/pages/foo.js` → `[baseUrl]/foo`
- `/src/pages/foo/test.js` → `[baseUrl]/foo/test`
- `/src/pages/foo/index.js` → `[baseUrl]/foo/`
In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:
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.13/guides/docs/docs-create-doc.mdx → website/versioned_docs/version-2.0.0-beta.15/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

163
website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md Normal file
View file

@ -0,0 +1,163 @@
---
id: introduction
title: Docs Introduction
sidebar_label: Introduction
slug: /docs-introduction
---
The docs feature provides users with a way to organize Markdown files in a hierarchical format.
:::info
Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options.
:::
## Document ID {#document-id}
Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
```bash
website # Root directory of your site
└── docs
├── greeting.md
└── guide
└── hello.md
```
However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
```md
---
id: part1
---
Lorem ipsum
```
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
```md
---
id: part1
slug: part1.html
---
Lorem ipsum
```
:::note
It is possible to use:
- absolute slugs: `slug: /mySlug`, `slug: /`...
- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
:::
## Home page docs {#home-page-docs}
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
```md
---
id: my-home-doc
slug: /
---
Lorem ipsum
```
## Docs-only mode {#docs-only-mode}
A freshly initialized Docusaurus site has the following structure:
```
example.com/ -> generated from `src/pages/index.js`
example.com/docs/intro -> generated from `docs/intro.md`
example.com/docs/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
...
example.com/blog/2021/08/26/welcome -> generated from `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
...
```
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting them at the root?
Assume that you have the following in your configuration:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* docs plugin options */
},
blog: {
/* blog plugin options */
},
// ...
},
],
};
```
To enter docs-only mode, change it to like this:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
routeBasePath: '/', // Serve the docs at the site's root
/* other docs plugin options */
},
// highlight-next-line
blog: false, // Optional: disable the blog plugin
// ...
},
],
};
```
Note that you **don't necessarily have to give up on using the blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
Don't forget to put some page at the root (`https://example.com/`) through adding the front matter:
```md title="docs/intro.md"
---
# highlight-next-line
slug: /
---
This page will be the home page when users visit https://example.com/.
```
:::caution
If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
:::
Now, the site's structure will be like the following:
```
example.com/ -> generated from `docs/intro.md`
example.com/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
...
```
:::tip
There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
:::

6
website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-markdown-features.mdx → website/versioned_docs/version-2.0.0-beta.15/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}

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