diff --git a/CHANGELOG.md b/CHANGELOG.md index a2460ce36c..f0738d5c0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,191 @@ # Docusaurus 2 Changelog +## 2.0.0-beta.5 (2021-08-26) + +#### :rocket: New Feature + +- `docusaurus-init`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-utils-validation` + - [#5396](https://github.com/facebook/docusaurus/pull/5396) feat(plugin-blog): multi-authors support + authors.yml global configuration ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` + - [#5371](https://github.com/facebook/docusaurus/pull/5371) feat: make blog config options and navbar versions dropdown label translatable ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#5375](https://github.com/facebook/docusaurus/pull/5375) feat: add metatags support for seo / blogposts #5373 ([@johnnyreilly](https://github.com/johnnyreilly)) +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils-validation`, `docusaurus-utils` + - [#3646](https://github.com/facebook/docusaurus/pull/3646) feat: doc tags (same as blog tags) ([@isaac-philip](https://github.com/isaac-philip)) +- `docusaurus-plugin-content-blog` + - [#5354](https://github.com/facebook/docusaurus/pull/5354) feat(plugin-blog): allow `'ALL'` as `postsPerPage` option value ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic` + - [#5330](https://github.com/facebook/docusaurus/pull/5330) feat: Markdown page-specific head metadatas ([@slorber](https://github.com/slorber)) + - [#5322](https://github.com/facebook/docusaurus/pull/5322) feat: structured data for blog posts ([@johnnyreilly](https://github.com/johnnyreilly)) + - [#5314](https://github.com/facebook/docusaurus/pull/5314) feat(v2): add cs (Czech) translations for docusaurus-theme-classic ([@michalsanger](https://github.com/michalsanger)) +- `docusaurus-init` + - [#5233](https://github.com/facebook/docusaurus/pull/5233) feat: new init template classic-typescript ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` + - [#5309](https://github.com/facebook/docusaurus/pull/5309) feat: blog posts support /YYYY/MM/DD/blog-post/index.md pattern + blog frontmatter can reference relative images ([@slorber](https://github.com/slorber)) +- `docusaurus-mdx-loader`, `docusaurus` + - [#5299](https://github.com/facebook/docusaurus/pull/5299) feat: mdx loader fallback, allow importing mdx docs from anywhere ([@slorber](https://github.com/slorber)) + +#### :boom: Breaking Change + +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils-validation`, `docusaurus-utils` + - [#3646](https://github.com/facebook/docusaurus/pull/3646) feat: doc tags (same as blog tags) ([@isaac-philip](https://github.com/isaac-philip)) +- `docusaurus-init`, `docusaurus-migrate`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus` + - [#5345](https://github.com/facebook/docusaurus/pull/5345) refactor: rename Git master branch to main ([@zpao](https://github.com/zpao)) +- `docusaurus-module-type-aliases`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-types`, `docusaurus` + - [#5349](https://github.com/facebook/docusaurus/pull/5349) refactor(core): replace useDocusaurusContext().isClient by useIsBrowser() ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic` + - [#5264](https://github.com/facebook/docusaurus/pull/5264) fix: apply proper class for active doc item on mobiles + avoid duplicated classes ([@lex111](https://github.com/lex111)) + +#### :bug: Bug Fix + +- `docusaurus-theme-classic` + - [#5425](https://github.com/facebook/docusaurus/pull/5425) fix: toc does not highlight clicked anchor + use scroll-margin-top ([@slorber](https://github.com/slorber)) + - [#5424](https://github.com/facebook/docusaurus/pull/5424) refactor: make dynamic authors layout via CSS only ([@lex111](https://github.com/lex111)) + - [#5422](https://github.com/facebook/docusaurus/pull/5422) fix: make tags wrapping properly ([@lex111](https://github.com/lex111)) + - [#5419](https://github.com/facebook/docusaurus/pull/5419) fix: various fixes back-to-top button ([@lex111](https://github.com/lex111)) + - [#5361](https://github.com/facebook/docusaurus/pull/5361) fix: refactor TOC highlighting + handle edge cases ([@slorber](https://github.com/slorber)) + - [#5357](https://github.com/facebook/docusaurus/pull/5357) fix: code blocks should scroll in RTL direction ([@slorber](https://github.com/slorber)) + - [#5346](https://github.com/facebook/docusaurus/pull/5346) fix: author/image adjustments in BlogPosting schema ([@lex111](https://github.com/lex111)) + - [#5240](https://github.com/facebook/docusaurus/pull/5240) fix: remove top margin only from directly first element ([@lex111](https://github.com/lex111)) + - [#5317](https://github.com/facebook/docusaurus/pull/5317) fix: make proper highlighting doc link if no sidebar ([@hamzahamidi](https://github.com/hamzahamidi)) + - [#5316](https://github.com/facebook/docusaurus/pull/5316) fix: avoid extra default active class on doc sidebar item ([@lex111](https://github.com/lex111)) + - [#5319](https://github.com/facebook/docusaurus/pull/5319) fix: unbreak highlighting regular navbar links ([@lex111](https://github.com/lex111)) + - [#5264](https://github.com/facebook/docusaurus/pull/5264) fix: apply proper class for active doc item on mobiles + avoid duplicated classes ([@lex111](https://github.com/lex111)) + - [#5275](https://github.com/facebook/docusaurus/pull/5275) fix: improve spanish translation ([@faloi](https://github.com/faloi)) + - [#5262](https://github.com/facebook/docusaurus/pull/5262) fix: show secondary menu if even there is no main one ([@lex111](https://github.com/lex111)) +- `docusaurus` + - [#5426](https://github.com/facebook/docusaurus/pull/5426) fix: Make update-notifier fail-safe if no permission to read configStore ([@slorber](https://github.com/slorber)) + - [#5398](https://github.com/facebook/docusaurus/pull/5398) fix: fix write-translations warning for theme-common translations ([@slorber](https://github.com/slorber)) + - [#5381](https://github.com/facebook/docusaurus/pull/5381) fix: canary releases should ignore notifier updates ([@slorber](https://github.com/slorber)) + - [#5339](https://github.com/facebook/docusaurus/pull/5339) fix: add admonitions support to mdx partials loaded through the fallback mdx loader ([@slorber](https://github.com/slorber)) + - [#5311](https://github.com/facebook/docusaurus/pull/5311) fix: docusaurus serve logs wrong port if 3000 is taken ([@wan-nyan-wan](https://github.com/wan-nyan-wan)) + - [#5308](https://github.com/facebook/docusaurus/pull/5308) fix: remove unexpected whitespaces in CSS bundle ([@lex111](https://github.com/lex111)) + - [#5268](https://github.com/facebook/docusaurus/pull/5268) fix: fix wrong regex that removes extra letters from swizzled component names ([@Josh-Cena](https://github.com/Josh-Cena)) +- Other + - [#5399](https://github.com/facebook/docusaurus/pull/5399) fix: fix site unlocalized 404 pages + aggressive Netlify /assets caching ([@slorber](https://github.com/slorber)) + - [#5249](https://github.com/facebook/docusaurus/pull/5249) fix: fix Crowdin mapping for pt-BR ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic`, `docusaurus` + - [#5383](https://github.com/facebook/docusaurus/pull/5383) fix: fix Locale Dropdown RTL icon + Webpack aliases ordering ([@slorber](https://github.com/slorber)) +- `docusaurus-init` + - [#5370](https://github.com/facebook/docusaurus/pull/5370) fix(init): fix links to feature images in classic-typescript ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-common` + - [#5364](https://github.com/facebook/docusaurus/pull/5364) fix: unbreak Details component ([@lex111](https://github.com/lex111)) + - [#5297](https://github.com/facebook/docusaurus/pull/5297) fix: fix constant value import ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-ideal-image` + - [#5334](https://github.com/facebook/docusaurus/pull/5334) fix: plugin ideal-image should generate filename with a hash even in development ([@Pierre-Gilles](https://github.com/Pierre-Gilles)) +- `docusaurus-theme-search-algolia` + - [#5290](https://github.com/facebook/docusaurus/pull/5290) fix: make successful build if missing favicon ([@lex111](https://github.com/lex111)) +- `docusaurus-utils` + - [#5270](https://github.com/facebook/docusaurus/pull/5270) fix: ability to link md files with relative paths when paths contain space ([@slorber](https://github.com/slorber)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-types` + - [#5261](https://github.com/facebook/docusaurus/pull/5261) fix: fix various TS errors ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :nail_care: Polish + +- `docusaurus-theme-common` + - [#5402](https://github.com/facebook/docusaurus/pull/5402) refactor: improve styles of Details component ([@lex111](https://github.com/lex111)) +- `docusaurus-theme-classic` + - [#5386](https://github.com/facebook/docusaurus/pull/5386) refactor: various tags improvements ([@lex111](https://github.com/lex111)) + - [#5377](https://github.com/facebook/docusaurus/pull/5377) refactor: make main heading font size changeable via CSS var ([@lex111](https://github.com/lex111)) + - [#5355](https://github.com/facebook/docusaurus/pull/5355) refactor: add blog microdata in markup instead of use JSON-LD ([@lex111](https://github.com/lex111)) + - [#5365](https://github.com/facebook/docusaurus/pull/5365) refactor(v2): improved Farsi default translations ([@massoudmaboudi](https://github.com/massoudmaboudi)) + - [#5280](https://github.com/facebook/docusaurus/pull/5280) refactor(v2): improved Farsi default translations ([@massoudmaboudi](https://github.com/massoudmaboudi)) +- Other + - [#5389](https://github.com/facebook/docusaurus/pull/5389) refactor: clean Canny integration + rename 'Feedback' to 'Feature Requests' + improve TS doc page ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#5242](https://github.com/facebook/docusaurus/pull/5242) refactor: reduce ESLint warnings / better typing ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :memo: Documentation + +- [#5423](https://github.com/facebook/docusaurus/pull/5423) docs: clarify using custom attributes for navbar link ([@lex111](https://github.com/lex111)) +- [#5421](https://github.com/facebook/docusaurus/pull/5421) docs: add Indent to showcase ([@fouad](https://github.com/fouad)) +- [#5405](https://github.com/facebook/docusaurus/pull/5405) docs: add Gotenberg to showcase ([@gulien](https://github.com/gulien)) +- [#5406](https://github.com/facebook/docusaurus/pull/5406) docs: specify proper min Node.js version for Travis CI example ([@BattleOfPlassey](https://github.com/BattleOfPlassey)) +- [#5390](https://github.com/facebook/docusaurus/pull/5390) docs(v2): showcase BoxyHQ ([@deepakprabhakara](https://github.com/deepakprabhakara)) +- [#5376](https://github.com/facebook/docusaurus/pull/5376) docs(v2): Update Datagit site to showcase page ([@massoudmaboudi](https://github.com/massoudmaboudi)) +- [#5372](https://github.com/facebook/docusaurus/pull/5372) docs: remove docusaurus-preset-name from preset doc ([@slorber](https://github.com/slorber)) +- [#5366](https://github.com/facebook/docusaurus/pull/5366) docs: Add drayman to showcase ([@jansivans](https://github.com/jansivans)) +- [#5369](https://github.com/facebook/docusaurus/pull/5369) docs(v2): Add Nocalhost website to showcase page ([@neaped](https://github.com/neaped)) +- [#5351](https://github.com/facebook/docusaurus/pull/5351) docs(website): bump announcement bar + include Twitter link + refactor site colors ([@slorber](https://github.com/slorber)) +- [#5352](https://github.com/facebook/docusaurus/pull/5352) docs: update `docusaurus-plugin-sass` instructions ([@erickzhao](https://github.com/erickzhao)) +- [#5332](https://github.com/facebook/docusaurus/pull/5332) docs(v2): add mdx-mermaid to resources ([@sjwall](https://github.com/sjwall)) +- [#5331](https://github.com/facebook/docusaurus/pull/5331) docs: Changelog page should display TOC with releases ([@slorber](https://github.com/slorber)) +- [#5329](https://github.com/facebook/docusaurus/pull/5329) docs: add Haochen to showcase page ([@HaochenQ](https://github.com/HaochenQ)) +- [#5313](https://github.com/facebook/docusaurus/pull/5313) docs: try to make plugin/preset config less confusing ([@slorber](https://github.com/slorber)) +- [#5296](https://github.com/facebook/docusaurus/pull/5296) docs: update canary doc ([@slorber](https://github.com/slorber)) +- [#5219](https://github.com/facebook/docusaurus/pull/5219) docs: refactor API documentation ([@Josh-Cena](https://github.com/Josh-Cena)) +- [#5271](https://github.com/facebook/docusaurus/pull/5271) Add Plausible Analytics docs to showcase page ([@metmarkosaric](https://github.com/metmarkosaric)) +- [#5283](https://github.com/facebook/docusaurus/pull/5283) docs: fix broken link to syncing tab choices section ([@lex111](https://github.com/lex111)) +- [#5259](https://github.com/facebook/docusaurus/pull/5259) docs(v2): update Remotion website picture in showcase ([@JonnyBurger](https://github.com/JonnyBurger)) +- [#5260](https://github.com/facebook/docusaurus/pull/5260) docs(v2): add Dart Code Metrics site to showcase page ([@incendial](https://github.com/incendial)) +- [#5253](https://github.com/facebook/docusaurus/pull/5253) docs: Fix typo `2-resources.md` ([@forresst](https://github.com/forresst)) +- [#5248](https://github.com/facebook/docusaurus/pull/5248) docs(v2): add docusaurus-prince-pdf to resources ([@sparanoid](https://github.com/sparanoid)) +- [#5239](https://github.com/facebook/docusaurus/pull/5239) docs(v2): Add unmand site to showcase page ([@dbseal](https://github.com/dbseal)) + +#### :house: Internal + +- Other + - [#5397](https://github.com/facebook/docusaurus/pull/5397) chore: rename docusaurus-2-website package + refactor scripts ([@slorber](https://github.com/slorber)) + - [#5342](https://github.com/facebook/docusaurus/pull/5342) chore: fix e2e yarn berry tests ([@slorber](https://github.com/slorber)) + - [#5328](https://github.com/facebook/docusaurus/pull/5328) refactor(website): convert website to TypeScript ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#5336](https://github.com/facebook/docusaurus/pull/5336) chore: bump url-parse from 1.5.1 to 1.5.3 ([@dependabot[bot]](https://github.com/apps/dependabot)) + - [#5312](https://github.com/facebook/docusaurus/pull/5312) fix: fix changelog page mdx import for i18n ([@slorber](https://github.com/slorber)) + - [#5295](https://github.com/facebook/docusaurus/pull/5295) fix: fix canary release versions ([@slorber](https://github.com/slorber)) + - [#5285](https://github.com/facebook/docusaurus/pull/5285) fix: fix canary version names ([@slorber](https://github.com/slorber)) + - [#5269](https://github.com/facebook/docusaurus/pull/5269) misc: enable pt-BR + archive older versions ([@slorber](https://github.com/slorber)) + - [#5237](https://github.com/facebook/docusaurus/pull/5237) chore: enable pt-BR i18n locale on staging ([@slorber](https://github.com/slorber)) +- `docusaurus-init`, `docusaurus-migrate`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus` + - [#5345](https://github.com/facebook/docusaurus/pull/5345) refactor: rename Git master branch to main ([@zpao](https://github.com/zpao)) +- `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#5341](https://github.com/facebook/docusaurus/pull/5341) polish: bind key listener to light/dark toggle + a11y lint fixes ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus` + - [#5347](https://github.com/facebook/docusaurus/pull/5347) chore(mdx-loader): migrate package to TypeScript ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-migrate`, `docusaurus-module-type-aliases`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-types`, `docusaurus` + - [#5335](https://github.com/facebook/docusaurus/pull/5335) refactor: better typing + remove unnecessary eslint-disable ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog` + - [#5338](https://github.com/facebook/docusaurus/pull/5338) refactor(plugin-blog): style improvements in blogUtils ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic` + - [#5256](https://github.com/facebook/docusaurus/pull/5256) chore: upgrade Infima to alpha.30 ([@lex111](https://github.com/lex111)) +- `docusaurus-init` + - [#5315](https://github.com/facebook/docusaurus/pull/5315) refactor(init): share common files between templates ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#5284](https://github.com/facebook/docusaurus/pull/5284) refactor: properly type docs version ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :running_woman: Performance + +- `docusaurus-module-type-aliases`, `docusaurus-theme-bootstrap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-types`, `docusaurus` + - [#5349](https://github.com/facebook/docusaurus/pull/5349) refactor(core): replace useDocusaurusContext().isClient by useIsBrowser() ([@slorber](https://github.com/slorber)) + +#### Committers: 27 + +- Alexey Pyltsyn ([@lex111](https://github.com/lex111)) +- David Seal ([@dbseal](https://github.com/dbseal)) +- Deepak Prabhakara ([@deepakprabhakara](https://github.com/deepakprabhakara)) +- Dmitry Zhifarsky ([@incendial](https://github.com/incendial)) +- Erick Zhao ([@erickzhao](https://github.com/erickzhao)) +- Federico Aloi ([@faloi](https://github.com/faloi)) +- Forresst ([@forresst](https://github.com/forresst)) +- Fouad Matin ([@fouad](https://github.com/fouad)) +- Garry ([@neaped](https://github.com/neaped)) +- Hamza Hamidi ([@hamzahamidi](https://github.com/hamzahamidi)) +- Isaac Philip ([@isaac-philip](https://github.com/isaac-philip)) +- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly)) +- Jonny Burger ([@JonnyBurger](https://github.com/JonnyBurger)) +- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena)) +- Julien Neuhart ([@gulien](https://github.com/gulien)) +- Marko Saric ([@metmarkosaric](https://github.com/metmarkosaric)) +- Massoud Maboudi ([@massoudmaboudi](https://github.com/massoudmaboudi)) +- Michal SΓ€nger ([@michalsanger](https://github.com/michalsanger)) +- Palash Shrivastava ([@BattleOfPlassey](https://github.com/BattleOfPlassey)) +- Paul O’Shannessy ([@zpao](https://github.com/zpao)) +- Pierre-Gilles Leymarie ([@Pierre-Gilles](https://github.com/Pierre-Gilles)) +- Sam Wall ([@sjwall](https://github.com/sjwall)) +- SΓ©bastien Lorber ([@slorber](https://github.com/slorber)) +- Tunghsiao Liu ([@sparanoid](https://github.com/sparanoid)) +- Yan Ivan Evdokimov ([@jansivans](https://github.com/jansivans)) +- [@HaochenQ](https://github.com/HaochenQ) +- wan-nyan-wan ([@wan-nyan-wan](https://github.com/wan-nyan-wan)) + ## 2.0.0-beta.4 (2021-07-28) #### :rocket: New Feature diff --git a/admin/publish.md b/admin/publish.md index f2d38547cf..da66363690 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -108,6 +108,10 @@ yarn workspace website docusaurus docs:version 2.0.0-beta.0 Test running the website with the new version locally. +To keep versions number small, delete the oldest version and add a link to it in `archivedVersions.json`. + +Check [Netlify site deployments](https://app.netlify.com/sites/docusaurus-2/deploys) to pick a recent immutable deployment url. + ### 5. Create a Pull Request You should still be on your local branch `/` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-blog.md deleted file mode 100644 index 628675cbc1..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-blog.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -id: plugin-content-blog -title: 'πŸ“¦ plugin-content-blog' -slug: '/api/plugins/@docusaurus/plugin-content-blog' ---- - -Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-content-blog -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below. - -::: - -## Configuration {#configuration} - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-content-blog', - { - /** - * Path to data on filesystem relative to site dir. - */ - path: 'blog', - /** - * Base url to edit your site. - * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath" - */ - editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', - /** - * For advanced cases, compute the edit url for each Markdown file yourself. - */ - editUrl: ({locale, blogDirPath, blogPath, permalink}) => { - return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`; - }, - /** - * Useful if you commit localized files to git. - * When Markdown files are localized, the edit url will target the localized file, - * instead of the original unlocalized file. - * Note: this option is ignored when editUrl is a function - */ - editLocalizedFiles: false, - /** - * Blog page title for better SEO - */ - blogTitle: 'Blog title', - /** - * Blog page meta description for better SEO - */ - blogDescription: 'Blog', - /** - * Number of blog post elements to show in the blog sidebar - * 'ALL' to show all blog posts - * 0 to disable - */ - blogSidebarCount: 5, - /** - * Title of the blog sidebar - */ - blogSidebarTitle: 'All our posts', - /** - * URL route for the blog section of your site. - * *DO NOT* include a trailing slash. - */ - routeBasePath: 'blog', - include: ['*.md', '*.mdx'], - postsPerPage: 10, - /** - * Theme components used by the blog pages. - */ - blogListComponent: '@theme/BlogListPage', - blogPostComponent: '@theme/BlogPostPage', - blogTagsListComponent: '@theme/BlogTagsListPage', - blogTagsPostsComponent: '@theme/BlogTagsPostsPage', - /** - * Remark and Rehype plugins passed to MDX. - */ - remarkPlugins: [ - /* require('remark-math') */ - ], - rehypePlugins: [], - /** - * Custom Remark and Rehype plugins passed to MDX before - * the default Docusaurus Remark and Rehype plugins. - */ - beforeDefaultRemarkPlugins: [], - beforeDefaultRehypePlugins: [], - /** - * Truncate marker, can be a regex or string. - */ - truncateMarker: //, - /** - * Show estimated reading time for the blog post. - */ - showReadingTime: true, - /** - * Blog feed. - * If feedOptions is undefined, no rss feed will be generated. - */ - feedOptions: { - type: '', // required. 'rss' | 'feed' | 'all' - title: '', // default to siteConfig.title - description: '', // default to `${siteConfig.title} Blog` - copyright: '', - language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes - }, - }, - ], - ], -}; -``` - -## i18n {#i18n} - -Read the [i18n introduction](../../i18n/i18n-introduction.md) first. - -### Translation files location {#translation-files-location} - -- **Base path**: `website/i18n//docusaurus-plugin-content-blog` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-blog-` -- **JSON files**: N/A -- **Markdown files**: `website/i18n//docusaurus-plugin-content-blog` - -### Example file-system structure {#example-file-system-structure} - -```bash -website/i18n//docusaurus-plugin-content-blog -β”‚ -β”‚ # translations for website/blog -β”œβ”€β”€ first-blog-post.md -└── second-blog-post.md -``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-docs.md deleted file mode 100644 index fde5037fb2..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-docs.md +++ /dev/null @@ -1,269 +0,0 @@ ---- -id: plugin-content-docs -title: 'πŸ“¦ plugin-content-docs' -slug: '/api/plugins/@docusaurus/plugin-content-docs' ---- - -Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-content-docs -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below. - -::: - -## Configuration {#configuration} - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-content-docs', - { - /** - * Path to data on filesystem relative to site dir. - */ - path: 'docs', - /** - * Base url to edit your site. - * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath" - */ - editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', - /** - * For advanced cases, compute the edit url for each Markdown file yourself. - */ - editUrl: function ({ - locale, - version, - versionDocsDirPath, - docPath, - permalink, - }) { - return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`; - }, - /** - * Useful if you commit localized files to git. - * When Markdown files are localized, the edit url will target the localized file, - * instead of the original unlocalized file. - * Note: this option is ignored when editUrl is a function - */ - editLocalizedFiles: false, - /** - * Useful if you don't want users to submit doc pull-requests to older versions. - * When docs are versioned, the edit url will link to the doc - * in current version, instead of the versioned doc. - * Note: this option is ignored when editUrl is a function - */ - editCurrentVersion: false, - /** - * URL route for the docs section of your site. - * *DO NOT* include a trailing slash. - * INFO: It is possible to set just `/` for shipping docs without base path. - */ - routeBasePath: 'docs', - include: ['**/*.md', '**/*.mdx'], // Extensions to include. - /** - * Path to sidebar configuration for showing a list of markdown pages. - */ - sidebarPath: 'sidebars.js', - /** - * Function used to replace the sidebar items of type "autogenerated" - * by real sidebar items (docs, categories, links...) - */ - sidebarItemsGenerator: async function ({ - defaultSidebarItemsGenerator, // useful to re-use/enhance default sidebar generation logic from Docusaurus - numberPrefixParser, // numberPrefixParser configured for this plugin - item, // the sidebar item with type "autogenerated" - version, // the current version - docs, // all the docs of that version (unfiltered) - }) { - // Use the provided data to generate a custom sidebar slice - return [ - {type: 'doc', id: 'intro'}, - { - type: 'category', - label: 'Tutorials', - items: [ - {type: 'doc', id: 'tutorial1'}, - {type: 'doc', id: 'tutorial2'}, - ], - }, - ]; - }, - /** - * The Docs plugin supports number prefixes like "01-My Folder/02.My Doc.md". - * Number prefixes are extracted and used as position to order autogenerated sidebar items. - * For conveniency, number prefixes are automatically removed from the default doc id, name, title. - * This parsing logic is configurable to allow all possible usecases and filename patterns. - * Use "false" to disable this behavior and leave the docs untouched. - */ - numberPrefixParser: function (filename) { - // Implement your own logic to extract a potential number prefix - const numberPrefix = findNumberPrefix(filename); - // Prefix found: return it with the cleaned filename - if (numberPrefix) { - return { - numberPrefix, - filename: filename.replace(prefix, ''), - }; - } - // No number prefix found - return {numberPrefix: undefined, filename}; - }, - /** - * Theme components used by the docs pages - */ - docLayoutComponent: '@theme/DocPage', - docItemComponent: '@theme/DocItem', - /** - * Remark and Rehype plugins passed to MDX - */ - remarkPlugins: [ - /* require('remark-math') */ - ], - rehypePlugins: [], - /** - * Custom Remark and Rehype plugins passed to MDX before - * the default Docusaurus Remark and Rehype plugins. - */ - beforeDefaultRemarkPlugins: [], - beforeDefaultRehypePlugins: [], - /** - * Whether to display the author who last updated the doc. - */ - showLastUpdateAuthor: false, - /** - * Whether to display the last date the doc was updated. - */ - showLastUpdateTime: false, - /** - * By default, versioning is enabled on versioned sites. - * This is a way to explicitly disable the versioning feature. - * This will only include the "current" version (the `/docs` directory) - */ - disableVersioning: false, - /** - * Include the "current" version of your docs (the `/docs` directory) - * Tip: turn it off if the current version is a work-in-progress, not ready to be published - */ - includeCurrentVersion: true, - /** - * The last version is the one we navigate to in priority on versioned sites - * It is the one displayed by default in docs navbar items - * By default, the last version is the first one to appear in versions.json - * By default, the last version is at the "root" (docs have path=/docs/myDoc) - * Note: it is possible to configure the path and label of the last version - * Tip: using lastVersion: 'current' make sense in many cases - */ - lastVersion: undefined, - /** - * The docusaurus versioning defaults don't make sense for all projects - * This gives the ability customize the properties of each version independantly - * - label: the label of the version - * - path: the route path of the version - * - banner: the banner to show at the top of a doc of that version: "none" | "unreleased" | "unmaintained" - */ - versions: { - /* - Example configuration: - current: { - label: 'Android SDK v2.0.0 (WIP)', - path: 'android-2.0.0', - banner: 'none', - }, - '1.0.0': { - label: 'Android SDK v1.0.0', - path: 'android-1.0.0', - banner: 'unmaintained', - }, - */ - }, - /** - * Sometimes you only want to include a subset of all available versions. - * Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews - */ - onlyIncludeVersions: undefined, // ex: ["current", "1.0.0", "2.0.0"] - }, - ], - ], -}; -``` - -## Markdown Frontmatter {#markdown-frontmatter} - -Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side: - -- `id`: A unique document id. Default value: file path (including folders, without the extension) -- `title`: The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. Default value: Markdown title or doc `id` -- `hide_title`: 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. Default value: `false` -- `hide_table_of_contents`: Whether to hide the table of contents to the right. Default value: `false` -- `sidebar_label`: The text shown in the document sidebar for this document. Default value: `title` -- `sidebar_position`: Permits to control the position of a doc inside the generated sidebar slice, when using `autogenerated` sidebar items. Can be Int or Float. -- `pagination_label`: The text used in the document next/previous buttons for this document. Default value: `sidebar_label`, or `title` -- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc. Default value: `parse_number_prefixes` plugin option -- `custom_edit_url`: The URL for editing this document. Default value: computed using the `editUrl` plugin options -- `keywords`: Keywords meta tag for the document page, for search engines -- `description`: The description of your document, which will become the `` and `` in ``, used by search engines. Default value: the first line of Markdown content -- `image`: Cover or thumbnail image that will be used when displaying the link to your post. -- `slug`: Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. - -Example: - -```yml ---- -id: doc-markdown -title: Docs Markdown Features -hide_title: false -hide_table_of_contents: false -sidebar_label: Markdown -sidebar_position: 3 -pagination_label: Markdown features -custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md -description: How do I find you when I cannot solve this problem -keywords: - - docs - - docusaurus -image: https://i.imgur.com/mErPwqL.png -slug: /myDoc ---- -# Markdown Features - -My Document Markdown content -``` - -## i18n {#i18n} - -Read the [i18n introduction](../../i18n/i18n-introduction.md) first. - -### Translation files location {#translation-files-location} - -- **Base path**: `website/i18n//docusaurus-plugin-content-docs` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-docs-` -- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) -- **Markdown files**: `website/i18n//docusaurus-plugin-content-docs/` - -### Example file-system structure {#example-file-system-structure} - -```bash -website/i18n//docusaurus-plugin-content-docs -β”‚ -β”‚ # translations for website/docs -β”œβ”€β”€ current -β”‚Β Β  β”œβ”€β”€ api -β”‚Β Β  β”‚Β Β  └── config.md -β”‚Β Β  └── getting-started.md -β”œβ”€β”€ current.json -β”‚ -β”‚ # translations for website/versioned_docs/version-1.0.0 -β”œβ”€β”€ version-1.0.0 -β”‚Β Β  β”œβ”€β”€ api -β”‚Β Β  β”‚Β Β  └── config.md -β”‚Β Β  └── getting-started.md -└── version-1.0.0.json -``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-pages.md deleted file mode 100644 index 4a2173a101..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-content-pages.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -id: plugin-content-pages -title: 'πŸ“¦ plugin-content-pages' -slug: '/api/plugins/@docusaurus/plugin-content-pages' ---- - -The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-content-pages -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below. - -::: - -## Configuration {#configuration} - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-content-pages', - { - /** - * Path to data on filesystem - * relative to site dir - * components in this directory will be automatically converted to pages - */ - path: 'src/pages', - /** - * URL route for the page section of your site - * do not include trailing slash - */ - routeBasePath: '', - include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], - /** - * No Route will be created for matching files - */ - exclude: [ - '**/_*.{js,jsx,ts,tsx,md,mdx}', - '**/*.test.{js,ts}', - '**/__tests__/**', - ], - /** - * Theme component used by markdown pages. - */ - mdxPageComponent: '@theme/MDXPage', - /** - * Remark and Rehype plugins passed to MDX - */ - remarkPlugins: [], - rehypePlugins: [], - /** - * Custom Remark and Rehype plugins passed to MDX before - * the default Docusaurus Remark and Rehype plugins. - */ - beforeDefaultRemarkPlugins: [], - beforeDefaultRehypePlugins: [], - }, - ], - ], -}; -``` - -## i18n {#i18n} - -Read the [i18n introduction](../../i18n/i18n-introduction.md) first. - -### Translation files location {#translation-files-location} - -- **Base path**: `website/i18n//docusaurus-plugin-content-pages` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-pages-` -- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) -- **Markdown files**: `website/i18n//docusaurus-plugin-content-pages` - -### Example file-system structure {#example-file-system-structure} - -```bash -website/i18n//docusaurus-plugin-content-pages -β”‚ -β”‚ # translations for website/src/pages -β”œβ”€β”€ first-markdown-page.md -└── second-markdown-page.md -``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-configuration.md deleted file mode 100644 index 394dbba6d7..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-configuration.md +++ /dev/null @@ -1,575 +0,0 @@ ---- -id: theme-configuration -title: 'Theme configuration' -slug: '/api/themes/configuration' ---- - -This configuration applies to all [main themes](./overview.md). - -## Common {#common} - -### Color mode - dark mode {#color-mode---dark-mode} - -The classic theme provides by default light and dark mode support, with a navbar switch for the user. - -It is possible to customize the color mode support with the following configuration: - -```js {6-36} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - // ... - colorMode: { - // "light" | "dark" - defaultMode: 'light', - - // Hides the switch in the navbar - // Useful if you want to support a single color mode - disableSwitch: false, - - // Should we use the prefers-color-scheme media-query, - // using user system preferences, instead of the hardcoded defaultMode - respectPrefersColorScheme: false, - - // Dark/light switch icon options - switchConfig: { - // Icon for the switch while in dark mode - darkIcon: 'πŸŒ™', - - // CSS to apply to dark icon, - // React inline style object - // see https://reactjs.org/docs/dom-elements.html#style - darkIconStyle: { - marginLeft: '2px', - }, - - // Unicode icons such as '\u2600' will work - // Unicode with 5 chars require brackets: '\u{1F602}' - lightIcon: '\u{1F602}', - - lightIconStyle: { - marginLeft: '1px', - }, - }, - }, - // ... - }, - // ... -}; -``` - -:::caution - -With `respectPrefersColorScheme: true`, the `defaultMode` is overridden by user system preferences. - -If you only want to support one color mode, you likely want to ignore user system preferences. - -::: - -### Meta image {#meta-image} - -You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. - -```js {4-6} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - // Relative to your site's "static" directory. - // Cannot be SVGs. Can be external URLs too. - image: 'img/docusaurus.png', - // ... - }, -}; -``` - -### Metadatas {#metadatas} - -You can configure additional html metadatas (and override existing ones). - -```js {4} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - metadatas: [{name: 'twitter:card', content: 'summary'}], - // ... - }, -}; -``` - -### Announcement bar {#announcement-bar} - -Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. - -```js {4-11} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - announcementBar: { - id: 'support_us', // Any value that will identify this message. - content: - 'We are looking to revamp our docs, please fill this survey', - backgroundColor: '#fafbfc', // Defaults to `#fff`. - textColor: '#091E42', // Defaults to `#000`. - isCloseable: false, // Defaults to `true`. - }, - // ... - }, -}; -``` - -## i18n {#i18n} - -Read the [i18n introduction](../../i18n/i18n-introduction.md) first. - -### Translation files location {#translation-files-location} - -- **Base path**: `website/i18n//docusaurus-theme-` -- **Multi-instance path**: N/A -- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) -- **Markdown files**: `N/A - -### Example file-system structure {#example-file-system-structure} - -```bash -website/i18n//docusaurus-theme-classic -β”‚ -β”‚ # translations for the theme -β”œβ”€β”€ navbar.json -└── footer.json -``` - -## Hooks {#hooks} - -### `useThemeContext` {#usethemecontext} - -React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use. - -Usage example: - -```jsx -import React from 'react'; -// highlight-next-line -import useThemeContext from '@theme/hooks/useThemeContext'; - -const Example = () => { - // highlight-next-line - const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext(); - - return

