diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2274f6d258..4dc6c1d6fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ If you're only fixing a bug, it's fine to submit a pull request right away but w ### Reporting New Issues -When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template. +When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not being managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template. - **One issue, one bug:** Please report a single bug per issue. - **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort. @@ -65,14 +65,18 @@ When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/cho We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues). -If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions. - -You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/main/.github/ISSUE_TEMPLATE/feature.md) - ### Security Bugs Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page. +### Feature requests + +You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request) in the form of an **elaborated RFC**. If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/main/.github/ISSUE_TEMPLATE/feature.md) + +### Questions + +If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions. + ## Pull Requests ### Your First Pull Request @@ -83,13 +87,13 @@ Working on your first Pull Request? You can learn how from this free video serie [**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) -We have a list of [beginner friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started. +We have a list of [beginner-friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started. ### Versioned Docs If you only want to make content changes you just need to be aware of versioned docs. -- `website/docs` - The files in here are responsible for the "next" version at https://docusaurus.io/docs/next/installation. +- `website/docs` - The files here are responsible for the "next" version at https://docusaurus.io/docs/next/installation. - `website/versioned_docs/version-X.Y.Z` - These are the docs for the X.Y.Z version at https://docusaurus.io/docs/X.Y.Z/installation. To make a fix to the published versions you must edit the corresponding markdown file in both folders. If you only made changes in `docs`, be sure to be viewing the `next` version to see the updates (ensure there's `next` in the URL). @@ -104,7 +108,7 @@ To make a fix to the published versions you must edit the corresponding markdown ### Online one-click setup for contributing -You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click it will launch a workspace (for Docusaurus 2) and automatically: +You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click, it will launch a workspace (for Docusaurus 2) and automatically: - clone the docusaurus repo. - install the dependencies. @@ -123,7 +127,7 @@ Small pull requests are much easier to review and more likely to get merged. Mak Please make sure the following is done when submitting a pull request: 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `main`. -1. Add the [copyright notice](#copyright-header-for-source-code) notice to the top of any code new files you've added. +1. Add the [copyright notice](#copyright-header-for-source-code) to the top of any code new files you've added. 1. Describe your [**test plan**](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/main/admin/testing-changes-on-Docusaurus-itself.md)! 1. Make sure your code lints (`yarn prettier && yarn lint`). 1. Make sure your Jest tests pass (`yarn test`). @@ -133,11 +137,9 @@ All pull requests should be opened against the `main` branch. #### Test Plan -A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI. +A good test plan has the exact commands you ran and their output and provides screenshots or videos if the pull request changes UI. If you've changed APIs, update the documentation. -- If you've changed APIs, update the documentation. - -If you need help testing your changes locally, you can check out the doc on doing [local third party testing](https://github.com/facebook/docusaurus/blob/main/admin/local-third-party-project-testing.md). +If you need help testing your changes locally, you can check out the doc on doing [local third-party testing](https://github.com/facebook/docusaurus/blob/main/admin/local-third-party-project-testing.md). #### Breaking Changes @@ -224,7 +226,7 @@ Use lower case not title case! ### General -- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation. +- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation, etc. - "Attractive" - We do have Prettier (a formatter) and ESLint (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during every git commit. diff --git a/examples/classic-typescript/docs/intro.md b/examples/classic-typescript/docs/intro.md index 8417aebee8..440ad3373e 100644 --- a/examples/classic-typescript/docs/intro.md +++ b/examples/classic-typescript/docs/intro.md @@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new Generate a new Docusaurus site using the **classic template**: -```shell +```bash npm init docusaurus@latest my-website classic ``` @@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic Run the development server: -```shell +```bash cd my-website npx docusaurus start diff --git a/examples/classic/docs/intro.md b/examples/classic/docs/intro.md index 8417aebee8..440ad3373e 100644 --- a/examples/classic/docs/intro.md +++ b/examples/classic/docs/intro.md @@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new Generate a new Docusaurus site using the **classic template**: -```shell +```bash npm init docusaurus@latest my-website classic ``` @@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic Run the development server: -```shell +```bash cd my-website npx docusaurus start diff --git a/examples/facebook/docs/intro.md b/examples/facebook/docs/intro.md index 8417aebee8..440ad3373e 100644 --- a/examples/facebook/docs/intro.md +++ b/examples/facebook/docs/intro.md @@ -16,7 +16,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new Generate a new Docusaurus site using the **classic template**: -```shell +```bash npm init docusaurus@latest my-website classic ``` @@ -24,7 +24,7 @@ npm init docusaurus@latest my-website classic Run the development server: -```shell +```bash cd my-website npx docusaurus start diff --git a/packages/create-docusaurus/templates/shared/docs/intro.md b/packages/create-docusaurus/templates/shared/docs/intro.md index df63c7dc93..500260230b 100644 --- a/packages/create-docusaurus/templates/shared/docs/intro.md +++ b/packages/create-docusaurus/templates/shared/docs/intro.md @@ -23,7 +23,7 @@ Generate a new Docusaurus site using the **classic template**. The classic template will automatically be added to your project after you run the command: -```shell +```bash npm init docusaurus@latest my-website classic ``` @@ -35,7 +35,7 @@ The command also installs all necessary dependencies you need to run Docusaurus. Run the development server: -```shell +```bash cd my-website npm run start ``` diff --git a/packages/docusaurus-theme-classic/README.md b/packages/docusaurus-theme-classic/README.md index 1bcc1807f4..3a30bb9290 100644 --- a/packages/docusaurus-theme-classic/README.md +++ b/packages/docusaurus-theme-classic/README.md @@ -24,7 +24,7 @@ module.exports = { ## Swizzling components -```shell +```bash $ npm swizzle @docusaurus/theme-classic [component name] ``` diff --git a/website/community/0-support.md b/website/community/0-support.md index 51e96593c4..fcfa721852 100644 --- a/website/community/0-support.md +++ b/website/community/0-support.md @@ -12,7 +12,7 @@ Stack Overflow is a popular forum to ask code-level questions or if you're stuck ## Discussion forums {#discussion-forums} -There are many online forums which are a great place for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit. +There are many online forums for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit. - [Docusaurus online chat](https://discord.gg/docusaurus) - [#help-and-questions](https://discord.gg/fwbcrQ3dHR) for user help @@ -21,7 +21,7 @@ There are many online forums which are a great place for discussion about best p ## Feature requests {#feature-requests} -For new feature requests, you can create a post on our [feature requests board (Canny)](/feature-requests), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first! +For new feature requests, you can create a post on our [feature requests board (Canny)](/feature-requests), which is a handy tool for road-mapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first! ## News {#news} diff --git a/website/community/4-canary.md b/website/community/4-canary.md index c6b1484326..b81c11ea90 100644 --- a/website/community/4-canary.md +++ b/website/community/4-canary.md @@ -2,15 +2,15 @@ Docusaurus has a canary releases system. -It permits you to **test new unreleased features** as soon as the pull-requests are merged. +It permits you to **test new unreleased features** as soon as the pull requests are merged. It is a good way to **give feedback to maintainers**, ensuring the newly implemented feature works as intended. :::note -Using a canary release in production might seem risky, but in practice it's not. +Using a canary release in production might seem risky, but in practice, it's not. -A canary release passes all automated tests, and is used in production by the Docusaurus site itself. +A canary release passes all automated tests and is used in production by the Docusaurus site itself. ::: diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index ea5b73cd05..28fed29987 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -76,7 +76,7 @@ module.exports = { - Type: `string` -Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field. +Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field. ```js title="docusaurus.config.js" module.exports = { @@ -90,9 +90,7 @@ module.exports = { - Type: `string | undefined` -Path to your site favicon - -Example, if your favicon is in `static/img/favicon.ico`: +Path to your site favicon. For example, if your favicon is in `static/img/favicon.ico`: ```js title="docusaurus.config.js" module.exports = { @@ -112,7 +110,7 @@ Allow to customize the presence/absence of a trailing slash at the end of URLs/l :::tip -Each static hosting provider serve static files differently (this behavior may even change over time). +Each static hosting provider serves static files differently (this behavior may even change over time). Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting. @@ -146,7 +144,7 @@ module.exports = { ``` - `label`: the label to use for this locale -- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Araric, Hebrew, etc.) +- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Arabic, Hebrew, etc.) ### `noIndex` {#noindex} @@ -341,33 +339,45 @@ module.exports = { ### `plugins` {#plugins} - +- Type: `PluginConfig[]` -- Type: `any[]` +```ts +type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any]; +``` + +See [plugin method references](./plugin-methods/README.md) for the shape of a `PluginModule`. ```js title="docusaurus.config.js" module.exports = { - plugins: [], + plugins: [ + 'docusaurus-plugin-awesome', + ['docusuarus-plugin-confetti', {fancy: false}], + () => ({ + postBuild() { + console.log('Build finished'); + }, + }), + ], }; ``` ### `themes` {#themes} - - -- Type: `any[]` +- Type: `PluginConfig[]` ```js title="docusaurus.config.js" module.exports = { - themes: [], + themes: ['@docusaurus/theme-classic'], }; ``` ### `presets` {#presets} - +- Type: `PresetConfig[]` -- Type: `any[]` +```ts +type PresetConfig = string | [string, any]; +``` ```js title="docusaurus.config.js" module.exports = { @@ -390,7 +400,7 @@ module.exports = { }; ``` -Attempting to add unknown field in the config will lead to error in build time: +Attempting to add unknown fields in the config will lead to errors during build time: ```bash Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js @@ -548,7 +558,7 @@ module.exports = { :::caution -This banner need to inline CSS / JS. +This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL. If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it. diff --git a/website/docs/api/plugin-methods/README.md b/website/docs/api/plugin-methods/README.md index f3d09ee01f..b764d726d5 100644 --- a/website/docs/api/plugin-methods/README.md +++ b/website/docs/api/plugin-methods/README.md @@ -37,11 +37,11 @@ interface LoadContext { `options` are the [second optional parameter when the plugins are used](../../using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. If there's a [`validateOptions`](./static-methods.md#validateOptions) function exported, the `options` will be validated and normalized beforehand. -Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes. +Alternatively, if a preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to the individual plugin to define what options it takes. ## Example {#example} -Here's a mind model for a presumptuous plugin implementation. +Here's a mental model for a presumptuous plugin implementation. ```js // A JavaScript function that returns an object. diff --git a/website/docs/api/plugin-methods/extend-infrastructure.md b/website/docs/api/plugin-methods/extend-infrastructure.md index 69a3c51830..fffc17b2e4 100644 --- a/website/docs/api/plugin-methods/extend-infrastructure.md +++ b/website/docs/api/plugin-methods/extend-infrastructure.md @@ -8,7 +8,9 @@ Docusaurus has some infrastructure like hot reloading, CLI, and swizzling, that ## `getPathsToWatch()` {#getPathsToWatch} -Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site. Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server. +Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site. + +Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server. Example: @@ -27,7 +29,7 @@ module.exports = function (context, options) { ## `extendCli(cli)` {#extendCli} -Register an extra command to enhance the CLI of Docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander/v/5.1.0) object. +Register an extra command to enhance the CLI of Docusaurus. `cli` is a [commander](https://www.npmjs.com/package/commander/v/5.1.0) object. :::caution @@ -55,7 +57,7 @@ module.exports = function (context, options) { ## `getThemePath()` {#getThemePath} -Returns the path to the directory where the theme components can be found. When your users calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components. +Returns the path to the directory where the theme components can be found. When your users call `swizzle`, `getThemePath` is called and its returned path is used to find your theme components. For example, your `getThemePath` can be: @@ -74,7 +76,7 @@ module.exports = function (context, options) { ## `getTypeScriptThemePath()` {#getTypeScriptThemePath} -Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make path returned by `getThemePath()` be the compiled JavaScript output. +Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement for `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make the path returned by `getThemePath()` be the compiled JavaScript output. :::tip @@ -108,7 +110,7 @@ module.exports = function (context, options) { **This is a static method, not attached to any plugin instance.** -Returns a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all component are considered stable. +Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without `--danger`. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all components are considered stable. ```js {0-12} title="my-theme/src/index.js" const swizzleAllowedComponents = [ diff --git a/website/docs/api/plugin-methods/i18n-lifecycles.md b/website/docs/api/plugin-methods/i18n-lifecycles.md index aa3a15f215..83f1087cc4 100644 --- a/website/docs/api/plugin-methods/i18n-lifecycles.md +++ b/website/docs/api/plugin-methods/i18n-lifecycles.md @@ -103,7 +103,7 @@ module.exports = function (context, options) { Themes using the `` API can provide default code translation messages. -It should return messages in `Record`, where keys are translation ids and values are messages (without the description) localized using the site current locale. +It should return messages in `Record`, where keys are translation ids and values are messages (without the description) localized using the site's current locale. Example: diff --git a/website/docs/api/plugin-methods/lifecycle-apis.md b/website/docs/api/plugin-methods/lifecycle-apis.md index dc088d480c..de4f7677d7 100644 --- a/website/docs/api/plugin-methods/lifecycle-apis.md +++ b/website/docs/api/plugin-methods/lifecycle-apis.md @@ -5,7 +5,7 @@ toc_max_heading_level: 4 # Lifecycle APIs -During build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files. +During the build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files. ## `async loadContent()` {#loadContent} @@ -63,9 +63,9 @@ type Module = #### `createData(name: string, data: any): Promise` {#createData} -A declarative callback to create static data (generally json or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path. +A declarative callback to create static data (generally JSON or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path. -For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`: +For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`: ```jsx title="website/src/components/Friends.js" import React from 'react'; @@ -105,7 +105,7 @@ export default function friendsPlugin(context, options) { #### `setGlobalData(data: any): void` -This function permits to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout. +This function permits one to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout. This data becomes accessible to your client-side/theme code through the [`useGlobalData`](../../docusaurus-core.md#useGlobalData) and [`usePluginData`](../../docusaurus-core.md#usePluginData) hooks. @@ -115,7 +115,7 @@ Global data is... global: its size affects the loading time of all pages of your ::: -For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`: +For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`: ```jsx title="website/src/components/Friends.js" import React from 'react'; @@ -174,7 +174,7 @@ The API of `configureWebpack` will be modified in the future to accept an object You may use them to return your webpack configures conditionally. -For example, this plugin below modify the webpack config to transpile `.foo` file. +For example, this plugin below modify the webpack config to transpile `.foo` files. ```js title="docusaurus-plugin/src/index.js" module.exports = function (context, options) { @@ -300,7 +300,7 @@ Inject head and/or body HTML tags to Docusaurus generated HTML. `injectHtmlTags` will be called both with the content loaded by the plugin. -```typescript +```ts function injectHtmlTags(): { headTags?: HtmlTags; preBodyTags?: HtmlTags; @@ -369,7 +369,7 @@ module.exports = function (context, options) { ## `getClientModules()` {#getClientModules} -Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI. +Returns an array of paths to the modules that are to be imported into the client bundle. These modules are imported globally before React even renders the initial UI. As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user: diff --git a/website/docs/api/plugin-methods/static-methods.md b/website/docs/api/plugin-methods/static-methods.md index 8135f7599b..c3bb4e730f 100644 --- a/website/docs/api/plugin-methods/static-methods.md +++ b/website/docs/api/plugin-methods/static-methods.md @@ -8,7 +8,7 @@ Static methods are not part of the plugin instance—they are attached to the co ## `validateOptions({options, validate})` {#validateOptions} -Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during initialization. +Returns validated and normalized options for the plugin. This method is called before the plugin is initialized. You must return the options since they will be passed to the plugin during initialization. ### `options` {#options} @@ -16,7 +16,7 @@ Return validated and normalized options for the plugin. This method is called be ### `validate` {#validate} -`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as argument, returns validated and normalized options. `validate` will automatically handle error and validation config. +`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config. :::tip @@ -70,7 +70,7 @@ Return validated and normalized configuration for the theme. ### `validate` {#validate-1} -`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as argument, returns validated and normalized options. `validate` will automatically handle error and validation config. +`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config. :::tip diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md index e737f0ea7d..bae9d3db81 100644 --- a/website/docs/api/plugins/plugin-content-blog.md +++ b/website/docs/api/plugins/plugin-content-blog.md @@ -66,7 +66,7 @@ Accepted fields: -```typescript +```ts type EditUrlFunction = (params: { blogDirPath: string; blogPath: string; @@ -191,9 +191,9 @@ module.exports = { }; ``` -## Markdown Frontmatter {#markdown-frontmatter} +## Markdown front matter {#markdown-front-matter} -Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. +Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side. Accepted fields: @@ -201,7 +201,7 @@ Accepted fields: | Name | Type | Default | Description | | --- | --- | --- | --- | -| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. | +| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` front matter fields, even for single author blog posts. | | `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. | | `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. | | `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. | @@ -220,7 +220,7 @@ Accepted fields: -```typescript +```ts type Tag = string | {label: string; permalink: string}; // An author key references an author from the global plugin authors.yml file @@ -234,13 +234,13 @@ type Author = { image_url?: string; }; -// The FrontMatter authors field allows various possible shapes +// The front matter authors field allows various possible shapes type Authors = AuthorKey | Author | (AuthorKey | Author)[]; ``` Example: -```yml +```md --- title: Welcome Docusaurus v2 authors: @@ -255,6 +255,7 @@ description: This is my first post on Docusaurus 2. image: https://i.imgur.com/mErPwqL.png hide_table_of_contents: false --- + A Markdown blog post ``` diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 47c241b821..87d5348d85 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -63,7 +63,7 @@ Accepted fields: -```typescript +```ts type EditUrlFunction = (params: { version: string; versionDocsDirPath: string; @@ -236,9 +236,9 @@ module.exports = { }; ``` -## Markdown Frontmatter {#markdown-frontmatter} +## Markdown front matter {#markdown-front-matter} -Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side. +Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side. Accepted fields: @@ -252,7 +252,7 @@ Accepted fields: | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. | | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). | | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. | -| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. | +| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. | | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. | | `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. | | `toc_max_heading_level` | `number` | `3` | The max heading level shown in the table of contents. Must be between 2 and 6. | @@ -268,13 +268,13 @@ Accepted fields: -```typescript +```ts type Tag = string | {label: string; permalink: string}; ``` Example: -```yml +```md --- id: doc-markdown title: Docs Markdown Features @@ -291,6 +291,7 @@ keywords: image: https://i.imgur.com/mErPwqL.png slug: /myDoc --- + # Markdown Features My Document Markdown content diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx index b71d166197..f61cbad055 100644 --- a/website/docs/blog.mdx +++ b/website/docs/blog.mdx @@ -16,7 +16,7 @@ Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content ## Initial setup {#initial-setup} -To setup your site's blog, start by creating a `blog` directory. +To set up your site's blog, start by creating a `blog` directory. Then, add an item link to your blog within `docusaurus.config.js`: @@ -41,7 +41,7 @@ To publish in the blog, create a Markdown file within the blog directory. For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`: -```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md" +```md title="website/blog/2019-09-05-hello-docusaurus-v2.md" --- title: Welcome Docusaurus v2 description: This is my first post on Docusaurus 2. @@ -59,6 +59,7 @@ tags: [hello, docusaurus-v2] image: https://i.imgur.com/mErPwqL.png hide_table_of_contents: false --- + Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/). @@ -72,7 +73,7 @@ A whole bunch of exploration to follow. Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`. -This naming convention is optional, and you can provide the date as FrontMatter. +This naming convention is optional, and you can provide the date as front matter.
Example supported patterns @@ -104,10 +105,11 @@ The blog's index page (by default, it is at `/blog`) is the _blog list page_, wh 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 +```md --- title: Truncation Example --- + All these will be part of the blog post summary. Even this. @@ -121,7 +123,7 @@ Not this. Or this. ``` -By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add meta description to the blog list page for better SEO: +By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add a meta description to the blog list page for better SEO: ```js title="docusaurus.config.js" module.exports = { @@ -147,7 +149,7 @@ module.exports = { The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed. -You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts": +You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may rather make it say "All posts": ```js title="docusaurus.config.js" module.exports = { @@ -169,11 +171,11 @@ module.exports = { ## Blog post authors {#blog-post-authors} -Use the `authors` FrontMatter field to declare blog post authors. +Use the `authors` front matter field to declare blog post authors. ### Inline authors {#inline-authors} -Blog post authors can be declared directly inside the FrontMatter: +Blog post authors can be declared directly inside the front matter: ````mdx-code-block @@ -218,7 +220,7 @@ This option works best to get started, or for casual, irregular authors. :::info -Prefer usage of the `authors` FrontMatter, but the legacy `author_*` FrontMatter remains supported: +Prefer using the `authors` front matter, but the legacy `author_*` front matter remains supported: ```yml title="my-blog-post.md" --- @@ -233,9 +235,9 @@ author_image_url: https://github.com/JoelMarcey.png ### Global authors {#global-authors} -For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post. +For regular blog post authors, it can be tedious to maintain authors' information inlined in each blog post. -It is possible declare those authors globally in a configuration file: +It is possible to declare those authors globally in a configuration file: ```yml title="website/blog/authors.yml" jmarcey: @@ -257,7 +259,7 @@ Use the `authorsMapPath` plugin option to configure the path. JSON is also suppo ::: -In blog posts FrontMatter, you can reference the authors declared in the global configuration file: +In blog posts front matter, you can reference the authors declared in the global configuration file: ````mdx-code-block @@ -393,7 +395,7 @@ module.exports = { Usage: -```yml "my-blog-post.md" +```md "my-blog-post.md" --- hide_reading_time: true --- @@ -552,7 +554,7 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t :::tip -There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborated explanation of `routeBasePath`. +There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborate explanation of `routeBasePath`. ::: diff --git a/website/docs/browser-support.md b/website/docs/browser-support.md index 87e9e1f2a2..4f374c7e9d 100644 --- a/website/docs/browser-support.md +++ b/website/docs/browser-support.md @@ -13,7 +13,7 @@ The browser list by default is provided through the `package.json` file as a roo :::caution -On old browsers, the compiled output will use unsupported (too recent) JS syntax, causing React to fail to initialize and ending up with a static website with only HTML/CSS and no JS. +On old browsers, the compiled output will use unsupported (too recent) JS syntax, causing React to fail to initialize and end up with a static website with only HTML/CSS and no JS. ::: @@ -53,23 +53,29 @@ You can "evaluate" any config with the `browserlist` cli to obtain the actual li npx browserslist --env="production" ``` -The output are all browsers supported in production. Below is the output in May, 2021: +The output is all browsers supported in production. Below is the output in December 2021: ```text -and_chr 89 +and_chr 95 and_uc 12.12 -chrome 89 -chrome 88 -chrome 87 -edge 89 -edge 88 -firefox 86 +chrome 95 +chrome 94 +chrome 93 +chrome 92 +edge 95 +edge 94 +firefox 93 +firefox 92 ie 11 -ios_saf 14.0-14.5 -ios_saf 13.4-13.7 -safari 14 +ios_saf 15 +ios_saf 14.5-14.8 +ios_saf 14.0-14.4 +ios_saf 12.2-12.5 +opera 79 +safari 15 +safari 14.1 safari 13.1 -samsung 13.0 +samsung 15.0 ``` ## Read more {#read-more} diff --git a/website/docs/cli.md b/website/docs/cli.md index 9ea0d48af1..a491f7f618 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -45,7 +45,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https | --- | --- | --- | | `--port` | `3000` | Specifies the port of the dev server. | | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. | -| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). | +| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). | | `--no-open` | `false` | Do not open automatically the page in the browser. | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). | @@ -66,7 +66,7 @@ There are multiple ways to obtain a certificate. We will use [mkcert](https://gi 3. Start the app with Docusaurus HTTPS env variables: -```shell +```bash HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start ``` @@ -110,7 +110,7 @@ npm run swizzle @docusaurus/theme-classic DocSidebar Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme. -`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle ` without `componentName` lists all the components available for swizzling. +`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle [themeName]` without `componentName` lists all the components available for swizzling. #### Options {#options-2} @@ -149,7 +149,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the | Name | Default | Description | | --- | --- | --- | | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | -| `--skip-build` | `false` | Deploy website without building it. This may be useful when using custom deploy script. | +| `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir} @@ -181,7 +181,7 @@ By default, the files are written in `website/i18n//...`. | `--locale` | `` | Define which locale folder you want to write translations the JSON files in | | `--override` | `false` | Override existing translation messages | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | -| `--messagePrefix` | `''` | Allows to add a prefix to each translation message, to help you highlight untranslated strings | +| `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings | ### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir} diff --git a/website/docs/configuration.md b/website/docs/configuration.md index c10a1692c9..c040630179 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -5,9 +5,9 @@ title: Configuration import TOCInline from '@theme/TOCInline'; -Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site. +Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. -Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site. +Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site. ## What goes into a `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs} @@ -23,9 +23,9 @@ For exact reference to each of the configurable fields, you may refer to [**`doc ### Site metadata {#site-metadata} -Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl` and `favicon`. +Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl`, and `favicon`. -They are used in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files. +They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files. ### Deployment configurations {#deployment-configurations} @@ -215,7 +215,7 @@ If you just want to use those fields on the client side, you could create your o ## Customizing Babel Configuration {#customizing-babel-configuration} -For new Docusaurus projects, we automatically generated a `babel.config.js` in project root. +For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root. ```js title="babel.config.js" module.exports = { @@ -223,4 +223,4 @@ module.exports = { }; ``` -Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver. +Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server. diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 91372c82db..67a558c0c6 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -25,7 +25,7 @@ A Docusaurus site is statically rendered, and it can generally work without Java ## Configuration {#configuration} -The following parameters are required in `docusaurus.config.js` in order for Docusaurus to optimize routing and serve files from the correct location: +The following parameters are required in `docusaurus.config.js` to optimize routing and serve files from the correct location: | Name | Description | | --- | --- | @@ -34,7 +34,7 @@ The following parameters are required in `docusaurus.config.js` in order for Doc ## Testing your Build Locally {#testing-build-locally} -It is important to test your build locally before deploying to production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that: +It is important to test your build locally before deploying it for production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that: ```bash npm2yarn npm run serve @@ -70,8 +70,8 @@ If you are unsure of which one to choose, ask the following questions: How much resource (person-hours, money) am I willing to invest in this? -- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services is almost never free, and setting up an on-site server and connecting it to the WAN can be more costly. -- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quota even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details. +- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services are almost never free, and setting up an on-site server and connecting it to the WAN can be even more costly. +- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quotas even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details. - 🟡 The GitHub Pages deployment workflow can be tedious to set up. (Evidence: see the length of [Deploying to GitHub Pages](#deploying-to-github-pages)!) However, this service (including build and deployment) is always free for public repositories, and we have detailed instructions to help you make it work.
@@ -192,7 +192,7 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu ### Overview {#github-pages-overview} -Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively. +Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial, they will be referred to as **"source"** and **"deployment"**, respectively. Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`. @@ -296,7 +296,7 @@ cmd /C 'set "GIT_USER=" && yarn deploy' Beginning in August 2021, GitHub requires every command-line sign-in to use the **personal access token** instead of the password. When GitHub prompts for your password, enter the PAT instead. See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for more information. -Alternatively, you can use SSH (`USE_SSH=true`) to login. +Alternatively, you can use SSH (`USE_SSH=true`) to log in. ::: @@ -309,7 +309,7 @@ The workflow examples below assume your website source resides in the `main` bra Our goal is that: 1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`. -2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new built output will be served on the GitHub Pages site. This job will be called `deploy`. +2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`. Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below: @@ -571,10 +571,10 @@ steps: 1. Create a new ssh key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project. 2. Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). -3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in our public key you just generated. -4. Open your Drone.io dashboard and login. The URL looks like `https://cloud.drone.io/USERNAME/REPO`. +3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in the public key you just generated. +4. Open your Drone.io dashboard and log in. The URL looks like `https://cloud.drone.io/USERNAME/REPO`. 5. Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated. -6. Create a `.drone.yml` on the root of your repository with below text. +6. Create a `.drone.yml` on the root of your repository with the below text. ```yml title=".drone.yml" kind: pipeline @@ -602,11 +602,11 @@ Now, whenever you push a new tag to GitHub, this trigger will start the drone CI ## Deploying to Render {#deploying-to-render} -[Render](https://render.com) offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto-deploy from your Git repo. Get started in just a few minutes by following [Render's guide to deploying Docusaurus](https://render.com/docs/deploy-docusaurus). +[Render](https://render.com) offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN, and continuous auto-deploy from your Git repo. Get started in just a few minutes by following [Render's guide to deploying Docusaurus](https://render.com/docs/deploy-docusaurus). ## Deploying to Qovery {#deploying-to-qovery} -[Qovery](https://www.qovery.com) is a fully-managed cloud platform that runs on your AWS, Digital Ocean and Scaleway account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. +[Qovery](https://www.qovery.com) is a fully-managed cloud platform that runs on your AWS, Digital Ocean, and Scaleway account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. 1. Create a Qovery account. Visit the [Qovery dashboard](https://console.qovery.com) to create an account if you don't already have one. 2. Create a project. @@ -637,13 +637,13 @@ That's it. Watch the status and wait till the app is deployed. To open the appli 2. Select the project to deploy. - If you are logged in to Hostman with your GitHub, GitLab or Bitbucket account, at this point you will see the repository with your projects, including the private ones. + If you are logged in to Hostman with your GitHub, GitLab, or Bitbucket account, at this point you will see the repository with your projects, including the private ones. - Choose the project you want to deploy. It must contain the directory with the project’s files (usually it is website or my-website). + Choose the project you want to deploy. It must contain the directory with the project's files (e.g. `website`). To access a different repository, click **Connect another repository**. - If you didn’t use your Git account credentials to log in, you’ll be able to access the necessary account now, and then select the project. + If you didn't use your Git account credentials to log in, you'll be able to access the necessary account now, and then select the project. 3. Configure the build settings. @@ -686,7 +686,7 @@ Deploy your app in a matter of seconds using surge with the following steps: surge build/ ``` -First-time users of Surge would be prompted to create an account from the command line(happens only once). +First-time users of Surge would be prompted to create an account from the command line (which happens only once). Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given (which can be edited). diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index cab72df81c..dd2eaadbfb 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -49,7 +49,7 @@ Docusaurus uses this component to catch errors within the theme's layout, and al :::note -This component doesn't catch build-time errors, and only protects against client-side render errors that can happen when using stateful React components. +This component doesn't catch build-time errors and only protects against client-side render errors that can happen when using stateful React components. ::: @@ -135,9 +135,15 @@ The target location to navigate to. Example: `/docs/introduction`. ``` +:::tip + +Prefer this component to vanilla `` tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use ``. + +::: + ### `` {#redirect} -Rendering a `` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props. +Rendering a `` will navigate to a new location. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props. Example usage: @@ -158,11 +164,11 @@ const Home = () => { ### `` {#browseronly} -The `` component permits to render React components only in the browser, after the React app has hydrated. +The `` component permits to render React components only in the browser after the React app has hydrated. :::tip -Use it for integrating with code that can't run in Node.js, because `window` or `document` objects are being accessed. +Use it for integrating with code that can't run in Node.js, because the `window` or `document` objects are being accessed. ::: @@ -249,20 +255,20 @@ export default function VisitMyWebsiteMessage() { When [localizing your site](./i18n/i18n-introduction.md), the `` component will allow providing **translation support to React components**, such as your homepage. The `` component supports [interpolation](#interpolate). -The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/[locale]`. +The translation strings will statically extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and a `code.json` translation file will be created in `website/i18n/[locale]`. :::note The `` props **must be hardcoded strings**. -Apart the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work. +Apart from the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work. ::: #### Props {#translate-props} - `children`: untranslated string in the default site locale (can contain [interpolation placeholders](#interpolate)) -- `id`: optional value to use as key in JSON translation files +- `id`: optional value to be used as the key in JSON translation files - `description`: optional text to help the translator - `values`: optional object containing interpolation placeholder values @@ -302,7 +308,7 @@ export default function Home() { :::note -You can even omit a children prop and specify a translation string in your `code.json` file manually after running the `docusaurus write-translations` CLI command. +You can even omit the children prop and specify a translation string in your `code.json` file manually after running the `docusaurus write-translations` CLI command. ```jsx @@ -314,7 +320,7 @@ You can even omit a children prop and specify a translation string in your `code ### `useDocusaurusContext` {#useDocusaurusContext} -React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata. +React hook to access Docusaurus Context. The context contains the `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md) and some additional site metadata. ```ts type DocusaurusPluginVersionInformation = @@ -368,6 +374,12 @@ const MyComponent = () => { }; ``` +:::note + +The `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. + +::: + ### `useIsBrowser` {#useIsBrowser} Returns `true` when the React app has successfully hydrated in the browser. @@ -376,9 +388,7 @@ Returns `true` when the React app has successfully hydrated in the browser. Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic. -The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). - -Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). +The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). ::: @@ -450,7 +460,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url. -- `withBaseUrl`: useful if you need to add base urls to multiple urls at once. +- `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once. ```jsx import React from 'react'; @@ -470,11 +480,11 @@ const Component = () => { React hook to access Docusaurus global data created by all the plugins. -Global data is namespaced by plugin name, and plugin id. +Global data is namespaced by plugin name then by plugin ID. :::info -Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data. +Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data. ::: @@ -511,7 +521,7 @@ Inspect your site's global data at `./docusaurus/globalData.json` Access global data created by a specific plugin instance. -This is the most convenient hook to access plugin global data, and should be used most of the time. +This is the most convenient hook to access plugin global data and should be used most of the time. `pluginId` is optional if you don't use multi-instance plugins. @@ -646,7 +656,7 @@ export default function Home() { ### `ExecutionEnvironment` {#executionenvironment} -A module which exposes a few boolean variables to check the current rendering environment. +A module that exposes a few boolean variables to check the current rendering environment. :::caution diff --git a/website/docs/guides/creating-pages.md b/website/docs/guides/creating-pages.md index 7ef75e6e95..a2c0cef4c7 100644 --- a/website/docs/guides/creating-pages.md +++ b/website/docs/guides/creating-pages.md @@ -7,7 +7,7 @@ sidebar_label: Pages In this section, we will learn about creating pages in Docusaurus. -This is useful for creating **one-off standalone pages** like a showcase page, playground page or support page. +This is useful for creating **one-off standalone pages** like a showcase page, playground page, or support page. The functionality of pages is powered by `@docusaurus/plugin-content-pages`. @@ -27,6 +27,8 @@ Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-con ## Add a React page {#add-a-react-page} +React is used as the UI library to create pages. Every page component should export a React component, and you can leverage the expressiveness of React to build rich and interactive content. + Create a file `/src/pages/helloReact.js`: ```jsx title="/src/pages/helloReact.js" @@ -55,7 +57,7 @@ function Hello() { export default Hello; ``` -Once you save the file, the development server will automatically reload the changes. Now open `http://localhost:3000/helloReact`, you will see the new page you just created. +Once you save the file, the development server will automatically reload the changes. Now open `http://localhost:3000/helloReact` and you will see the new page you just created. Each page doesn't come with any styling. You will need to import the `Layout` component from `@theme/Layout` and wrap your contents within that component if you want the navbar and/or footer to appear. @@ -83,7 +85,7 @@ How are you? In the same way, a page will be created at `http://localhost:3000/helloMarkdown`. -Markdown pages are less flexible than React pages, because it always uses the theme layout. +Markdown pages are less flexible than React pages because it always uses the theme layout. Here's an [example Markdown page](/examples/markdownPageExample). @@ -102,14 +104,22 @@ If you are familiar with other static site generators like Jekyll and Next, this - `/src/pages/foo/test.js` → `[baseUrl]/foo/test` - `/src/pages/foo/index.js` → `[baseUrl]/foo/` -In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following: +In this component-based development era, it is encouraged to co-locate your styling, markup, and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following: - Add a `/src/pages/support.js` file - Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file. -The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). By default, any Markdown or Javascript file starting with `_` will be ignored, and no routes will be created for that file (see the `exclude` option). +The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. -```sh +:::note + +This is merely a recommended directory structure, and you will still need to manually import the CSS module file within your component module (`support/index.js`). + +::: + +By default, any Markdown or Javascript file starting with `_` will be ignored and no routes will be created for that file (see the `exclude` option). + +```bash my-website ├── src │ └── pages @@ -124,14 +134,10 @@ my-website :::caution -All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the `exclude` option (by default, files prefixed with `_`, test files(`.test.js`) and files in `__tests__` directory are not turned into pages). +All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the `exclude` option (by default, files prefixed with `_`, test files(`.test.js`), and files in `__tests__` directory are not turned into pages). ::: -## Using React {#using-react} - -React is used as the UI library to create pages. Every page component should export a React component, and you can leverage on the expressiveness of React to build rich and interactive content. - -## Duplicate Routes {#duplicate-routes} +### Duplicate Routes {#duplicate-routes} You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run `yarn start` or `yarn build`, but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes. diff --git a/website/docs/guides/docs/docs-create-doc.mdx b/website/docs/guides/docs/docs-create-doc.mdx index 4bc628d914..90a7b70df7 100644 --- a/website/docs/guides/docs/docs-create-doc.mdx +++ b/website/docs/guides/docs/docs-create-doc.mdx @@ -10,16 +10,16 @@ Create a Markdown file, `greeting.md`, and place it under the `docs` directory. ```bash website # root directory of your site ├── docs -│   └── greeting.md +│ └── greeting.md ├── src -│   └── pages +│ └── pages ├── docusaurus.config.js ├── ... ``` At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site. -```yml +```md --- id: greeting title: Hello @@ -35,7 +35,7 @@ will show up on the table of contents on the upper right So that your users will know what this page is all about without scrolling down or even without reading too much. -### Only h2 and h3 will be in the toc by default. +### Only h2 and h3 will be in the TOC by default. You can configure the TOC heading levels either per-document or in the theme configuration. @@ -69,9 +69,9 @@ will show up on the table of contents on the upper right So that your users will know what this page is all about without scrolling down or even without reading too much. -