Dark mode is now {isDarkTheme ? 'on' : 'off'}

; -}; -``` - -:::note - -The component calling `useThemeContext` must be a child of the `Layout` component. - -```jsx -function ExamplePage() { - return ( - - - - ); -} -``` - -::: - -## Navbar {#navbar} - -### Navbar title & logo {#navbar-title--logo} - -You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab. - -To improve dark mode support, you can also set a different logo for this mode. - -```js {5-12} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - navbar: { - title: 'Site Title', - logo: { - alt: 'Site Logo', - src: 'img/logo.svg', - srcDark: 'img/logo_dark.svg', // Default to `logo.src`. - href: 'https://docusaurus.io/', // Default to `siteConfig.baseUrl`. - target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one). - }, - }, - // ... - }, -}; -``` - -### Navbar items {#navbar-items} - -You can add items to the navbar via `themeConfig.navbar.items`. - -By default, Navbar items are regular links (internal or external). - -```js title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - navbar: { - // highlight-start - items: [ - { - // Client-side routing, used for navigating within the website. - // The baseUrl will be automatically prepended to this value. - to: 'docs/introduction', - // A full-page navigation, used for navigating outside of the website. - // You should only use either `to` or `href`. - href: 'https://www.facebook.com', - // Prepends the baseUrl to href values. - prependBaseUrlToHref: true, - // The string to be shown. - label: 'Introduction', - // Left or right side of the navbar. - position: 'left', // or 'right' - // To apply the active class styling on all - // routes starting with this path. - // This usually isn't necessary - activeBasePath: 'docs', - // Alternative to activeBasePath if required. - activeBaseRegex: 'docs/(next|v8)', - // Custom CSS class (for styling any item). - className: '', - }, - // ... other items - ], - // highlight-end - }, - // ... - }, -}; -``` - -React Router should automatically apply active link styling to links, but you can use `activeBasePath` in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use `activeBaseRegex`. `activeBaseRegex` is a more flexible alternative to `activeBasePath` and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL. - -Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes. - -### Navbar dropdown {#navbar-dropdown} - -Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items. - -```js {9-19} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - navbar: { - items: [ - { - label: 'Community', - position: 'left', // or 'right' - items: [ - { - label: 'Facebook', - href: '...', - }, - { - label: 'GitHub', - href: '...', - }, - // ... more items - ], - }, - ], - }, - // ... - }, -}; -``` - -### Navbar doc link {#navbar-doc-link} - -If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar. - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'doc', - docId: 'introduction', - - //// Optional - position: 'left', - label: 'Docs', - activeSidebarClassName: 'navbar__link--active', - docsPluginId: 'default', - }, - // highlight-end - ], - }, - }, -}; -``` - -### Navbar docs version dropdown {#navbar-docs-version-dropdown} - -If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. - -The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions). - -```js {5-8} title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - { - type: 'docsVersionDropdown', - - //// Optional - position: 'left', - // Add additional dropdown items at the beginning/end of the dropdown. - dropdownItemsBefore: [], - dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], - // Do not add the link active class when browsing docs. - dropdownActiveClassDisabled: true, - docsPluginId: 'default', - }, - ], - }, - }, -}; -``` - -### Navbar docs version {#navbar-docs-version} - -If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version. - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'docsVersion', - - //// Optional - position: 'left', - to: '/path', // by default, link to active/latest version - label: 'label', // by default, show active/latest version label - docsPluginId: 'default', - }, - // highlight-end - ], - }, - }, -}; -``` - -### Navbar locale dropdown {#navbar-locale-dropdown} - -If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales. - -The user will be able to switch from one locale to another, while staying on the same page. - -```js {5-8} title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - { - type: 'localeDropdown', - - //// Optional - position: 'left', - // Add additional dropdown items at the beginning/end of the dropdown. - dropdownItemsBefore: [], - dropdownItemsAfter: [ - { - to: 'https://my-site.com/help-us-translate', - label: 'Help us translate', - }, - ], - }, - ], - }, - }, -}; -``` - -### Navbar search {#navbar-search} - -If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar. - -However, with this special navbar item type, you can change the default location. - -```js {5-8} title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - { - type: 'search', - position: 'right', - }, - ], - }, - }, -}; -``` - -### Auto-hide sticky navbar {#auto-hide-sticky-navbar} - -You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. - -```js {5} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - navbar: { - hideOnScroll: true, - }, - // ... - }, -}; -``` - -### Navbar style {#navbar-style} - -You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected. - -Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/). - -```js {5} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - navbar: { - style: 'primary', - }, - // ... - }, -}; -``` - - - -## CodeBlock {#codeblock} - -Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. - -### Theme {#theme} - -By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. - -```js {5-6} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - prism: { - theme: require('prism-react-renderer/themes/github'), - darkTheme: require('prism-react-renderer/themes/dracula'), - }, - // ... - }, -}; -``` - -:::note - -If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting). - -::: - -### Default language {#default-language} - -You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.: - -```js {5} title="docusaurus.config.js" -module.exports = { - // ... - themeConfig: { - prism: { - defaultLanguage: 'javascript', - }, - // ... - }, -}; -``` - -## Footer {#footer-1} - -You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo. - -```js {5-15} title="docusaurus.config.js" - // ... - footer: { - logo: { - alt: 'Facebook Open Source Logo', - src: 'img/oss_logo.png', - href: 'https://opensource.facebook.com', - }, - copyright: `Copyright Β© ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, - } -``` - -## Footer Links {#footer-links} - -You can add links to the footer via `themeConfig.footer.links`: - -```js {5-15} title="docusaurus.config.js" -module.exports = { - // ... - footer: { - links: [ - { - // Label of the section of these links - title: 'Docs', - items: [ - { - // Label of the link - label: 'Style Guide', - // Client-side routing, used for navigating within the website. - // The baseUrl will be automatically prepended to this value. - to: 'docs/', - }, - { - label: 'Second Doc', - to: 'docs/doc2/', - }, - ], - }, - { - title: 'Community', - items: [ - { - label: 'Stack Overflow', - // A full-page navigation, used for navigating outside of the website. - href: 'https://stackoverflow.com/questions/tagged/docusaurus', - }, - { - label: 'Discord', - href: 'https://discordapp.com/invite/docusaurus', - }, - { - label: 'Twitter', - href: 'https://twitter.com/docusaurus', - }, - { - //Renders the html pass-through instead of a simple link - html: ` - - Deploys by Netlify - - `, - }, - ], - }, - ], - }, -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/blog.md b/website/versioned_docs/version-2.0.0-beta.3/blog.md deleted file mode 100644 index d46ba9d270..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/blog.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -id: blog -title: Blog ---- - -## Initial setup {#initial-setup} - -To setup your site's blog, start by creating a `blog` directory. - -Then, add an item link to your blog within `docusaurus.config.js`: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - // ... - navbar: { - items: [ - // ... - // highlight-next-line - {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' - ], - }, - }, -}; -``` - -## Adding posts {#adding-posts} - -To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name. - -For example, at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`: - -```yml ---- -title: Welcome Docusaurus v2 -author: Joel Marcey -author_title: Co-creator of Docusaurus 1 -author_url: https://github.com/JoelMarcey -author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200 -tags: [hello, docusaurus-v2] -description: This is my first post on Docusaurus 2. -image: https://i.imgur.com/mErPwqL.png -hide_table_of_contents: false ---- -Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/). - - - -This is my first post on Docusaurus 2. - -A whole bunch of exploration to follow. -``` - -## Header options {#header-options} - -The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options. - -- `author`: The author name to be displayed. -- `author_url`: The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. -- `author_image_url`: The URL to the author's thumbnail image. -- `author_title`: A description of the author. -- `title`: The blog post title. -- `slug`: Allows to customize the blog post url (`//`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. -- `date`: The blog post creation date. If not specified, this could be extracted from the file name, e.g, `2021-04-15-blog-post.mdx`. By default, it is the Markdown file creation time. -- `tags`: A list of strings or objects of two string fields `label` and `permalink` to tag to your post. -- `draft`: A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development. -- `description`: The description of your post, which will become the `` and `` in ``, used by search engines. If this field is not present, it will default to the first line of the contents. -- `keywords`: Keywords meta tag, which will become the `` in ``, used by search engines. -- `image`: Cover or thumbnail image that will be used when displaying the link to your post. -- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default, it is `false`. - -## Summary truncation {#summary-truncation} - -Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. For example: - -```yml ---- -title: Truncation Example ---- -All these will be part of the blog post summary. - -Even this. - - - -But anything from here on down will not be. - -Not this. - -Or this. -``` - -## Feed {#feed} - -You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`. - -```ts -feedOptions?: { - type?: 'rss' | 'atom' | 'all' | null; - title?: string; - description?: string; - copyright: string; - language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes -}; -``` - -Example usage: - -```js {8-11} title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - blog: { - feedOptions: { - type: 'all', - copyright: `Copyright Β© ${new Date().getFullYear()} Facebook, Inc.`, - }, - }, - }, - ], - ], -}; -``` - -Accessing the feed: - -The feed for RSS can be found at: - -```text -https://{your-domain}/blog/rss.xml -``` - -and for Atom: - -```text -https://{your-domain}/blog/atom.xml -``` - -## Advanced topics {#advanced-topics} - -### Blog-only mode {#blog-only-mode} - -You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. - -```js {10} title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: false, - blog: { - path: './blog', - routeBasePath: '/', // Set this value to '/'. - }, - }, - ], - ], -}; -``` - -:::caution - -Don't forget to delete the existing homepage at `./src/pages/index.js` or else there will be two files mapping to the same route! - -::: - -You can also add meta description to the blog list page for better SEO: - -```js {8} title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - blog: { - blogTitle: 'Docusaurus blog!', - blogDescription: 'A Docusaurus powered blog!', - }, - }, - ], - ], -}; -``` - -### Multiple blogs {#multiple-blogs} - -By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. - -Set the `routeBasePath` to the URL route that you want your second blog to be accessed on. Note that the `routeBasePath` here has to be different from the first blog or else there could be a collision of paths! Also, set `path` to the path to the directory containing your second blog's entries. - -As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique id to the plugins. - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - [ - '@docusaurus/plugin-content-blog', - { - /** - * Required for any multi-instance plugin - */ - id: 'second-blog', - /** - * URL route for the blog section of your site. - * *DO NOT* include a trailing slash. - */ - routeBasePath: 'my-second-blog', - /** - * Path to data on filesystem relative to site dir. - */ - path: './my-second-blog', - }, - ], - ], -}; -``` - -As an example, we host a second blog [here](/tests/blog). diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-admonitions.mdx b/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-admonitions.mdx deleted file mode 100644 index 886b518559..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-admonitions.mdx +++ /dev/null @@ -1,86 +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 - - The content and title *can* include markdown. - - ::: - - :::tip You can specify an optional title - - Heads up! Here's a pro-tip. - - ::: - - :::info - - Useful information. - - ::: - - :::caution - - Warning! You better pay attention! - - ::: - - :::danger - - Danger danger, mayday! - - ::: - -:::note - -The content and title _can_ include markdown. - -::: - -:::tip You can specify an optional title - -Heads up! Here's a pro-tip. - -::: - -:::info - -Useful information. - -::: - -:::caution - -Warning! You better pay attention! - -::: - -:::danger - -Danger danger, mayday! - -::: - -## Specifying title {#specifying-title} - -You may also specify an optional title - - :::note Your Title - - The content and title *can* include markdown. - - ::: - -:::note Your Title - -The content and title _can_ include Markdown. - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-intro.mdx b/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-intro.mdx deleted file mode 100644 index 28f215471c..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-intro.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -id: introduction -title: Markdown Features introduction -sidebar_label: Introduction -description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown. -slug: /markdown-features ---- - -Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible. - -Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users. - -In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example. - -Markdown is a syntax that enables you to write formatted content in a readable syntax. - -The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents. - -:::important - -This section assumes you are using the official Docusaurus content plugins. - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/typescript-support.md b/website/versioned_docs/version-2.0.0-beta.3/typescript-support.md deleted file mode 100644 index 2f802e539f..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.3/typescript-support.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: typescript-support -title: TypeScript Support ---- - -## Setup {#setup} - -Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project: - -```bash npm2yarn -npm install --save-dev typescript @docusaurus/module-type-aliases @types/react @types/react-router-dom @types/react-helmet @tsconfig/docusaurus -``` - -Then add `tsconfig.json` to your project root with the following content: - -```json title="tsconfig.json" -{ - "extends": "@tsconfig/docusaurus/tsconfig.json", - "include": ["src/"] -} -``` - -Docusaurus doesn't use this `tsconfig.json` to compile your project. It is added just for a nicer Editor experience, although you can choose to run `tsc` to type check your code for yourself or on CI. - -Now you can start writing TypeScript theme components. - -## Swizzling TypeScript theme components {#swizzling-typescript-theme-components} - -For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`. - -```bash npm2yarn -npm run swizzle @docusaurus/theme-classic Footer -- --typescript -``` - -At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./lifecycle-apis.md#gettypescriptthemepath). diff --git a/website/versioned_docs/version-2.0.0-beta.5/_partials/swizzleWarning.mdx b/website/versioned_docs/version-2.0.0-beta.5/_partials/swizzleWarning.mdx new file mode 100644 index 0000000000..e2aec479dd --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/_partials/swizzleWarning.mdx @@ -0,0 +1,5 @@ +:::caution + +We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-beta.5/api/docusaurus.config.js.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/docusaurus.config.js.md rename to website/versioned_docs/version-2.0.0-beta.5/api/docusaurus.config.js.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/overview.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/overview.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/overview.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/overview.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-client-redirects.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-client-redirects.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-client-redirects.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-client-redirects.md diff --git a/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-blog.md new file mode 100644 index 0000000000..26ef631a62 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-blog.md @@ -0,0 +1,256 @@ +--- +id: plugin-content-blog +title: 'πŸ“¦ plugin-content-blog' +slug: '/api/plugins/@docusaurus/plugin-content-blog' +--- + +Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus. + +## Installation {#installation} + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-blog +``` + +:::tip + +If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'blog'` | Path to the blog content directory on the filesystem, relative to site dir. | +| `editUrl` | string | EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | +| `blogTitle` | `string` | `'Blog'` | Blog page title for better SEO. | +| `blogDescription` | `string` | `'Blog'` | Blog page meta description for better SEO. | +| `blogSidebarCount` | number | 'ALL' | `5` | Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable | +| `blogSidebarTitle` | `string` | `'Recent posts'` | Title of the blog sidebar. | +| `routeBasePath` | `string` | `'blog'` | URL route for the blog section of your site. **DO NOT** include a trailing slash. Use `/` to put the blog at root path. | +| `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` | number | 'ALL' | `10` | Number of posts to show per page in the listing page. Use `'ALL'` to display all posts on one listing page. | +| `blogListComponent` | `string` | `'@theme/BlogListPage'` | Root component of the blog listing page. | +| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. | +| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page | +| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. | +| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | +| `truncateMarker` | `string` | `//` | Truncate marker, can be a regex or string. | +| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. | +| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file. | +| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. | +| `feedOptions.type` | 'rss' | 'atom' | 'all' (or array of multiple options) | **Required** | Type of feed to be generated. | +| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. | +| `feedOptions.description` | `string` | \`${siteConfig.title} Blog\` | Description of the feed. | +| `feedOptions.copyright` | `string` | `undefined` | Copyright message. | +| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. | + + + +```typescript +type EditUrlFunction = (params: { + blogDirPath: string; + blogPath: string; + permalink: string; + locale: string; +}) => string | undefined; +``` + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'blog', + // Simple use-case: string editUrl + // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', + // Advanced use-case: functional editUrl + editUrl: ({locale, blogDirPath, blogPath, permalink}) => { + return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`; + }, + editLocalizedFiles: false, + blogTitle: 'Blog title', + blogDescription: 'Blog', + blogSidebarCount: 5, + blogSidebarTitle: 'All our posts', + routeBasePath: 'blog', + include: ['**/*.{md,mdx}'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + postsPerPage: 10, + blogListComponent: '@theme/BlogListPage', + blogPostComponent: '@theme/BlogPostPage', + blogTagsListComponent: '@theme/BlogTagsListPage', + blogTagsPostsComponent: '@theme/BlogTagsPostsPage', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], + truncateMarker: //, + showReadingTime: true, + feedOptions: { + type: '', + title: '', + description: '', + copyright: '', + language: undefined, + }, +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + blog: { + path: 'blog', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-blog', + // highlight-start + { + path: 'blog', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## Markdown Frontmatter {#markdown-frontmatter} + +Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. | +| `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. | +| `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. | +| `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. | +| `author_title` | `string` | `undefined` | ⚠️ Prefer using `authors`. A description of the author. | +| `title` | `string` | Markdown title | The blog post title. | +| `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time. | +| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. | +| `draft` | `boolean` | `false` | A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development. | +| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. | +| `keywords` | `string[]` | `undefined` | Keywords meta tag, which will become the `` in ``, used by search engines. | +| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. | +| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | +| `slug` | `string` | File path | Allows to customize the blog post url (`//`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. | + + + +```typescript +type Tag = string | {label: string; permalink: string}; + +// An author key references an author from the global plugin authors.yml file +type AuthorKey = string; + +type Author = { + key?: AuthorKey; + name: string; + title?: string; + url?: string; + image_url?: string; +}; + +// The FrontMatter authors field allows various possible shapes +type Authors = AuthorKey | Author | (AuthorKey | Author)[]; +``` + +Example: + +```yml +--- +title: Welcome Docusaurus v2 +authors: + - slorber + - yangshun + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png +tags: [hello, docusaurus-v2] +description: This is my first post on Docusaurus 2. +image: https://i.imgur.com/mErPwqL.png +hide_table_of_contents: false +--- +A Markdown blog post +``` + +## i18n {#i18n} + +Read the [i18n introduction](../../i18n/i18n-introduction.md) first. + +### Translation files location {#translation-files-location} + +- **Base path**: `website/i18n//docusaurus-plugin-content-blog` +- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-blog-` +- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) +- **Markdown files**: `website/i18n//docusaurus-plugin-content-blog` + +### Example file-system structure {#example-file-system-structure} + +```bash +website/i18n//docusaurus-plugin-content-blog +β”‚ +β”‚ # translations for website/blog +β”œβ”€β”€ authors.yml +β”œβ”€β”€ first-blog-post.md +β”œβ”€β”€ second-blog-post.md +β”‚ +β”‚ # translations for the plugin options that will be rendered +└── options.json +``` diff --git a/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-docs.md new file mode 100644 index 0000000000..800526ce47 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-docs.md @@ -0,0 +1,315 @@ +--- +id: plugin-content-docs +title: 'πŸ“¦ plugin-content-docs' +slug: '/api/plugins/@docusaurus/plugin-content-docs' +--- + +Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus. + +## Installation {#installation} + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-docs +``` + +:::tip + +If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. | +| `editUrl` | string | EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | +| `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. | +| `routeBasePath` | `string` | `'docs'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. Use `/` for shipping docs without base path. | +| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. | +| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | +| `sidebarPath` | false | string | `undefined` (creates autogenerated sidebar) | Path to sidebar configuration. | +| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar#collapsible-categories) | +| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar#expanded-categories-by-default) | +| `sidebarItemsGenerator` | `SidebarGenerator` | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` by real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) | +| `numberPrefixParser` | boolean | PrefixParser | _Omitted_ | Custom parsing logic to extract number prefixes from file names. Use `false` to disable this behavior and leave the docs untouched, and `true` to use the default parser. See also [Using number prefixes](/docs/sidebar#using-number-prefixes) | +| `docLayoutComponent` | `string` | `'@theme/DocPage'` | Root Layout component of each doc page. | +| `docItemComponent` | `string` | `'@theme/DocItem'` | Main doc container, with TOC, pagination, etc. | +| `docTagsListComponent` | `string` | `'@theme/DocTagsListPage'` | Root component of the tags list page | +| `docTagDocListComponent` | `string` | `'@theme/DocTagDocListPage'` | Root component of the "docs containing tag" page. | +| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | +| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. | +| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. | +| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). | +| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory).
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.
Note: the path and label of the last version are configurable.
Tip: `lastVersion: 'current'` makes sense in many cases. | +| `versions` | `Versions` | `{}` | Independent customization of each version's properties. | +| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions.
Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. | + + + +```typescript +type EditUrlFunction = (params: { + version: string; + versionDocsDirPath: string; + docPath: string; + permalink: string; + locale: string; +}) => string | undefined; + +type PrefixParser = ( + filename: string, +) => {filename: string; numberPrefix?: number}; + +type SidebarGenerator = (generatorArgs: { + item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated" + version: {contentPath: string; versionName: string}; // the current version + docs: Array<{ + id: string; + frontMatter: DocFrontMatter & Record; + source: string; + sourceDirName: string; + sidebarPosition?: number | undefined; + }>; // all the docs of that version (unfiltered) + numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin + defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus +}) => Promise; + +type Versions = Record< + string, // the version's ID + { + label: string; // the label of the version + path: string; // the route path of the version + banner: 'none' | 'unreleased' | 'unmaintained'; // the banner to show at the top of a doc of that version + } +>; +``` + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'docs', + // Simple use-case: string editUrl + // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/', + // Advanced use-case: functional editUrl + editUrl: ({versionDocsDirPath, docPath}) => + `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`, + editLocalizedFiles: false, + editCurrentVersion: false, + routeBasePath: 'docs', + include: ['**/*.md', '**/*.mdx'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + sidebarPath: 'sidebars.js', + sidebarItemsGenerator: async function ({ + defaultSidebarItemsGenerator, + numberPrefixParser, + item, + version, + docs, + }) { + // Use the provided data to generate a custom sidebar slice + return [ + {type: 'doc', id: 'intro'}, + { + type: 'category', + label: 'Tutorials', + items: [ + {type: 'doc', id: 'tutorial1'}, + {type: 'doc', id: 'tutorial2'}, + ], + }, + ]; + }, + numberPrefixParser: function (filename) { + // Implement your own logic to extract a potential number prefix + const numberPrefix = findNumberPrefix(filename); + // Prefix found: return it with the cleaned filename + if (numberPrefix) { + return { + numberPrefix, + filename: filename.replace(prefix, ''), + }; + } + // No number prefix found + return {numberPrefix: undefined, filename}; + }, + docLayoutComponent: '@theme/DocPage', + docItemComponent: '@theme/DocItem', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], + showLastUpdateAuthor: false, + showLastUpdateTime: false, + disableVersioning: false, + includeCurrentVersion: true, + lastVersion: undefined, + versions: { + current: { + label: 'Android SDK v2.0.0 (WIP)', + path: 'android-2.0.0', + banner: 'none', + }, + '1.0.0': { + label: 'Android SDK v1.0.0', + path: 'android-1.0.0', + banner: 'unmaintained', + }, + }, + onlyIncludeVersions: ['current', '1.0.0', '2.0.0'], +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + docs: { + path: 'docs', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + // highlight-start + { + path: 'docs', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## Markdown Frontmatter {#markdown-frontmatter} + +Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | file path (including folders, without the extension) | A unique document id. | +| `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. | +| `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. | +| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. | +| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadatas](/docs/sidebar#autogenerated-sidebar-metadatas). | +| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. | +| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. | +| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](/docs/sidebar#using-number-prefixes). | +| `custom_edit_url` | `string` | Computed using the `editUrl` plugin option | The URL for editing this document. | +| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. | +| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. | +| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | +| `slug` | `string` | File path | Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | +| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. | + + + +```typescript +type Tag = string | {label: string; permalink: string}; +``` + +Example: + +```yml +--- +id: doc-markdown +title: Docs Markdown Features +hide_title: false +hide_table_of_contents: false +sidebar_label: Markdown +sidebar_position: 3 +pagination_label: Markdown features +custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: How do I find you when I cannot solve this problem +keywords: + - docs + - docusaurus +image: https://i.imgur.com/mErPwqL.png +slug: /myDoc +--- +# Markdown Features + +My Document Markdown content +``` + +## i18n {#i18n} + +Read the [i18n introduction](../../i18n/i18n-introduction.md) first. + +### Translation files location {#translation-files-location} + +- **Base path**: `website/i18n//docusaurus-plugin-content-docs` +- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-docs-` +- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) +- **Markdown files**: `website/i18n//docusaurus-plugin-content-docs/` + +### Example file-system structure {#example-file-system-structure} + +```bash +website/i18n//docusaurus-plugin-content-docs +β”‚ +β”‚ # translations for website/docs +β”œβ”€β”€ current +β”‚Β Β  β”œβ”€β”€ api +β”‚Β Β  β”‚Β Β  └── config.md +β”‚Β Β  └── getting-started.md +β”œβ”€β”€ current.json +β”‚ +β”‚ # translations for website/versioned_docs/version-1.0.0 +β”œβ”€β”€ version-1.0.0 +β”‚Β Β  β”œβ”€β”€ api +β”‚Β Β  β”‚Β Β  └── config.md +β”‚Β Β  └── getting-started.md +└── version-1.0.0.json +``` diff --git a/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-pages.md new file mode 100644 index 0000000000..27e3b0c9b9 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-content-pages.md @@ -0,0 +1,135 @@ +--- +id: plugin-content-pages +title: 'πŸ“¦ plugin-content-pages' +slug: '/api/plugins/@docusaurus/plugin-content-pages' +--- + +The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality. + +## Installation {#installation} + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-pages +``` + +:::tip + +If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the [preset options](#ex-config-preset). + +::: + +## Configuration {#configuration} + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | `string` | `'src/pages'` | Path to data on filesystem relative to site dir. Components in this directory will be automatically converted to pages. | +| `routeBasePath` | `string` | `'/'` | URL route for the pages section of your site. **DO NOT** include a trailing slash. | +| `include` | `string[]` | `['**/*.{js,jsx,ts,tsx,md,mdx}']` | Matching files will be included and processed. | +| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | +| `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. | +| `remarkPlugins` | `[]` | `any[]` | Remark plugins passed to MDX. | +| `rehypePlugins` | `[]` | `any[]` | Rehype plugins passed to MDX. | +| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | +| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | + + + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + path: 'src/pages', + routeBasePath: '', + include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], + exclude: [ + '**/_*.{js,jsx,ts,tsx,md,mdx}', + '**/_*/**', + '**/*.test.{js,jsx,ts,tsx}', + '**/__tests__/**', + ], + mdxPageComponent: '@theme/MDXPage', + remarkPlugins: [require('remark-math')], + rehypePlugins: [], + beforeDefaultRemarkPlugins: [], + beforeDefaultRehypePlugins: [], +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + pages: { + path: 'src/pages', + // ... configuration object here + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-pages', + // highlight-start + { + path: 'src/pages', + // ... configuration object here + }, + // highlight-end + ], + ], +}; +``` + +## i18n {#i18n} + +Read the [i18n introduction](../../i18n/i18n-introduction.md) first. + +### Translation files location {#translation-files-location} + +- **Base path**: `website/i18n//docusaurus-plugin-content-pages` +- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-pages-` +- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) +- **Markdown files**: `website/i18n//docusaurus-plugin-content-pages` + +### Example file-system structure {#example-file-system-structure} + +```bash +website/i18n//docusaurus-plugin-content-pages +β”‚ +β”‚ # translations for website/src/pages +β”œβ”€β”€ first-markdown-page.md +└── second-markdown-page.md +``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-debug.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-debug.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-debug.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-debug.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-google-analytics.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-google-analytics.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-google-analytics.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-google-analytics.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-google-gtag.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-google-gtag.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-google-gtag.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-google-gtag.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-ideal-image.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-ideal-image.md similarity index 96% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-ideal-image.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-ideal-image.md index 6647383167..737d4ee417 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-ideal-image.md +++ b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-ideal-image.md @@ -26,7 +26,7 @@ module.exports = { ## Usage {#usage} -This plugin supports the PNG, GIF and JPG formats only. +This plugin supports the PNG and JPG formats only. ```jsx import Image from '@theme/IdealImage'; diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-pwa.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-pwa.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-pwa.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-pwa.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-sitemap.md b/website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-sitemap.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/plugins/plugin-sitemap.md rename to website/versioned_docs/version-2.0.0-beta.5/api/plugins/plugin-sitemap.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/overview.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/overview.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/themes/overview.md rename to website/versioned_docs/version-2.0.0-beta.5/api/themes/overview.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-bootstrap.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-bootstrap.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-bootstrap.md rename to website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-bootstrap.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-classic.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-classic.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-classic.md rename to website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-classic.md diff --git a/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-configuration.md new file mode 100644 index 0000000000..8b099bd1ac --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-configuration.md @@ -0,0 +1,816 @@ +--- +id: theme-configuration +title: 'Theme configuration' +slug: '/api/themes/configuration' +--- + +This configuration applies to all [main themes](./overview.md). + +## Common {#common} + +### Color mode {#color-mode---dark-mode} + +The classic theme provides by default light and dark mode support, with a navbar switch for the user. + +It is possible to customize the color mode support within the `colorMode` object. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `defaultMode` | 'light' | 'dark' | `'light'` | The color mode when user first visits the site. | +| `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. | +| `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. | +| `switchConfig` | _See below_ | _See below_ | Dark/light switch icon options. | +| `switchConfig.darkIcon` | `string` | `'🌜'` | Icon for the switch while in dark mode. | +| `switchConfig.darkIconStyle` | JSX style object (see [documentation](https://reactjs.org/docs/dom-elements.html#style)) | `{}` | CSS to apply to dark icon. | +| `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. | +| `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + colorMode: { + defaultMode: 'light', + disableSwitch: false, + respectPrefersColorScheme: false, + switchConfig: { + darkIcon: 'πŸŒ™', + darkIconStyle: { + marginLeft: '2px', + }, + // Unicode icons such as '\u2600' will work + // Unicode with 5 chars require brackets: '\u{1F602}' + lightIcon: '\u{1F602}', + lightIconStyle: { + marginLeft: '1px', + }, + }, + }, + // highlight-end + }, +}; +``` + +:::caution + +With `respectPrefersColorScheme: true`, the `defaultMode` is overridden by user system preferences. + +If you only want to support one color mode, you likely want to ignore user system preferences. + +::: + +### Meta image {#meta-image} + +You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-next-line + image: 'img/docusaurus.png', + }, +}; +``` + +### Metadatas {#metadatas} + +You can configure additional html metadatas (and override existing ones). + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-next-line + metadatas: [{name: 'twitter:card', content: 'summary'}], + }, +}; +``` + +### Announcement bar {#announcement-bar} + +Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. All configuration are in the `announcementBar` object. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `id` | `string` | `'announcement-bar'` | Any value that will identify this message. | +| `content` | `string` | `''` | The text content of the announcement. HTML will be interpolated. | +| `backgroundColor` | `string` | `'#fff'` | Background color of the entire bar. | +| `textColor` | `string` | `'#000'` | Announcement text color. | +| `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a 'Γ—' button. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + announcementBar: { + id: 'support_us', + content: + 'We are looking to revamp our docs, please fill this survey', + backgroundColor: '#fafbfc', + textColor: '#091E42', + isCloseable: false, + }, + // highlight-end + }, +}; +``` + +## Navbar {#navbar} + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `string` | `undefined` | Title for the navbar. | +| `logo` | _See below_ | `undefined` | Customization of the logo object. | +| `items` | `NavbarItem[]` | `[]` | A list of navbar items. See specification below. | +| `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. | +| `style` | 'primary' | 'dark' | Same as theme | Sets the navbar style, ignoring the dark/light theme. | + + + +### Navbar logo {#navbar-logo} + +The logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab. + +To improve dark mode support, you can also set a different logo for this mode. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `alt` | `string` | `undefined` | Alt tag for the logo image. | +| `src` | `string` | **Required** | URL to the logo image. Base URL is appended by default. | +| `srcDark` | `string` | `logo.src` | An alternative image URL to use in dark mode. | +| `href` | `string` | `siteConfig.baseUrl` | Link to navigate to when the logo is clicked. | +| `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + title: 'Site Title', + // highlight-start + logo: { + alt: 'Site Logo', + src: 'img/logo.svg', + srcDark: 'img/logo_dark.svg', + href: 'https://docusaurus.io/', + target: '_self', + }, + // highlight-end + }, + }, +}; +``` + +### Navbar items {#navbar-items} + +You can add items to the navbar via `themeConfig.navbar.items`. + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-start + items: [ + { + type: 'doc', + position: 'left', + docId: 'introduction', + label: 'Docs', + }, + {to: 'blog', label: 'Blog', position: 'left'}, + { + type: 'docsVersionDropdown', + position: 'right', + }, + { + type: 'localeDropdown', + position: 'right', + }, + { + href: 'https://github.com/facebook/docusaurus', + position: 'right', + className: 'header-github-link', + 'aria-label': 'GitHub repository', + }, + ], + // highlight-end + }, + }, +}; +``` + +The items can have different behaviors based on the `type` field. The sections below will introduce you to all the types of navbar items available. + +### Navbar link {#navbar-link} + +By default, Navbar items are regular links (internal or external). + +React Router should automatically apply active link styling to links, but you can use `activeBasePath` in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use `activeBaseRegex`. `activeBaseRegex` is a more flexible alternative to `activeBasePath` and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL. + +Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | The name to be shown for this item. | +| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | +| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | +| `prependBaseUrlToHref` | `boolean` | `false` | Prepends the baseUrl to `href` values. | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | +| `activeBasePath` | `string` | `to` / `href` | To apply the active class styling on all routes starting with this path. This usually isn't necessary. | +| `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. | +| `className` | `string` | `''` | Custom CSS class (for styling any item). | + + + +:::note + +In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link. + +::: + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + to: 'docs/introduction', + // Only one of "to" or "href" should be used + // href: 'https://www.facebook.com', + label: 'Introduction', + position: 'left', + activeBaseRegex: 'docs/(next|v8)', + target: '_blank', + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar dropdown {#navbar-dropdown} + +Navbar items of the type `dropdown` has the additional `items` field, an inner array of navbar items. + +Navbar dropdown items only accept the following **"link-like" item types**: + +- [Navbar link](#navbar-link) +- [Navbar doc link](#navbar-doc-link) +- [Navbar docs version](#navbar-docs-version) + +Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a [plain navbar link](#navbar-link). + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | The name to be shown for this item. | +| `items` | [LinkLikeItem](#navbar-dropdown)[] | **Required** | The items to be contained in the dropdown. | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'dropdown', + label: 'Community', + position: 'left', + items: [ + { + label: 'Facebook', + href: 'https://www.facebook.com', + }, + { + type: 'doc', + label: 'Social', + docId: 'social', + }, + // ... more items + ], + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar doc link {#navbar-doc-link} + +If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `docId` | `string` | **Required** | The ID of the doc that this item links to. | +| `label` | `string` | `docId` | The name to be shown for this item. | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'doc', + position: 'left', + docId: 'introduction', + label: 'Docs', + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar docs version dropdown {#navbar-docs-version-dropdown} + +If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. + +The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions). + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | +| `dropdownItemsBefore` | [LinkLikeItem](#navbar-dropdown)[] | `[]` | Add additional dropdown items at the beginning of the dropdown. | +| `dropdownItemsAfter` | [LinkLikeItem](#navbar-dropdown)[] | `[]` | Add additional dropdown items at the end of the dropdown. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. | +| `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'docsVersionDropdown', + position: 'left', + dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], + dropdownActiveClassDisabled: true, + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar docs version {#navbar-docs-version} + +If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current URL), and fallback to the latest version. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | The active/latest version label. | The name to be shown for this item. | +| `to` | `string` | The active/latest version. | The internal link that this item points to. | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | +| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'docsVersion', + position: 'left', + to: '/path', + label: 'label', + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar locale dropdown {#navbar-locale-dropdown} + +If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales. + +The user will be able to switch from one locale to another, while staying on the same page. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | +| `dropdownItemsBefore` | [LinkLikeItem](#navbar-dropdown)[] | `[]` | Add additional dropdown items at the beginning of the dropdown. | +| `dropdownItemsAfter` | [LinkLikeItem](#navbar-dropdown)[] | `[]` | Add additional dropdown items at the end of the dropdown. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'localeDropdown', + position: 'left', + dropdownItemsAfter: [ + { + to: 'https://my-site.com/help-us-translate', + label: 'Help us translate', + }, + ], + }, + // highlight-end + ], + }, + }, +}; +``` + +### Navbar search {#navbar-search} + +If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar. + +However, with this special navbar item type, you can change the default location. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `position` | 'left' | 'right' | `'left'` | The side of the navbar this item should appear on. | + + + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'search', + position: 'right', + }, + // highlight-end + ], + }, + }, +}; +``` + +### Auto-hide sticky navbar {#auto-hide-sticky-navbar} + +You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-next-line + hideOnScroll: true, + }, + }, +}; +``` + +### Navbar style {#navbar-style} + +You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected. + +Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/). + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + navbar: { + // highlight-next-line + style: 'primary', + }, + }, +}; +``` + +## CodeBlock {#codeblock} + +Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. All configuration are in the `prism` object. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `theme` | `PrismTheme` | `palenight` | The Prism theme to use for light-theme code blocks. | +| `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. | +| `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. | + + + +### Theme {#theme} + +By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). You may also use a different syntax highlighting theme when the site is in dark mode. + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + prism: { + // highlight-start + theme: require('prism-react-renderer/themes/github'), + darkTheme: require('prism-react-renderer/themes/dracula'), + // highlight-end + }, + }, +}; +``` + +:::note + +If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting). + +::: + +### Default language {#default-language} + +You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed. + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + prism: { + // highlight-next-line + defaultLanguage: 'javascript', + }, + }, +}; +``` + +## Footer {#footer-1} + +You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo. + +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `logo` | `Logo` | `undefined` | Customization of the logo object. See [Navbar logo](#navbar-logo) for details. | +| `copyright` | `string` | `undefined` | The copyright message to be displayed at the bottom. | +| `style` | 'dark' | 'light' | `'light'` | The color theme of the footer component. | +| `items` | `FooterItem[]` | `[]` | The link groups to be present. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // highlight-start + footer: { + logo: { + alt: 'Facebook Open Source Logo', + src: 'img/oss_logo.png', + href: 'https://opensource.facebook.com', + }, + copyright: `Copyright Β© ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, + }, + // highlight-end + }, +}; +``` + +### Footer Links {#footer-links} + +You can add links to the footer via `themeConfig.footer.links`. + +Accepted fields of each link section: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `string` | `undefined` | Label of the section of these links. | +| `items` | `FooterLink[]` | `[]` | Links in this section. | + + + +Accepted fields of each item in `items`: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `label` | `string` | **Required** | Text to be displayed for this link. | +| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | +| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | +| `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. | + + + +Example configuration: + +```js title="docusaurus.config.js" +module.exports = { + footer: { + // highlight-start + links: [ + { + title: 'Docs', + items: [ + { + label: 'Style Guide', + to: 'docs/', + }, + { + label: 'Second Doc', + to: 'docs/doc2/', + }, + ], + }, + { + title: 'Community', + items: [ + { + label: 'Stack Overflow', + href: 'https://stackoverflow.com/questions/tagged/docusaurus', + }, + { + label: 'Discord', + href: 'https://discordapp.com/invite/docusaurus', + }, + { + label: 'Twitter', + href: 'https://twitter.com/docusaurus', + }, + { + html: ` + + Deploys by Netlify + + `, + }, + ], + }, + ], + // highlight-end + }, +}; +``` + +## Hooks {#hooks} + +### `useThemeContext` {#usethemecontext} + +React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use. + +Usage example: + +```jsx +import React from 'react'; +// highlight-next-line +import useThemeContext from '@theme/hooks/useThemeContext'; + +const Example = () => { + // highlight-next-line + const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext(); + + return

Dark mode is now {isDarkTheme ? 'on' : 'off'}

; +}; +``` + +:::note + +The component calling `useThemeContext` must be a child of the `Layout` component. + +```jsx +function ExamplePage() { + return ( + + + + ); +} +``` + +::: + +## i18n {#i18n} + +Read the [i18n introduction](../../i18n/i18n-introduction.md) first. + +### Translation files location {#translation-files-location} + +- **Base path**: `website/i18n//docusaurus-theme-` +- **Multi-instance path**: N/A +- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir) +- **Markdown files**: N/A + +### Example file-system structure {#example-file-system-structure} + +```bash +website/i18n//docusaurus-theme-classic +β”‚ +β”‚ # translations for the theme +β”œβ”€β”€ navbar.json +└── footer.json +``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-live-codeblock.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-live-codeblock.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-live-codeblock.md rename to website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-live-codeblock.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-search-algolia.md b/website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-search-algolia.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/api/themes/theme-search-algolia.md rename to website/versioned_docs/version-2.0.0-beta.5/api/themes/theme-search-algolia.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example-banner.png b/website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example-banner.png similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example-banner.png rename to website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example-banner.png diff --git a/website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example-pdf.pdf b/website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example-pdf.pdf similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example-pdf.pdf rename to website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example-pdf.pdf diff --git a/website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example.xyz b/website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example.xyz similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/assets/docusaurus-asset-example.xyz rename to website/versioned_docs/version-2.0.0-beta.5/assets/docusaurus-asset-example.xyz diff --git a/website/versioned_docs/version-2.0.0-beta.5/blog.mdx b/website/versioned_docs/version-2.0.0-beta.5/blog.mdx new file mode 100644 index 0000000000..96dee72d9d --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/blog.mdx @@ -0,0 +1,466 @@ +--- +id: blog +title: Blog +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The blog feature enables you to deploy in no time a full-featured blog. + +:::info + +Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content-blog.md) for an exhaustive list of options. + +::: + +## Initial setup {#initial-setup} + +To setup your site's blog, start by creating a `blog` directory. + +Then, add an item link to your blog within `docusaurus.config.js`: + +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // ... + navbar: { + items: [ + // ... + // highlight-next-line + {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' + ], + }, + }, +}; +``` + +## Adding posts {#adding-posts} + +To publish in the blog, create a Markdown file within the blog directory. + +For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`: + +```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md" +--- +title: Welcome Docusaurus v2 +description: This is my first post on Docusaurus 2. +slug: welcome-docusaurus-v2 +authors: + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + - name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +tags: [hello, docusaurus-v2] +image: https://i.imgur.com/mErPwqL.png +hide_table_of_contents: false +--- +Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/). + + + +This is my first post on Docusaurus 2. + +A whole bunch of exploration to follow. +``` + +:::note + +Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`. + +This naming convention is optional, and you can provide the date as FrontMatter. + +
+Example supported patterns + +- `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` +- ... + +
+ +::: + +:::tip + +Using a folder can be convenient to co-locate blog post images alongside the Markdown file. + +::: + +The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter). + +## Blog list {#blog-list} + +The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed. + +Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. For example: + +```yml +--- +title: Truncation Example +--- +All these will be part of the blog post summary. + +Even this. + + + +But anything from here on down will not be. + +Not this. + +Or this. +``` + +By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add meta description to the blog list page for better SEO: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + // highlight-start + blogTitle: 'Docusaurus blog!', + blogDescription: 'A Docusaurus powered blog!', + postsPerPage: 'ALL', + // highlight-end + }, + }, + ], + ], +}; +``` + +## Blog sidebar {#blog-sidebar} + +The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed. + +You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts": + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + // highlight-start + blogSidebarTitle: 'All posts', + blogSidebarCount: 'ALL', + // highlight-end + }, + }, + ], + ], +}; +``` + +## Blog post authors {#blog-post-authors} + +Use the `authors` FrontMatter field to declare blog post authors. + +### Inline authors {#inline-authors} + +Blog post authors can be declared directly inside the FrontMatter: + +````mdx-code-block + + + +```yml title="my-blog-post.md" +--- +authors: + name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png +--- +``` + + + + +```yml title="my-blog-post.md" +--- +authors: + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + - name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +--- +``` + + + +```` + +:::tip + +This option works best to get started, or for casual, irregular authors. + +::: + +:::info + +Prefer usage of the `authors` FrontMatter, but the legacy `author_*` FrontMatter remains supported: + +```yml title="my-blog-post.md" +--- +author: Joel Marcey +author_title: Co-creator of Docusaurus 1 +author_url: https://github.com/JoelMarcey +author_image_url: https://github.com/JoelMarcey.png +--- + +``` + +::: + +### Global authors {#global-authors} + +For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post. + +It is possible declare those authors globally in a configuration file: + +```yml title="website/blog/authors.yml" +jmarcey: + name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + +slorber: + name: SΓ©bastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +``` + +:::tip + +Use the `authorsMapPath` plugin option to configure the path. JSON is also supported. + +::: + +In blog posts FrontMatter, you can reference the authors declared in the global configuration file: + +````mdx-code-block + + + +```yml title="my-blog-post.md" +--- +authors: jmarcey +--- +``` + + + + +```yml title="my-blog-post.md" +--- +authors: [jmarcey, slorber] +--- +``` + + + +```` + +:::info + +The `authors` system is very flexible and can suit more advanced use-case: + +
+ Mix inline authors and global authors + +You can use global authors most of the time, and still use inline authors: + +```yml title="my-blog-post.md" +--- +authors: + - jmarcey + - slorber + - name: Inline Author name + title: Inline Author Title + url: https://github.com/inlineAuthor + image_url: https://github.com/inlineAuthor +--- + +``` + +
+ +
+ Local override of global authors + +You can customize the global author's data on per-blog-post basis + +```yml title="my-blog-post.md" +--- +authors: + - key: jmarcey + title: Joel Marcey's new title + - key: slorber + name: SΓ©bastien Lorber's new name +--- + +``` + +
+ +
+ Localize the author's configuration file + +The configuration file can be localized, just create a localized copy of it at: + +```bash +website/i18n//docusaurus-plugin-content-blog/authors.yml +``` + +
+ +::: + +## Feed {#feed} + +You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`. + +```ts +type BlogOptions = { + feedOptions?: { + type?: 'rss' | 'atom' | 'all' | null; + title?: string; + description?: string; + copyright: string; + language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes + }; +}; +``` + +Example usage: + +```js {8-11} title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + feedOptions: { + type: 'all', + copyright: `Copyright Β© ${new Date().getFullYear()} Facebook, Inc.`, + }, + }, + }, + ], + ], +}; +``` + +Accessing the feed: + +The feed for RSS can be found at: + +```text +https://{your-domain}/blog/rss.xml +``` + +and for Atom: + +```text +https://{your-domain}/blog/atom.xml +``` + +## Advanced topics {#advanced-topics} + +### Blog-only mode {#blog-only-mode} + +You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. + +```js {10} title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: false, + blog: { + path: './blog', + routeBasePath: '/', // Set this value to '/'. + }, + }, + ], + ], +}; +``` + +:::caution + +Don't forget to delete the existing homepage at `./src/pages/index.js` or else there will be two files mapping to the same route! + +::: + +### Multiple blogs {#multiple-blogs} + +By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. + +Set the `routeBasePath` to the URL route that you want your second blog to be accessed on. Note that the `routeBasePath` here has to be different from the first blog or else there could be a collision of paths! Also, set `path` to the path to the directory containing your second blog's entries. + +As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique id to the plugins. + +```js title="docusaurus.config.js" +module.exports = { + // ... + plugins: [ + [ + '@docusaurus/plugin-content-blog', + { + /** + * Required for any multi-instance plugin + */ + id: 'second-blog', + /** + * URL route for the blog section of your site. + * *DO NOT* include a trailing slash. + */ + routeBasePath: 'my-second-blog', + /** + * Path to data on filesystem relative to site dir. + */ + path: './my-second-blog', + }, + ], + ], +}; +``` + +As an example, we host a second blog [here](/tests/blog). diff --git a/website/versioned_docs/version-2.0.0-beta.3/browser-support.md b/website/versioned_docs/version-2.0.0-beta.5/browser-support.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/browser-support.md rename to website/versioned_docs/version-2.0.0-beta.5/browser-support.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/cli.md b/website/versioned_docs/version-2.0.0-beta.5/cli.md similarity index 97% rename from website/versioned_docs/version-2.0.0-beta.3/cli.md rename to website/versioned_docs/version-2.0.0-beta.5/cli.md index 7327c920d6..026011d03a 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/cli.md +++ b/website/versioned_docs/version-2.0.0-beta.5/cli.md @@ -93,11 +93,11 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht ### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir} -:::caution +```mdx-code-block +import SwizzleWarning from "./_partials/swizzleWarning.mdx" -We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now. - -::: + +``` Change any Docusaurus theme components to your liking with `npm run swizzle`. diff --git a/website/versioned_docs/version-2.0.0-beta.3/configuration.md b/website/versioned_docs/version-2.0.0-beta.5/configuration.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/configuration.md rename to website/versioned_docs/version-2.0.0-beta.5/configuration.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.5/deployment.mdx similarity index 94% rename from website/versioned_docs/version-2.0.0-beta.3/deployment.mdx rename to website/versioned_docs/version-2.0.0-beta.5/deployment.mdx index bc25c720e7..9400cf6a80 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/deployment.mdx +++ b/website/versioned_docs/version-2.0.0-beta.5/deployment.mdx @@ -214,11 +214,11 @@ jobs: - name: Test Build run: | if [ -e yarn.lock ]; then - yarn install --frozen-lockfile + yarn install --frozen-lockfile elif [ -e package-lock.json ]; then - npm ci + npm ci else - npm i + npm i fi npm run build gh-release: @@ -240,11 +240,11 @@ jobs: git config --global user.email "actions@github.com" git config --global user.name "gh-actions" if [ -e yarn.lock ]; then - yarn install --frozen-lockfile + yarn install --frozen-lockfile elif [ -e package-lock.json ]; then - npm ci + npm ci else - npm i + npm i fi npm run deploy ``` @@ -266,7 +266,7 @@ Continuous integration (CI) services are typically used to perform routine tasks ```yaml title=".travis.yml" language: node_js node_js: - - '10' + - '12.13.0' branches: only: - main @@ -426,31 +426,38 @@ After your project has been imported, all subsequent pushes to branches will gen ## Deploying to Qovery {#deploying-to-qovery} -[Qovery](https://qovery.com) is a fully-managed cloud platform that runs on your AWS, GCP, Azure and Digital Ocean account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. +[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. +1. Create a Qovery account. Visit the [Qovery dashboard](https://console.qovery.com) to create an account if you don't already have one. 2. Create a project -Click on "Create a new project" and give a name to your project. +- Click on **Create project** and give a name to your project. +- Click on **Next**. -Click on "Next". +3. Create a new environment -3. Add an application +- Click on **Create environment** and give a name (e.g. staging, production). -Click on "Create an application" then choose "I have an application" and select your GitHub or GitLab repository where your app is located. +4. Add an application -Click on "Next". +- Click on **Create an application**, give a name and select your GitHub or GitLab repository where your Docusaurus app is located. +- Define the main branch name and the root application path. +- Click on **Create**. -Skip adding services +After the application is created: -4. Deploy +- Navigate to your application **Settings** +- Select **Port** +- Add port used by your Docusaurus application -Click on "Deploy". +5. Deploy All you have to do now is to navigate to your application and click on **Deploy** -You can see the status in real time by clicking on deployment logs. +![Deploy the app](https://hub.qovery.com/img/heroku/heroku-1.png) + +That's it. Watch the status and wait till the app is deployed. + +To open the application in your browser, click on **Action** and **Open** in your application overview ## Deploying to Hostman {#deploying-to-hostman} diff --git a/website/versioned_docs/version-2.0.0-beta.3/docusaurus-core.md b/website/versioned_docs/version-2.0.0-beta.5/docusaurus-core.md similarity index 82% rename from website/versioned_docs/version-2.0.0-beta.3/docusaurus-core.md rename to website/versioned_docs/version-2.0.0-beta.5/docusaurus-core.md index 6d4ca9bb10..d144820e93 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/docusaurus-core.md +++ b/website/versioned_docs/version-2.0.0-beta.5/docusaurus-core.md @@ -60,6 +60,8 @@ This component enables linking to internal pages as well as a powerful performan The component is a wrapper around react-router’s `` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `` component. +External links also work, and automatically have these props: `target="_blank" rel="noopener noreferrer"`. + ```jsx {2,7} import React from 'react'; import Link from '@docusaurus/Link'; @@ -70,8 +72,7 @@ const Page = () => ( Check out my blog!