Only h2 and h3 will be in the toc by default.

+

Only h2 and h3 will be in the TOC by default.

-You can configure the TOC heading levels either per-document or in the theme configuration. +You can configure the TOC heading levels either per document or in the theme configuration. The headers are well-spaced so that the hierarchy is clear. @@ -100,7 +100,7 @@ Read more about [importing partial pages](../markdown-features/markdown-features Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels: -```yml "your-doc-page.md" +```md "your-doc-page.md" --- id: doc-with-tags title: A doc with tags diff --git a/website/docs/guides/docs/docs-introduction.md b/website/docs/guides/docs/docs-introduction.md index 793c5468f7..426186a72b 100644 --- a/website/docs/guides/docs/docs-introduction.md +++ b/website/docs/guides/docs/docs-introduction.md @@ -27,22 +27,24 @@ website # Root directory of your site └── hello.md ``` -However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. +However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. -```yml +```md --- id: part1 --- + Lorem ipsum ``` If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`). -```yml +```md --- id: part1 slug: part1.html --- + Lorem ipsum ``` @@ -57,13 +59,14 @@ It is possible to use: ## Home page docs {#home-page-docs} -If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter: +If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter: -```yml +```md --- id: my-home-doc slug: / --- + Lorem ipsum ``` @@ -83,7 +86,7 @@ example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-m ... ``` -All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root? +All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting them at the root? Assume that you have the following in your configuration: @@ -126,15 +129,16 @@ module.exports = { }; ``` -Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute. +Note that you **don't necessarily have to give up on using the blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute. Don't forget to put some page at the root (`https://example.com/`) through adding the front matter: -```yml title="docs/intro.md" +```md title="docs/intro.md" --- # highlight-next-line slug: / --- + This page will be the home page when users visit https://example.com/. ``` diff --git a/website/docs/guides/docs/docs-markdown-features.mdx b/website/docs/guides/docs/docs-markdown-features.mdx index eb5b7732a0..fe2660b212 100644 --- a/website/docs/guides/docs/docs-markdown-features.mdx +++ b/website/docs/guides/docs/docs-markdown-features.mdx @@ -5,11 +5,11 @@ description: Docusaurus Markdown features that are specific to the docs plugin slug: /docs-markdown-features --- -Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional docs-specific Markdown features. +Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features. -## Markdown frontmatter {#markdown-frontmatter} +## Markdown front matter {#markdown-front-matter} -Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter) +Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter). ## Referencing other documents {#referencing-other-documents} diff --git a/website/docs/guides/docs/docs-multi-instance.mdx b/website/docs/guides/docs/docs-multi-instance.mdx index 9b6d144a84..5433830491 100644 --- a/website/docs/guides/docs/docs-multi-instance.mdx +++ b/website/docs/guides/docs/docs-multi-instance.mdx @@ -9,7 +9,7 @@ The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../ :::note -This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. +This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar.md#using-multiple-sidebars), you can do so within one plugin. ::: @@ -26,7 +26,7 @@ If you build a cross-platform mobile SDK, you may have 2 documentations: - Android SDK documentation (`v1.0`, `v1.1`) - iOS SDK documentation (`v1.0`, `v2.0`) -In such case, you can use a distinct docs plugin instance per mobile SDK documentation. +In this case, you can use a distinct docs plugin instance per mobile SDK documentation. :::caution diff --git a/website/docs/guides/docs/sidebar.md b/website/docs/guides/docs/sidebar.md index a03e683734..927aa5f4e0 100644 --- a/website/docs/guides/docs/sidebar.md +++ b/website/docs/guides/docs/sidebar.md @@ -14,7 +14,7 @@ Creating a sidebar is useful to: - Group multiple **related documents** - **Display a sidebar** on each of those documents -- Provide a **paginated navigation**, with next/previous button +- Provide **paginated navigation**, with next/previous button To use sidebars on your Docusaurus site: @@ -58,7 +58,7 @@ You can also define your sidebars explicitly. A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks. -```typescript +```ts type Sidebar = // Normal syntax | SidebarItem[] @@ -108,7 +108,7 @@ This is a sidebars file that exports one sidebar, called `mySidebar`. It has thr A sidebars file can contain [**multiple sidebar objects**](#using-multiple-sidebars), identified by their object keys. -```typescript +```ts type SidebarsFile = { [sidebarID: string]: Sidebar; }; @@ -235,7 +235,7 @@ Note how the two consecutive category shorthands are compressed into one object ## Understanding sidebar items {#understanding-sidebar-items} -We have introduced three types of item types in the above example: `doc`, `category`, and `link`, whose usage are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later. +We have introduced three types of item types in the above example: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later. - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar - **[Link](#sidebar-item-link)**: link to any internal or external page @@ -247,7 +247,7 @@ We have introduced three types of item types in the above example: `doc`, `categ Use the `doc` type to link to a doc page and assign that doc to a sidebar: -```typescript +```ts type SidebarItemDoc = // Normal syntax | { @@ -283,7 +283,7 @@ module.exports = { }; ``` -If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has a higher precedence over the `label` key in the sidebar item. +If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. :::note @@ -295,7 +295,7 @@ A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't Use the `link` type to link to any page (internal or external) that is not a doc. -```typescript +```ts type SidebarItemLink = { type: 'link'; label: string; @@ -334,7 +334,7 @@ module.exports = { Use the `category` type to create a hierarchy of sidebar items. -```typescript +```ts type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. @@ -419,7 +419,7 @@ module.exports = { }; ``` -See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md). +See it in action on the [i18n introduction page](../../i18n/i18n-introduction.md). ##### Generated index page {#generated-index-page} @@ -445,7 +445,7 @@ module.exports = { }; ``` -See it in action in the [Docusaurus Guides pages](/docs/category/guides). +See it in action on the [Docusaurus Guides page](/docs/category/guides). :::tip @@ -504,7 +504,7 @@ The option in `sidebars.js` takes precedence over plugin configuration, so it is #### Expanded categories by default {#expanded-categories-by-default} -Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`: +Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`: ```js title="sidebars.js" module.exports = { @@ -551,7 +551,7 @@ When a category has `collapsed: true` but `collapsible: false` (either through ` Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category, and each file creates a doc link. -```typescript +```ts type SidebarItemAutogenerated = { type: 'autogenerated'; dirName: string; // Source folder to generate the sidebar slice from (relative to docs) @@ -576,7 +576,7 @@ module.exports = { An `autogenerated` item is converted by Docusaurus to a **sidebar slice** (also discussed in [category shorthands](#category-shorthand)): a list of items of type `doc` or `category`, so you can splice **multiple `autogenerated` items** from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
-A real world example +A real-world example Consider this file structure: ```bash @@ -736,11 +736,11 @@ Naming your introductory document `README.md` makes it show up when browsing the #### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata} -For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names). +For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names). **For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter. -```yaml title="docs/tutorials/tutorial-easy.md" +```md title="docs/tutorials/tutorial-easy.md" --- # highlight-start sidebar_position: 2 @@ -748,6 +748,7 @@ sidebar_label: Easy sidebar_class_name: green # highlight-end --- + # Easy Tutorial This is the easy tutorial! @@ -775,7 +776,7 @@ This is the easy tutorial! -```yaml title="docs/tutorials/_category_.yml" +```yml title="docs/tutorials/_category_.yml" position: 2.5 # float position is supported label: 'Tutorial' collapsible: true # make the category collapsible @@ -824,7 +825,7 @@ docs To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**. -By default, Docusaurus will **remove the number prefix** from the doc id, title, label and URL paths. +By default, Docusaurus will **remove the number prefix** from the doc id, title, label, and URL paths. :::caution @@ -874,7 +875,7 @@ module.exports = { **Re-use and enhance the default generator** instead of writing a generator from scratch: [the default generator we provide](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts) is 250 lines long. -**Add, update, filter, re-order** the sidebar items according to your use-case: +**Add, update, filter, re-order** the sidebar items according to your use case: ```js title="docusaurus.config.js" // highlight-start @@ -967,7 +968,7 @@ module.exports = { How does Docusaurus know which sidebar to display when browsing `commonDoc`? Answer: it doesn't, and we don't guarantee which sidebar it will pick. In this case, in order to remove the ambiguity, you can use the special `ref` sidebar item type. -The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link, but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored. +The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored. So you can turn the sidebars above into: @@ -1007,11 +1008,12 @@ module.exports = { The pagination next link on "windows" points to "linux", but that doesn't make sense: you would want readers to proceed to "getting started" after installation. In this case, you can set the pagination manually: -```yml title="windows.md" +```md title="windows.md" --- # highlight-next-line pagination_next: getting-started --- + # Installation on Windows ``` @@ -1035,7 +1037,7 @@ To pass in custom props to a swizzled sidebar item, add the optional `customProp ## Complex sidebars example {#complex-sidebars-example} -Real-world example from the Docusaurus site: +A real-world example from the Docusaurus site: ```mdx-code-block import CodeBlock from '@theme/CodeBlock'; diff --git a/website/docs/guides/docs/versioning.md b/website/docs/guides/docs/versioning.md index 451e42d582..f2f4a7edd2 100644 --- a/website/docs/guides/docs/versioning.md +++ b/website/docs/guides/docs/versioning.md @@ -18,7 +18,7 @@ To better understand how versioning works and see if it suits your needs, you ca ## Directory structure {#directory-structure} -```shell +```bash website ├── sidebars.json # sidebar for the current docs version ├── docs # docs directory for the current docs version @@ -54,7 +54,7 @@ The table below explains how a versioned file maps to its version and the genera The files in the `docs` directory belong to the `current` docs version. -By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle. +By default, the `current` docs version is labeled as `Next` and hosted under `/docs/next/*`, but it is entirely configurable to fit your project's release lifecycle. ::: @@ -78,11 +78,11 @@ When tagging a new version, the document versioning mechanism will: ### Creating new docs {#creating-new-docs} 1. Place the new file into the corresponding version folder. -1. Include the reference for the new file into the corresponding sidebar file, according to version number. +2. Include the reference to the new file in the corresponding sidebar file according to the version number. **Current version docs** -```shell +```bash # The new file. docs/new.md @@ -92,7 +92,7 @@ sidebar.js **Older version docs** -```shell +```bash # The new file. versioned_docs/version-1.0.0/new.md @@ -103,7 +103,7 @@ versioned_sidebars/version-1.0.0-sidebars.json ### Linking docs {#linking-docs} - Remember to include the `.md` extension. -- Files will be linked to correct corresponding version. +- Files will be linked to the correct corresponding version. - Relative paths work as well. ```md @@ -156,9 +156,9 @@ There are different ways to manage versioning, but two very common patterns are: - You release v1, and start immediately working on v2 (including its docs) - You release v1, and will maintain it for some time before thinking about v2. -Docusaurus defaults work great for the first usecase. +Docusaurus defaults work great for the first use case. -**For the 2nd usecase**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead: +**For the 2nd use case**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead: ```json { @@ -178,17 +178,23 @@ See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for mo ### Version your documentation only when needed {#version-your-documentation-only-when-needed} -For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1. +For example, you are building documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1. Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files. ### Keep the number of versions small {#keep-the-number-of-versions-small} -As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation versions with the lowest being `22.X`. Keep it small 😊 +As a good rule of thumb, try to keep the number of your versions below 10. You will **very likely** to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `27.4`, and only maintains several latest documentation versions with the lowest being `25.X`. Keep it small 😊 + +:::tip archive older versions + +If you deploy your site on a Jamstack provider (e.g. [Netlify](../../deployment.mdx)), the provider will save each production build as a snapshot under an immutable URL. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docusaurus website both use such pattern to keep the number of actively built versions low. + +::: ### Use absolute import within the docs {#use-absolute-import-within-the-docs} -Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus, that points to the `website` directory. Example: +Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus that points to the `website` directory. Example: ```diff - import Foo from '../src/components/Foo'; @@ -197,7 +203,7 @@ Don't use relative paths import within the docs. Because when we cut a version t ### Global or versioned colocated assets {#global-or-versioned-colocated-assets} -You should decide if assets like images and files are per version or shared between versions +You should decide if assets like images and files are per-version or shared between versions. If your assets should be versioned, put them in the docs version, and use relative paths: diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx index 65ba905c28..b0c11acc73 100644 --- a/website/docs/guides/markdown-features/markdown-features-assets.mdx +++ b/website/docs/guides/markdown-features/markdown-features-assets.mdx @@ -20,7 +20,7 @@ Let's imagine the following file structure: ## Images {#images} -You can display images in three different ways: Markdown syntax, JSX require or ES imports syntax. +You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax. Display images using simple Markdown syntax: @@ -57,7 +57,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal ## Files {#files} -In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc. +In the same way, you can link to existing assets by requiring them and using the returned url in videos, links, etc. ```mdx # My Markdown page @@ -95,7 +95,7 @@ import DocusaurusSvg from '@site/static/img/docusaurus.svg'; -This can be useful, if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme. +This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme. ```jsx import DocusaurusSvg from './docusaurus.svg'; @@ -154,5 +154,5 @@ If a Markdown link or image has an absolute path, the path will be seen as a fil Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require` call instead of staying as a URL. This is desirable in two regards: -1. You don't have to worry about base URL, which Docusaurus will take care of when serving the asset; +1. You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset; 2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance. diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index 27ddb18af6..3150f91640 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -9,7 +9,7 @@ Code blocks within documentation are super-powered 💪. ## Code title {#code-title} -You can add a title to the code block by adding `title` key after the language (leave a space between them). +You can add a title to the code block by adding a `title` key after the language (leave a space between them). ```jsx title="/src/components/HelloCodeTitle.js" function HelloCodeTitle(props) { @@ -25,7 +25,7 @@ function HelloCodeTitle(props) { ## Syntax highlighting {#syntax-highlighting} -Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX. +Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX. ```jsx console.log('Every repo must come with a mascot.'); @@ -65,9 +65,9 @@ Some popular languages like Java, C#, or PHP are not enabled by default. ::: -To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages. +To add syntax highlighting for any of the other [Prism-supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages. -For example, if you want to add highlighting for the `powershell` language: +For example, if you want to add highlighting for the PowerShell language: ```js {5} title="docusaurus.config.js" module.exports = { @@ -148,7 +148,7 @@ html[data-theme='dark'] .docusaurus-highlight-code-line { } ``` -### Multiple line highlighting {#multiple-line-highlighting} +### Multiple-line highlighting {#multiple-line-highlighting} To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details. @@ -365,7 +365,7 @@ function MyPlayground(props) { ## Using JSX markup in code blocks -Code blocks in Markdown always preserves its content as plain text, meaning you can't do something like: +Code block in Markdown always preserves its content as plain text, meaning you can't do something like: ```ts type EditUrlFunction = (params: { @@ -407,11 +407,11 @@ Syntax highlighting only works on plain strings. Docusaurus will not attempt to ## Multi-language support code blocks {#multi-language-support-code-blocks} -With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component. +With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switch between them using a tabs component. Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well. -The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is **intentional**. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX. +The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block are **intentional**. This is a current limitation of MDX: you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX. ````jsx import Tabs from '@theme/Tabs'; diff --git a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx index ee0c03a53b..fa987eb1fe 100644 --- a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx +++ b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx @@ -48,7 +48,7 @@ My text This `` declaration has been added to the current Markdown doc, as a demo. -Open your browser DevTools and check how this page's metadata have been affected. +Open your browser DevTools and check how this page's metadata has been affected. ::: diff --git a/website/docs/guides/markdown-features/markdown-features-headings.mdx b/website/docs/guides/markdown-features/markdown-features-headings.mdx index c52a7975ea..a4beb7bba3 100644 --- a/website/docs/guides/markdown-features/markdown-features-headings.mdx +++ b/website/docs/guides/markdown-features/markdown-features-headings.mdx @@ -17,11 +17,11 @@ You can use regular Markdown headings. #### Level 4 title ``` -Markdown headings appear as a table-of-contents entry. +Markdown headings appear as a table of contents entry. ## Heading ids {#heading-ids} -Each heading has an id that can be automatically generated, or explicitly specified. +Each heading has an id that can be automatically generated or explicitly specified. Heading ids allow you to link to a specific document heading in Markdown or JSX: @@ -35,9 +35,7 @@ Heading ids allow you to link to a specific document heading in Markdown or JSX: ### Generated ids {#generated-ids} -By default, Docusaurus will generate heading ids for you, based on the heading text. - -`### Hello World` will have id `hello-world`. +By default, Docusaurus will generate heading ids for you, based on the heading text. For example, `### Hello World` will have id `hello-world`. Generated ids have **some limits**: diff --git a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx b/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx index 3726f04842..55e3e21e0a 100644 --- a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx @@ -13,7 +13,7 @@ But it is also possible to display an inline table of contents directly inside a ## Full table of contents {#full-table-of-contents} -The `toc` variable is available in any MDX document, and contains all the headings of a MDX document. +The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel`. @@ -71,7 +71,7 @@ import TOCInline from '@theme/TOCInline'; :::caution -The underlying content is just an example to have more table-of-contents items available in current page. +Below is just some dummy content to have more table of contents items available on the current page. ::: diff --git a/website/docs/guides/markdown-features/markdown-features-intro.mdx b/website/docs/guides/markdown-features/markdown-features-intro.mdx index da448446f4..c07ab7d2e5 100644 --- a/website/docs/guides/markdown-features/markdown-features-intro.mdx +++ b/website/docs/guides/markdown-features/markdown-features-intro.mdx @@ -12,9 +12,9 @@ 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. +Docusaurus 2 uses modern tooling to help you compose your interactive documentation 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. +In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example. :::important @@ -31,7 +31,7 @@ The [standard Markdown syntax](https://daringfireball.net/projects/markdown/synt ```md ### My Doc Section -Hello world message with some **bold** text, some _italic_ text and a [link](/) +Hello world message with some **bold** text, some _italic_ text, and a [link](/) ![img alt](/img/docusaurus.png) ``` @@ -53,10 +53,14 @@ Hello world message with some **bold** text, some _italic_ text and a [link](/) Markdown quotes are beautifully styled: ```md -> This is a quote +> Easy to maintain open source documentation websites. +> +> — Docusaurus ``` -> This is a quote +> Easy to maintain open source documentation websites. +> +> — Docusaurus ## Details diff --git a/website/docs/guides/markdown-features/markdown-features-plugins.mdx b/website/docs/guides/markdown-features/markdown-features-plugins.mdx index 4cb8fa3783..75d11797f0 100644 --- a/website/docs/guides/markdown-features/markdown-features-plugins.mdx +++ b/website/docs/guides/markdown-features/markdown-features-plugins.mdx @@ -8,13 +8,13 @@ slug: /markdown-features/plugins Sometimes, you may want to extend or tweak your Markdown syntax. For example: - How do I embed youtube videos using the image syntax (`![](https://youtu.be/yKNxeF4KMsY)`)? -- How do I style links that are on its own line differently, e.g., like a social card? +- How do I style links that are on their own lines differently, e.g., as a social card? - How do I make every page start with a copyright notice? And the answer is: create an MDX plugin! MDX has a built-in [plugin system](https://mdxjs.com/advanced/plugins/) that can be used to customize how the Markdown files will be parsed and transformed to JSX. There are three typical use-cases of MDX plugins: - Using existing [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) or [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins); -- Creating remark/rehype plugins to tranform the elements generated by existing MDX syntax; +- Creating remark/rehype plugins to transform the elements generated by existing MDX syntax; - Creating remark/rehype plugins to introduce new syntaxes to MDX. If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms: @@ -24,7 +24,7 @@ If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-md :::tip -Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project. The [admonition](./markdown-features-admonitions.mdx) syntax that we offer is also generated by a [Remark plugin](https://github.com/elviswolcott/remark-admonitions), and you could do the same for your own use-case. +Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project. The [admonition](./markdown-features-admonitions.mdx) syntax that we offer is also generated by a [Remark plugin](https://github.com/elviswolcott/remark-admonitions), and you could do the same for your own use case. ::: @@ -41,7 +41,7 @@ These are all typical use-cases of Remark plugins, which can also be a source of ## Installing plugins {#installing-plugins} -An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as example. +An MDX plugin is usually an npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as an example. ```bash npm2yarn npm install --save remark-math@3 rehype-katex@4 @@ -56,9 +56,9 @@ There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules
How are remark-math and rehype-katex different? -In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transforms that to the JSX `...` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin. +In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transform that to the JSX `...` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin. -Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class, and uses $\KaTeX$ to parse and render the content to actual HTML. +Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class and uses $\KaTeX$ to parse and render the content to actual HTML.
@@ -112,7 +112,7 @@ module.exports = { }; ``` -You should check your plugin's documentation for options it supports. +You should check your plugin's documentation for the options it supports. ## Creating new rehype/remark plugins @@ -124,7 +124,7 @@ The writeup below is **not** meant to be a comprehensive guide to creating a plu ::: -For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate NPM package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` which operates on the AST. +For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate NPM package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` that operates on the AST. ```js "src/remark/section-prefix.js" const visit = require('unist-util-visit'); diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 8be1ae86fc..6096ffed99 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -17,7 +17,7 @@ Docusaurus has built-in support for [MDX v1](https://mdxjs.com/), which allows y :::note -While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. +While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the syntaxes are treated slightly differently by third-party tools. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. ::: @@ -86,7 +86,7 @@ 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/). In order to use `raw-loader`, first you need to install it in your project: +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`, you first need to install it in your project: ```bash npm2yarn npm install --save raw-loader @@ -116,7 +116,7 @@ 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: +You can also pass `title` prop to `CodeBlock` component in order for it to appear as header above your code block: ```jsx @@ -132,7 +132,7 @@ You have to use `` rather than the Markdown triple-backtick ` ``` `, :::warning -This feature is experimental and might be subject to API breaking changes in the future. +This feature is experimental and might be subject to breaking API changes in the future. ::: @@ -164,11 +164,11 @@ import PartialExample from './_markdown-partial-example.mdx';
``` -This way, you can reuse contents among multiple pages and avoid duplicating materials. +This way, you can reuse content among multiple pages and avoid duplicating materials. :::caution -The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)). +The table of contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)). ::: diff --git a/website/docs/guides/markdown-features/markdown-features-tabs.mdx b/website/docs/guides/markdown-features/markdown-features-tabs.mdx index 031264a85a..3517311da6 100644 --- a/website/docs/guides/markdown-features/markdown-features-tabs.mdx +++ b/website/docs/guides/markdown-features/markdown-features-tabs.mdx @@ -132,11 +132,11 @@ It is possible to only render the default tab with ``. The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default. -Docusaurus will throw an error if a `defaultValue` is provided for the `Tabs` but it refers to an non-existing value. If you want none of the tabs to be shown by default, use `defaultValue={null}`. +Docusaurus will throw an error if a `defaultValue` is provided for the `Tabs` but it refers to a non-existing value. If you want none of the tabs to be shown by default, use `defaultValue={null}`. ## Syncing tab choices {#syncing-tab-choices} -You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that `groupID` are globally-namespaced. +You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to change all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that group IDs are globally namespaced. ```jsx // highlight-next-line @@ -167,7 +167,7 @@ You may want choices of the same kind of tabs to sync with each other. For examp
``` -For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change. +For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group is chosen a value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups don't change. ```jsx @@ -195,7 +195,7 @@ For all tab groups that have the same `groupId`, the possible values do not need --- -Tab choices with different `groupId`s will not interfere with each other: +Tab choices with different group IDs will not interfere with each other: ```jsx // highlight-next-line @@ -227,7 +227,7 @@ Tab choices with different `groupId`s will not interfere with each other: ## Customizing tabs {#customizing-tabs} -You might want to customize the appearance of certain set of tabs. To do that you can pass the string in `className` prop and the specified CSS class will be added to the `Tabs` component: +You might want to customize the appearance of a certain set of tabs. You can pass the string in `className` prop, and the specified CSS class will be added to the `Tabs` component: ```jsx // highlight-next-line diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index f914ee2b3c..fe23e712a7 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -13,7 +13,7 @@ We document the usage of [Crowdin](https://crowdin.com/), as **one** possible ** :::caution -This is **not an endorsement of Crowdin** as the unique choice to translate a Docusaurus site, but it is successfully used by Facebook to translate documentation projects such as [Jest](https://jestjs.io/), [Docusaurus](https://docusaurus.io/) and [ReasonML](https://reasonml.github.io/). +This is **not an endorsement of Crowdin** as the unique choice to translate a Docusaurus site, but it is successfully used by Facebook to translate documentation projects such as [Jest](https://jestjs.io/), [Docusaurus](https://docusaurus.io/), and [ReasonML](https://reasonml.github.io/). Refer to the **[Crowdin documentation](https://support.crowdin.com/)** and **[Crowdin support](mailto:support@crowdin.com)** for help. @@ -21,7 +21,7 @@ Refer to the **[Crowdin documentation](https://support.crowdin.com/)** and **[Cr :::tip -Use this **[community-driven GitHub issue](https://github.com/facebook/docusaurus/discussions/4052)** to discuss anything related to Docusaurus + Crowdin. +Use this **[community-driven GitHub discussion](https://github.com/facebook/docusaurus/discussions/4052)** to discuss anything related to Docusaurus + Crowdin. ::: @@ -103,7 +103,7 @@ export default function Home() { Sign up on [Crowdin](https://crowdin.com/), and create a project. -Use English as source language, and French as target language. +Use English as the source language, and French as the target language. ![Create a Crowdin project with english as source language, and french as target language](/img/crowdin/crowdin-create-project.png) @@ -187,9 +187,9 @@ You should **not commit** it, and it may be a good idea to create a dedicated ** ### Install the Crowdin CLI {#install-the-crowdin-cli} -This tutorial use the CLI in version `3.5.2`, but we expect `3.x` releases to keep working. +This tutorial uses the CLI version `3.5.2`, but we expect `3.x` releases to keep working. -Install the Crowdin CLI as a NPM package to your Docusaurus site: +Install the Crowdin CLI as an NPM package to your Docusaurus site: ```bash npm2yarn npm install @crowdin/cli@3 @@ -298,13 +298,13 @@ Make sure that your website is now translated in French at `http://localhost:300 ### Automate with CI {#automate-with-ci} -We will configure the CI to **download the Crowdin translations at build time**, and keep them outside of Git. +We will configure the CI to **download the Crowdin translations at build time** and keep them outside of Git. Add `website/i18n` to `.gitignore`. Set the `CROWDIN_PERSONAL_TOKEN` env variable on your CI. -Create a npm script to `sync` Crowdin (extract sources, upload sources, download translations): +Create an npm script to `sync` Crowdin (extract sources, upload sources, download translations): ```json title="package.json" { @@ -342,17 +342,13 @@ Crowdin **does not support officially MDX**, but they added **support for the `. #### MDX problems {#mdx-problems} -Crowdin thinks the JSX syntax is embedded HTML, and can mess-up with the JSX markup when you download the translations, leading to a site that fails to build due to invalid JSX. +Crowdin thinks that the JSX syntax is embedded HTML and can mess up with the JSX markup when you download the translations, leading to a site that fails to build due to invalid JSX. -Simple JSX fragments using simple string props like `` will work fine. - -More complex JSX fragments using object/array props like `` are more likely to fail due to a syntax that does not look like HTML. +Simple JSX fragments using simple string props like `` will work fine; more complex JSX fragments using object/array props like `` are more likely to fail due to a syntax that does not look like HTML. #### MDX solutions {#mdx-solutions} -We recommend moving the complex embedded JSX code as separate standalone components. - -We also added a `mdx-code-block` escape hatch syntax: +We recommend extracting the complex embedded JSX code as separate standalone components. We also added an `mdx-code-block` escape hatch syntax: `````text # How to deploy Docusaurus @@ -454,15 +450,15 @@ Crowdin has an [In-Context localization](https://support.crowdin.com/in-context- Unfortunately, it does not work yet for technical reasons, but we have good hope it can be solved. -Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and mess-up with the frontmatter, admonitions, jsx... +Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and messes up with front matter, admonitions, JSX... ::: -### Localize edit urls {#localize-edit-urls} +### Localize edit URLs {#localize-edit-urls} When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`. -You may prefer the edit button to link to the Crowdin interface instead, and can use the `editUrl` function to customize the edit urls on a per-locale basis. +You may prefer the edit button to link to the Crowdin interface instead by using the `editUrl` function to customize the edit URLs on a per-locale basis. ```js title="docusaurus.config.js" const DefaultLocale = 'en'; diff --git a/website/docs/i18n/i18n-git.md b/website/docs/i18n/i18n-git.md index 186975a1fc..95ba9e104f 100644 --- a/website/docs/i18n/i18n-git.md +++ b/website/docs/i18n/i18n-git.md @@ -13,7 +13,7 @@ This strategy has advantages: - **Easy to get started**: just add the `i18n` folder to Git - **Easy for developers**: Git, GitHub and pull requests are mainstream developer tools - **Free** (or without any additional cost, assuming you already use Git) -- **Low friction**: does not require signing-up to an external tool +- **Low friction**: does not require signing up to an external tool - **Rewarding**: contributors are happy to have a nice contribution history Using Git also present some shortcomings: @@ -163,7 +163,7 @@ To help you maintain the JSON translation files, it is possible to run again the npm run write-translations -- --locale fr ``` -New translation will be appended, and existing ones will not be overridden. +New translations will be appended, and existing ones will not be overridden. :::tip @@ -171,7 +171,7 @@ Reset your translations with the `--override` option. ::: -### Localize edit urls {#localize-edit-urls} +### Localize edit URLs {#localize-edit-urls} When the user is browsing a page at `/fr/doc1`, the edit button will link by default to the unlocalized doc at `website/docs/doc1.md`. diff --git a/website/docs/i18n/i18n-introduction.md b/website/docs/i18n/i18n-introduction.md index 8d81d6fdac..8c137e327a 100644 --- a/website/docs/i18n/i18n-introduction.md +++ b/website/docs/i18n/i18n-introduction.md @@ -44,12 +44,12 @@ We don't provide support for: Overview of the workflow to create a translated Docusaurus website: 1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js` -1. **Translate**: put the translation files at the correct filesystem location -1. **Deploy**: build and deploy your site using a single or multi-domain strategy +2. **Translate**: put the translation files at the correct filesystem location +3. **Deploy**: build and deploy your site using a single or multi-domain strategy ### Translation files {#translation-files} -You will have to work with 2 kind of translation files. +You will work with 2 kinds of translation files. #### Markdown files {#markdown-files} @@ -83,7 +83,7 @@ The JSON format used is called **Chrome i18n**: The choice was made for 2 reasons: - **Description attribute**: to help translators with additional context -- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json) +- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json), etc. ### Translation files location {#translation-files-location} diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md index 4e4ce73ebd..dbc9eb902a 100644 --- a/website/docs/i18n/i18n-tutorial.md +++ b/website/docs/i18n/i18n-tutorial.md @@ -4,7 +4,7 @@ title: i18n - Tutorial slug: /i18n/tutorial --- -This tutorial will walk you through the basis of the **Docusaurus i18n system**. +This tutorial will walk you through the basics of the **Docusaurus i18n system**. We will add **French** translations to a **newly initialized English Docusaurus website**. @@ -70,7 +70,7 @@ Please help us complete those **[default translations](https://github.com/facebo :::caution -Each locale is a **distinct standalone single-page-application**: it is not possible to start the Docusaurus sites in all locales at the same time. +Each locale is a **distinct standalone single-page application**: it is not possible to start the Docusaurus sites in all locales at the same time. ::: @@ -203,7 +203,7 @@ Translate the `message` attribute in the JSON files of `i18n/fr`, and your site ### Translate Markdown files {#translate-markdown-files} -Official Docusaurus content plugins extensively use Markdown/MDX files, and allow you to translate them. +Official Docusaurus content plugins extensively use Markdown/MDX files and allow you to translate them. #### Translate the docs {#translate-the-docs} @@ -268,7 +268,7 @@ For localized sites, it is recommended to use **[explicit heading ids](../guides ## Deploy your site {#deploy-your-site} -You can choose to deploy your site under a **single domain**, or use **multiple (sub)domains**. +You can choose to deploy your site under a **single domain** or use **multiple (sub)domains**. ### Single-domain deployment {#single-domain-deployment} @@ -287,7 +287,7 @@ You can now [deploy](../deployment.mdx) the `build` folder to the static hosting :::note -The Docusaurus v2 website use this strategy: +The Docusaurus v2 website uses this strategy: - [https://docusaurus.io](https://docusaurus.io) - [https://docusaurus.io/fr](https://docusaurus.io/fr) @@ -296,7 +296,7 @@ The Docusaurus v2 website use this strategy: :::tip -Static hosting providers generally redirect `/unknown/urls` to `/404.html` by convention, always showing an **English 404 page**. +Static hosting providers generally redirect `/unknown/url` to `/404.html` by convention, always showing an **English 404 page**. **Localize your 404 pages** by configuring your host to redirect `/fr/*` to `/fr/404.html`. diff --git a/website/docs/installation.md b/website/docs/installation.md index dab54bb550..3bd31976ff 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -37,12 +37,16 @@ If you do not specify `name` or `template`, it will prompt you for them. We reco The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory. -**[FB-Only]:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults: +:::info FB-Only + +If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults: ```bash npx create-docusaurus@latest my-website facebook ``` +::: + If you want to skip installing dependencies, use the `--skip-install` option, like the following: ```bash @@ -59,7 +63,7 @@ npx create-docusaurus@latest my-website classic --typescript Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`: -```sh +```bash my-website ├── blog │ ├── 2019-05-28-hola.md @@ -165,4 +169,4 @@ Use new unreleased features of Docusaurus with the [`@canary` npm dist tag](/com ## Problems? {#problems} -Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus), our [Discord](https://discordapp.com/invite/docusaurus) or [Twitter](https://twitter.com/docusaurus). +Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus), our [Discord server](https://discordapp.com/invite/docusaurus), or [Twitter](https://twitter.com/docusaurus). diff --git a/website/docs/introduction.md b/website/docs/introduction.md index b56532a2f5..32c98c3f83 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -13,7 +13,7 @@ slug: / 💅 Check the **[best Docusaurus sites](/showcase?tags=favorite)** for inspiration and read some **[testimonials](https://twitter.com/sebastienlorber/timelines/1392048416872706049)**. -🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with a fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features**, but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc). +🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features** but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc). ![Docusaurus Slash Introduction](/img/slash-introducing.svg) @@ -70,45 +70,45 @@ A [lot of users](/showcase) are already using Docusaurus v2 ([trends](https://ww Docusaurus is built with high attention to the developer and contributor experience. -- ⚛️ **Built with 💚 and React** +- ⚛️ **Built with 💚 and React**: - Extend and customize with React - Gain full control of your site's browsing experience by providing your own React components -- **Pluggable** +- **Pluggable**: - Bootstrap your site with a basic template, then use advanced features and plugins - Open source your plugins to share with the community -- ✂️ **Developer experience** +- ✂️ **Developer experience**: - Start writing your docs right now - Universal configuration entry point to make it more maintainable by contributors - - Hot reloading with lightning fast incremental build on changes + - Hot reloading with lightning-fast incremental build on changes - Route-based code and data splitting - - Publish to GitHub Pages, Netlify, Vercel and other deployment services with ease + - Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease -Our shared goal — to help your users find what they need fast, and understand your products better. We share with you our best practices helping you build your doc site right and well. +Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well. -- 🎯 **SEO friendly** - - HTML files are statically generated for every possible path - - page-specific SEO to help your users land on your official docs directly relating their problems at hand -- 📝 **Powered by MDX** - - Write interactive components via JSX and React embedded in markdown - - Share your code in live editors to get your users love your products on the spot -- 🔍 **Search** - Your full site is searchable -- 💾 **Document Versioning** - Helps you keep documentation in sync with project releases. -- 🌍 **i18n** - Translate your site in multiple locales +- 🎯 **SEO friendly**: + - HTML files are statically generated for every possible path. + - Page-specific SEO to help your users land on your official docs directly relating their problems at hand. +- 📝 **Powered by MDX**: + - Write interactive components via JSX and React embedded in markdown. + - Share your code in live editors to get your users to love your products on the spot. +- 🔍 **Search**: Your full site is searchable. +- 💾 **Document Versioning**: Helps you keep documentation in sync with project releases. +- 🌍 **Internationalization (i18n)**: Translate your site in multiple locales. -Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. +Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast. -- ⚡️ **Lightning fast** - Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast -- 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users +- ⚡️ **Lightning-fast**. Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast. +- 🦖 **Accessible**. Attention to accessibility, making your site equally accessible to all users. ## Design principles {#design-principles} -- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8). -- **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with. -- **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular. -- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. -- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users. +- **Little to learn**. Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk—[Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8). +- **Intuitive**. Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with. +- **Layered architecture**. The separations of concerns between each layer of our stack (content/theming/styling) should be clear—well-abstracted and modular. +- **Sensible defaults**. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. +- **No vendor lock-in**. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users. -We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it. +We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.