- {/* Note that external links still use `a` tags, but automatically opens in new tab. */} - Follow me on Twitter! + Follow me on Twitter!

); @@ -108,19 +109,56 @@ const Home = () => { ### `` {#browseronly} -The `` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser. +The `` component permits to render React components only in the browser, after the React app has hydrated. -```jsx {1,5-10} +:::tip + +Use it for integrating with code that can't run in Node.js, because `window` or `document` objects are being accessed. + +::: + +#### Props {#browseronly-props} + +- `children`: render function prop returning browser-only JSX. Will not be executed in Node.js +- `fallback` (optional): JSX to render on the server (Node.js) and until React hydration completes. + +#### Example with code {#browseronly-example-code} + +```jsx +// highlight-start import BrowserOnly from '@docusaurus/BrowserOnly'; +// highlight-end const MyComponent = () => { return ( - The fallback content to display on prerendering}> + // highlight-start + {() => { - // Something that should be excluded during build process prerendering. + page url = {window.location.href}; }} + // highlight-end + ); +}; +``` + +#### Example with a library {#browseronly-example-library} + +```jsx +// highlight-start +import BrowserOnly from '@docusaurus/BrowserOnly'; +// highlight-end + +const MyComponent = (props) => { + return ( + // highlight-start + Loading...}> + {() => { + const LibComponent = require('some-lib').LibComponent; + return ; + }} + + // highlight-end ); }; ``` @@ -131,7 +169,7 @@ A simple interpolation component for text containing dynamic placeholders. The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...). -#### Props {#props} +#### Props {#interpolate-props} - `children`: text containing interpolation placeholders like `{placeholderName}` - `values`: object containing interpolation placeholder values @@ -174,7 +212,7 @@ Apart the `values` prop used for interpolation, it is **not possible to use vari ::: -#### Props {#props-1} +#### 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 @@ -234,9 +272,24 @@ interface DocusaurusSiteMetadata { readonly pluginVersions: Record; } +interface I18nLocaleConfig { + label: string; + direction: string; +} + +interface I18n { + defaultLocale: string; + locales: [string, ...string[]]; + currentLocale: string; + localeConfigs: Record; +} + interface DocusaurusContext { siteConfig: DocusaurusConfig; siteMetadata: DocusaurusSiteMetadata; + globalData: Record; + i18n: I18n; + codeTranslations: Record; } ``` @@ -258,6 +311,34 @@ const MyComponent = () => { }; ``` +### `useIsBrowser` {#useIsBrowser} + +Returns `true` when the React app has successfully hydrated in the browser. + +:::caution + +Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic. + +The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). + +Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). + +::: + +Usage example: + +```jsx +import React from 'react'; +import useIsBrowser from '@docusaurus/useIsBrowser'; + +const MyComponent = () => { + // highlight-start + const isBrowser = useIsBrowser(); + // highlight-end + return
{isBrowser ? 'Client' : 'Server'}
; +}; +``` + ### `useBaseUrl` {#usebaseurl} React hook to prepend your site `baseUrl` to a string. @@ -508,21 +589,27 @@ export default function Home() { ### `ExecutionEnvironment` {#executionenvironment} -A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code. +A module which exposes a few boolean variables to check the current rendering environment. -```jsx {2,5} -import React from 'react'; +:::caution + +For React rendering logic, use [`useIsBrowser()`](#useIsBrowser) or [``](#browseronly) instead. + +::: + +Example: + +```jsx import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; -const MyPage = () => { - const location = ExecutionEnvironment.canUseDOM ? window.location.href : null; - return
{location}
; -}; +if (ExecutionEnvironment.canUseDOM) { + require('lib-that-only-works-client-side'); +} ``` | Field | Description | | --- | --- | -| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if prerendering. | +| `ExecutionEnvironment.canUseDOM` | `true` if on client/browser, `false` on Node.js/prerendering. | | `ExecutionEnvironment.canUseEventListeners` | `true` if on client and has `window.addEventListener`. | | `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. | | `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. | diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/creating-pages.md b/website/versioned_docs/version-2.0.0-beta.5/guides/creating-pages.md similarity index 96% rename from website/versioned_docs/version-2.0.0-beta.3/guides/creating-pages.md rename to website/versioned_docs/version-2.0.0-beta.5/guides/creating-pages.md index a30f27b4d0..c622ae5fcd 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/creating-pages.md +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/creating-pages.md @@ -2,6 +2,7 @@ id: creating-pages title: Creating Pages slug: /creating-pages +sidebar_label: Pages --- In this section, we will learn about creating pages in Docusaurus. @@ -18,6 +19,12 @@ Pages do not have sidebars, only [docs](./docs/docs-introduction.md) do. ::: +:::info + +Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.md) for an exhaustive list of options. + +::: + ## Add a React page {#add-a-react-page} Create a file `/src/pages/helloReact.js`: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-create-doc.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-create-doc.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-create-doc.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-create-doc.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-introduction.md similarity index 92% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-introduction.md rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-introduction.md index 9203488ed4..0612e7b089 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-introduction.md +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-introduction.md @@ -7,6 +7,12 @@ 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. @@ -75,6 +81,6 @@ You should delete the existing homepage at `./src/pages/index.js`, or else there :::tip -There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.md#blog-only-mode). +There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode). ::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-markdown-features.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-markdown-features.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-markdown-features.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-multi-instance.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-multi-instance.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/docs-multi-instance.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/docs-multi-instance.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/sidebar.md b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/sidebar.md similarity index 86% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/sidebar.md rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/sidebar.md index c0799f662e..47aecb43f2 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/sidebar.md +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/sidebar.md @@ -22,9 +22,8 @@ module.exports = { '@docusaurus/preset-classic', { docs: { - // highlight-start + // highlight-next-line sidebarPath: require.resolve('./sidebars.js'), - // highlight-end }, }, ], @@ -285,7 +284,8 @@ type SidebarItemCategory = { items: SidebarItem[]; // Array of sidebar items. // Category options: - collapsed: boolean; // Set the category to be collapsed or open by default + collapsible: boolean; // Set the category to be collapsible + collapsed: boolean; // Set the category to be initially collapsed or open by default }; ``` @@ -297,6 +297,7 @@ module.exports = { { type: 'category', label: 'Guides', + collapsible: true, collapsed: false, items: [ 'creating-pages', @@ -332,21 +333,56 @@ module.exports = { #### Collapsible categories {#collapsible-categories} -For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: +We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`. -```js title="docusaurus.config.js" +```js title="sidebars.js" module.exports = { - themeConfig: { - // highlight-start - sidebarCollapsible: false, - // highlight-end - }, + 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} -For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`: +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 = { @@ -356,6 +392,7 @@ module.exports = { { type: 'category', label: 'Docs', + // highlight-next-line collapsed: false, items: ['markdown-features', 'sidebar', 'versioning'], }, @@ -364,6 +401,30 @@ module.exports = { }; ``` +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. @@ -465,6 +526,7 @@ This is the easy tutorial! ```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 ``` diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/docs/versioning.md b/website/versioned_docs/version-2.0.0-beta.5/guides/docs/versioning.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/docs/versioning.md rename to website/versioned_docs/version-2.0.0-beta.5/guides/docs/versioning.md diff --git a/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/_markdown-partial-example.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/_markdown-partial-example.mdx new file mode 100644 index 0000000000..5eb3f3bf11 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/_markdown-partial-example.mdx @@ -0,0 +1,3 @@ +Hello {props.name} + +This is text some content from `_markdown-partial-example.md`. diff --git a/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-admonitions.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-admonitions.mdx new file mode 100644 index 0000000000..ccd7ae68ff --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-admonitions.mdx @@ -0,0 +1,135 @@ +--- +id: admonitions +title: Admonitions +description: Handling admonitions/callouts in Docusaurus Markdown +slug: /markdown-features/admonitions +--- + +In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons. + +Example: + + :::note + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::tip + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::info + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::caution + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + + :::danger + + Some **content** with _markdown_ `syntax`. Check [this `api`](#). + + ::: + +:::note + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::tip + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::info + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::caution + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +:::danger + +Some **content** with _markdown_ `syntax`. Check [this `api`](#). + +::: + +## Specifying title {#specifying-title} + +You may also specify an optional title + + :::note Your Title + + Some **content** with _markdown_ `syntax`. + + ::: + +:::note Your Title + +Some **content** with _markdown_ `syntax`. + +::: + +## Admonitions with MDX + +You can use MDX inside admonitions too! + +```mdx +import Tabs from '@theme/Tabs'; + +import TabItem from '@theme/TabItem'; + +:::tip Use tabs in admonitions + + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 + + +::: +``` + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +:::tip Use tabs in admonitions + +```mdx-code-block + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 + +``` + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-assets.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-assets.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-assets.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-assets.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-code-blocks.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-code-blocks.mdx similarity index 99% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-code-blocks.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-code-blocks.mdx index 7dff83dc0b..7fedb93fec 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-code-blocks.mdx @@ -81,6 +81,8 @@ module.exports = { }; ``` +After adding `additionalLanguages`, restart Docusaurus. + If you want to add highlighting for languages not yet supported by Prism, you can swizzle `prism-include-languages`: ```bash npm2yarn diff --git a/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-head-metadatas.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-head-metadatas.mdx new file mode 100644 index 0000000000..4d4c0e6fad --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-head-metadatas.mdx @@ -0,0 +1,61 @@ +--- +id: head-metadatas +title: Head Metadatas +description: Declaring page-specific head metadatas through MDX +slug: /markdown-features/head-metadatas +--- + +# Head Metadatas + +Docusaurus automatically sets useful page metadatas in ``, `` and `` for you. + +It is possible to add extra metadatas (or override existing ones) by using the `` tag in Markdown files: + +```md title="markdown-features-head-metadatas.mdx" +--- +id: head-metadatas +title: Head Metadatas +--- + + + + + + Head Metadatas customized title! + + + + + + +# Head Metadatas + +My text +``` + +```mdx-code-block + + + + Head Metadatas customized title! + + + + +``` + +:::tip + +This `` declaration has been added to the current Markdown doc, as a demo. + +Open your browser DevTools and check how this page's metadatas have been affected. + +::: + +:::note + +This feature is built on top of the Docusaurus [``](./../../docusaurus-core.md#head) component. + +Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-headings.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-headings.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-headings.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-headings.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-inline-toc.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-inline-toc.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-inline-toc.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-inline-toc.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-intro.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-intro.mdx new file mode 100644 index 0000000000..da448446f4 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-intro.mdx @@ -0,0 +1,115 @@ +--- +id: introduction +title: Markdown Features +sidebar_label: Introduction +description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown. +slug: /markdown-features +--- + +```mdx-code-block +import BrowserWindow from '@site/src/components/BrowserWindow'; +``` + +Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible. + +Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users. + +In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example. + +:::important + +This section assumes you are using the official Docusaurus content plugins. + +::: + +## Standard features + +Markdown is a syntax that enables you to write formatted content in a readable syntax. + +The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents. + +```md +### My Doc Section + +Hello world message with some **bold** text, some _italic_ text and a [link](/) + +![img alt](/img/docusaurus.png) +``` + +```mdx-code-block + + +

My Doc Section

+ +Hello world message with some **bold** text, some _italic_ text and a [link](/) + +![img alt](/img/docusaurus.png) + + +``` + +## Quotes + +Markdown quotes are beautifully styled: + +```md +> This is a quote +``` + +> This is a quote + +## Details + +Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled: + +```md +### Details element example + +
+ Toggle me! +
+
This is the detailed content
+
+
+ + Nested toggle! Some surprise inside... + +
+ 😲😲😲😲😲 +
+
+
+
+``` + +```mdx-code-block + + +

Details element example

+ +
+ Toggle me! +
+
This is the detailed content
+
+
+ + Nested toggle! Some surprise inside... + +
+ 😲😲😲😲😲 +
+
+
+
+ + + +
+``` + +:::note + +In practice, those are not really HTML elements, but React JSX elements, which we'll cover next! + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-math-equations.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-math-equations.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-math-equations.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-math-equations.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-plugins.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-plugins.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-plugins.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-plugins.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-react.mdx similarity index 74% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-react.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-react.mdx index 982b75a90d..4f920c5d20 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-react.mdx +++ b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-react.mdx @@ -1,11 +1,13 @@ --- id: react -title: Using React +title: MDX and React description: Using the power of React in Docusaurus Markdown documents, thanks to MDX slug: /markdown-features/react --- +```mdx-code-block import BrowserWindow from '@site/src/components/BrowserWindow'; +``` ## Using JSX in Markdown {#using-jsx-in-markdown} @@ -17,6 +19,14 @@ While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are t ::: +:::caution + +MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018). + +Use the **[MDX playground](https://mdxjs.com/playground)** to ensure that your syntax is valid MDX. + +::: + Try this block here: ```jsx @@ -74,14 +84,22 @@ Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, ## 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/). +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: + + ```jsx title="myMarkdownFile.mdx" import CodeBlock from '@theme/CodeBlock'; import MyComponentSource from '!!raw-loader!./myComponent'; -{MyComponentSource}; +{MyComponentSource} ``` + ```mdx-code-block import CodeBlock from '@theme/CodeBlock'; @@ -96,6 +114,14 @@ import MyComponentSource from '!!raw-loader!@site/src/pages/examples/_myComponen
``` +You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock: + +```jsx + + {MyComponentSource} + +``` + :::note You have to use `` 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. @@ -110,21 +136,27 @@ This feature is experimental and might be subject to API breaking changes in the ## Importing Markdown {#importing-markdown} -You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. Below we are importing from [another file](./markdown-features-intro.mdx) and inserting it as a component. +You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. -```jsx -import Intro from './markdown-features-intro.mdx'; +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" +Hello {props.name} + +This is text some content from `_markdown-partial-example.mdx`. +``` + +```jsx title="someOtherDoc.mdx" +import PartialExample from './_markdown-partial-example.mdx'; + +; ``` ```mdx-code-block -import Intro from './markdown-features-intro.mdx'; +import PartialExample from './_markdown-partial-example.mdx'; - - - +
diff --git a/website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-tabs.mdx b/website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-tabs.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/guides/markdown-features/markdown-features-tabs.mdx rename to website/versioned_docs/version-2.0.0-beta.5/guides/markdown-features/markdown-features-tabs.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-crowdin.mdx b/website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-crowdin.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-crowdin.mdx rename to website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-crowdin.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-git.md b/website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-git.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-git.md rename to website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-git.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-introduction.md b/website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-introduction.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-introduction.md rename to website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-introduction.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-tutorial.md b/website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-tutorial.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/i18n/i18n-tutorial.md rename to website/versioned_docs/version-2.0.0-beta.5/i18n/i18n-tutorial.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/installation.md b/website/versioned_docs/version-2.0.0-beta.5/installation.md similarity index 97% rename from website/versioned_docs/version-2.0.0-beta.3/installation.md rename to website/versioned_docs/version-2.0.0-beta.5/installation.md index 5d079d348d..c632bc83e6 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/installation.md +++ b/website/versioned_docs/version-2.0.0-beta.5/installation.md @@ -52,6 +52,12 @@ If you want to skip installing dependencies, use the `--skip-install` option, li npx @docusaurus/init@latest init my-website classic --skip-install ``` +You can also use the template's TypeScript variant by passing the `--typescript` flag. + +```bash +npx @docusaurus/init@latest init my-website classic --typescript +``` + ## Project structure {#project-structure} Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`: @@ -84,7 +90,7 @@ my-website ### Project structure rundown {#project-structure-rundown} -- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md) +- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.mdx) - `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx) - `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing - `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md) diff --git a/website/versioned_docs/version-2.0.0-beta.3/introduction.md b/website/versioned_docs/version-2.0.0-beta.5/introduction.md similarity index 99% rename from website/versioned_docs/version-2.0.0-beta.3/introduction.md rename to website/versioned_docs/version-2.0.0-beta.5/introduction.md index 526ae57665..0ecbefd7d1 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/introduction.md +++ b/website/versioned_docs/version-2.0.0-beta.5/introduction.md @@ -42,7 +42,7 @@ Open `http://localhost:3000` and follow the tutorial. Use **[docusaurus.new](https://docusaurus.new)** to test Docusaurus immediately in your browser! -Or read the **[5 minutes tutorial](https://tutorial.docusaurus.io/)** online. +Or read the **[5 minutes tutorial](https://tutorial.docusaurus.io)** online. ::: diff --git a/website/versioned_docs/version-2.0.0-beta.3/lifecycle-apis.md b/website/versioned_docs/version-2.0.0-beta.5/lifecycle-apis.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/lifecycle-apis.md rename to website/versioned_docs/version-2.0.0-beta.5/lifecycle-apis.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-automated.md b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-automated.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/migration/migration-automated.md rename to website/versioned_docs/version-2.0.0-beta.5/migration/migration-automated.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-manual.md b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-manual.md similarity index 98% rename from website/versioned_docs/version-2.0.0-beta.3/migration/migration-manual.md rename to website/versioned_docs/version-2.0.0-beta.5/migration/migration-manual.md index a1cdc37836..e915c815e6 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-manual.md +++ b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-manual.md @@ -229,8 +229,6 @@ module.exports = { copyright: `Copyright Β© ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here. }, image: 'img/docusaurus.png', - // Equivalent to `docsSideNavCollapsible`. - sidebarCollapsible: false, // ... }, }; @@ -399,7 +397,7 @@ The following fields are all deprecated, you may remove from your configuration - `defaultVersionShown` - Versioning is not ported yet. You'd be unable to migration to Docusaurus 2 if you are using versioning. Stay tuned. - `disableHeaderTitle` - `disableTitleTagline` -- `docsSideNavCollapsible` is available at `themeConfig.sidebarCollapsible`, and this is turned on by default now. +- `docsSideNavCollapsible` is available at `docsPluginOptions.sidebarCollapsible`, and this is turned on by default now. - `facebookAppId` - `facebookComments` - `facebookPixelId` @@ -578,7 +576,7 @@ Refer to the [multi-language support code blocks](../guides/markdown-features/ma The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs. -The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field. +The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `authors` field. ## Deployment {#deployment} diff --git a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-overview.md b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-overview.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/migration/migration-overview.md rename to website/versioned_docs/version-2.0.0-beta.5/migration/migration-overview.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-translated-sites.md b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-translated-sites.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/migration/migration-translated-sites.md rename to website/versioned_docs/version-2.0.0-beta.5/migration/migration-translated-sites.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/migration/migration-versioned-sites.md b/website/versioned_docs/version-2.0.0-beta.5/migration/migration-versioned-sites.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/migration/migration-versioned-sites.md rename to website/versioned_docs/version-2.0.0-beta.5/migration/migration-versioned-sites.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/playground.mdx b/website/versioned_docs/version-2.0.0-beta.5/playground.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/playground.mdx rename to website/versioned_docs/version-2.0.0-beta.5/playground.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.3/presets.md b/website/versioned_docs/version-2.0.0-beta.5/presets.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/presets.md rename to website/versioned_docs/version-2.0.0-beta.5/presets.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/search.md b/website/versioned_docs/version-2.0.0-beta.5/search.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/search.md rename to website/versioned_docs/version-2.0.0-beta.5/search.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/static-assets.md b/website/versioned_docs/version-2.0.0-beta.5/static-assets.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/static-assets.md rename to website/versioned_docs/version-2.0.0-beta.5/static-assets.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/styling-layout.md b/website/versioned_docs/version-2.0.0-beta.5/styling-layout.md similarity index 99% rename from website/versioned_docs/version-2.0.0-beta.3/styling-layout.md rename to website/versioned_docs/version-2.0.0-beta.5/styling-layout.md index 388bc3bad3..b50a860324 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/styling-layout.md +++ b/website/versioned_docs/version-2.0.0-beta.5/styling-layout.md @@ -166,7 +166,7 @@ To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 p 1. Install [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass): ```bash npm2yarn -npm install --save docusaurus-plugin-sass +npm install --save docusaurus-plugin-sass sass ``` 2. Include the plugin in your `docusaurus.config.js` file: diff --git a/website/versioned_docs/version-2.0.0-beta.5/typescript-support.md b/website/versioned_docs/version-2.0.0-beta.5/typescript-support.md new file mode 100644 index 0000000000..ec803ffa19 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.5/typescript-support.md @@ -0,0 +1,85 @@ +--- +id: typescript-support +title: TypeScript Support +--- + +Docusaurus is written in TypeScript, and provide first-class TypeScript support. + +## Initialization {#initialization} + +Docusaurus supports writing and using TypeScript theme components. If the init template provides a Typescript variant, you can directly initialize a site with full TypeScript support by using the `--typescript` flag. + +```bash +npx @docusaurus/init@latest init my-website classic --typescript +``` + +Below are some guides on how to migrate an existing project to TypeScript. + +## Setup {#setup} + +To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project: + +```bash npm2yarn +npm install --save-dev typescript @docusaurus/module-type-aliases @types/react @types/react-router-dom @types/react-helmet @tsconfig/docusaurus +``` + +Then add `tsconfig.json` to your project root with the following content: + +```json title="tsconfig.json" +{ + "extends": "@tsconfig/docusaurus/tsconfig.json", + "include": ["src/"] +} +``` + +Docusaurus doesn't use this `tsconfig.json` to compile your project. It is added just for a nicer Editor experience, although you can choose to run `tsc` to type check your code for yourself or on CI. + +Now you can start writing TypeScript theme components. + +## Typing the config file {#typing-config} + +It is **not possible** to use a TypeScript config file in Docusaurus, unless you compile it yourself to JavaScript. + +We recommend using [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html): + +```js title="docusaurus.config.js +// highlight-start +/** @type {import('@docusaurus/types').Plugin} */ +// highlight-end +function MyPlugin(context, options) { + return { + name: 'my-plugin', + }; +} + +// highlight-start +/** @type {import('@docusaurus/types').DocusaurusConfig} */ +// highlight-end +const config = { + title: 'Docusaurus', + tagline: 'Build optimized websites quickly, focus on your content', + organizationName: 'facebook', + projectName: 'docusaurus', + plugins: [MyPlugin], +}; + +module.exports = config; +``` + +:::tip + +Type annotations are very useful and help your IDE understand the type of config objects! + +The best IDEs (VSCode, WebStorm, Intellij...) will provide a nice auto-completion experience. + +::: + +## Swizzling TypeScript theme components {#swizzling-typescript-theme-components} + +For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`. + +```bash npm2yarn +npm run swizzle @docusaurus/theme-classic Footer -- --typescript +``` + +At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./lifecycle-apis.md#gettypescriptthemepath). diff --git a/website/versioned_docs/version-2.0.0-beta.3/using-plugins.md b/website/versioned_docs/version-2.0.0-beta.5/using-plugins.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.3/using-plugins.md rename to website/versioned_docs/version-2.0.0-beta.5/using-plugins.md diff --git a/website/versioned_docs/version-2.0.0-beta.3/using-themes.md b/website/versioned_docs/version-2.0.0-beta.5/using-themes.md similarity index 97% rename from website/versioned_docs/version-2.0.0-beta.3/using-themes.md rename to website/versioned_docs/version-2.0.0-beta.5/using-themes.md index cfd482ca4c..f0f94a959f 100644 --- a/website/versioned_docs/version-2.0.0-beta.3/using-themes.md +++ b/website/versioned_docs/version-2.0.0-beta.5/using-themes.md @@ -98,11 +98,11 @@ Use this component to render React Context providers and global stateful logic. ## Swizzling theme components {#swizzling-theme-components} -:::caution +```mdx-code-block +import SwizzleWarning from "./_partials/swizzleWarning.mdx" -We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now. - -::: + +``` 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`. diff --git a/website/versioned_sidebars/version-2.0.0-beta.3-sidebars.json b/website/versioned_sidebars/version-2.0.0-beta.3-sidebars.json deleted file mode 100644 index bb91addaa7..0000000000 --- a/website/versioned_sidebars/version-2.0.0-beta.3-sidebars.json +++ /dev/null @@ -1,313 +0,0 @@ -{ - "version-2.0.0-beta.3/docs": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/introduction" - }, - { - "collapsed": false, - "type": "category", - "label": "Getting Started", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/installation" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/configuration" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/playground" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/typescript-support" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Guides", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/creating-pages" - }, - { - "collapsed": true, - "type": "category", - "label": "Docs", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/introduction" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/create-doc" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/sidebar" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/versioning" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/markdown-features" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/docs/multi-instance" - } - ] - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/blog" - }, - { - "collapsed": true, - "type": "category", - "label": "Markdown Features", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/introduction" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/react" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/tabs" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/code-blocks" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/admonitions" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/headings" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/inline-toc" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/assets" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/plugins" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/guides/markdown-features/math-equations" - } - ] - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/styling-layout" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/static-assets" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/search" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/browser-support" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/deployment" - }, - { - "collapsed": true, - "type": "category", - "label": "Internationalization", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/i18n/introduction" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/i18n/tutorial" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/i18n/git" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/i18n/crowdin" - } - ] - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Advanced Guides", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/using-plugins" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/using-themes" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/presets" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Migrating from v1 to v2", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/migration/migration-overview" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/migration/migration-automated" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/migration/migration-manual" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/migration/migration-versioned-sites" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/migration/migration-translated-sites" - } - ] - } - ], - "version-2.0.0-beta.3/api": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/cli" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/docusaurus-core" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/docusaurus.config.js" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/lifecycle-apis" - }, - { - "collapsed": true, - "type": "category", - "label": "Plugins", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugins-overview" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-content-docs" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-content-blog" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-content-pages" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-client-redirects" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-debug" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-google-analytics" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-google-gtag" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-ideal-image" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-pwa" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/plugins/plugin-sitemap" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Themes", - "items": [ - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/themes-overview" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/theme-configuration" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/theme-classic" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/theme-bootstrap" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/theme-live-codeblock" - }, - { - "type": "doc", - "id": "version-2.0.0-beta.3/api/themes/theme-search-algolia" - } - ] - } - ] -} diff --git a/website/versioned_sidebars/version-2.0.0-beta.5-sidebars.json b/website/versioned_sidebars/version-2.0.0-beta.5-sidebars.json new file mode 100644 index 0000000000..f5279c2b61 --- /dev/null +++ b/website/versioned_sidebars/version-2.0.0-beta.5-sidebars.json @@ -0,0 +1,326 @@ +{ + "version-2.0.0-beta.5/docs": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/introduction" + }, + { + "type": "category", + "label": "Getting Started", + "collapsed": false, + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/installation" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/configuration" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/playground" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/typescript-support" + } + ], + "collapsible": true + }, + { + "type": "category", + "label": "Guides", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/creating-pages" + }, + { + "type": "category", + "collapsed": true, + "collapsible": true, + "label": "Docs", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/introduction" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/create-doc" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/sidebar" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/versioning" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/markdown-features" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/docs/multi-instance" + } + ] + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/blog" + }, + { + "type": "category", + "label": "Markdown Features", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/introduction" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/react" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/tabs" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/code-blocks" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/admonitions" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/headings" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/inline-toc" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/assets" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/plugins" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/math-equations" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/guides/markdown-features/head-metadatas" + } + ], + "collapsible": true, + "collapsed": true + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/styling-layout" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/static-assets" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/search" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/browser-support" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/deployment" + }, + { + "type": "category", + "label": "Internationalization", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/i18n/introduction" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/i18n/tutorial" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/i18n/git" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/i18n/crowdin" + } + ], + "collapsible": true, + "collapsed": true + } + ], + "collapsible": true, + "collapsed": true + }, + { + "type": "category", + "label": "Advanced Guides", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/using-plugins" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/using-themes" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/presets" + } + ], + "collapsible": true, + "collapsed": true + }, + { + "type": "category", + "label": "Migrating from v1 to v2", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/migration/migration-overview" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/migration/migration-automated" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/migration/migration-manual" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/migration/migration-versioned-sites" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/migration/migration-translated-sites" + } + ], + "collapsible": true, + "collapsed": true + } + ], + "version-2.0.0-beta.5/api": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/cli" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/docusaurus-core" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/docusaurus.config.js" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/lifecycle-apis" + }, + { + "type": "category", + "label": "Plugins", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugins-overview" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-content-docs" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-content-blog" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-content-pages" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-client-redirects" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-debug" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-google-analytics" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-google-gtag" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-ideal-image" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-pwa" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/plugins/plugin-sitemap" + } + ], + "collapsible": true, + "collapsed": true + }, + { + "type": "category", + "label": "Themes", + "items": [ + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/themes-overview" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/theme-configuration" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/theme-classic" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/theme-bootstrap" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/theme-live-codeblock" + }, + { + "type": "doc", + "id": "version-2.0.0-beta.5/api/themes/theme-search-algolia" + } + ], + "collapsible": true, + "collapsed": true + } + ] +} diff --git a/website/versions.json b/website/versions.json index 39b6c8d300..a4b8c7dcf3 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,4 @@ [ - "2.0.0-beta.4", - "2.0.0-beta.3" + "2.0.0-beta.5", + "2.0.0-beta.4" ] diff --git a/website/versionsArchived.json b/website/versionsArchived.json index 600ee795c8..b7a7ddaf94 100644 --- a/website/versionsArchived.json +++ b/website/versionsArchived.json @@ -1,4 +1,5 @@ { + "2.0.0-beta.3": "https://6127899cbdc82400074cdc97--docusaurus-2.netlify.app/docs/2.0.0-beta.3", "2.0.0-beta.2": "https://6107be93ef38a00008efa7eb--docusaurus-2.netlify.app/docs/2.0.0-beta.2", "2.0.0-beta.1": "https://6107be93ef38a00008efa7eb--docusaurus-2.netlify.app/docs/2.0.0-beta.1", "2.0.0-beta.0": "https://6107be93ef38a00008efa7eb--docusaurus-2.netlify.app/docs/2.0.0-beta.0",