mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-03 12:17:20 +02:00
docs: audit grammar issues (#6203)
* docs: audit grammar mistakes * fix code block language * revert change * let's get another
This commit is contained in:
Joshua Chen
GitHub
parent
3195e7feed
commit
73ee356949
56 changed files with 432 additions and 383 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ module.exports = {
|
|||
|
||||
## Swizzling components
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ npm swizzle @docusaurus/theme-classic [component name]
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
<!-- TODO: configuration for plugins -->
|
||||
- Type: `PluginConfig[]`
|
||||
|
||||
- Type: `any[]`
|
||||
```ts
|
||||
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
|
||||
```
|
||||
|
||||
See [plugin method references](./plugin-methods/README.md) for the shape of a `PluginModule`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [],
|
||||
plugins: [
|
||||
'docusaurus-plugin-awesome',
|
||||
['docusuarus-plugin-confetti', {fancy: false}],
|
||||
() => ({
|
||||
postBuild() {
|
||||
console.log('Build finished');
|
||||
},
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### `themes` {#themes}
|
||||
|
||||
<!-- TODO: configuration for plugins -->
|
||||
|
||||
- Type: `any[]`
|
||||
- Type: `PluginConfig[]`
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themes: [],
|
||||
themes: ['@docusaurus/theme-classic'],
|
||||
};
|
||||
```
|
||||
|
||||
### `presets` {#presets}
|
||||
|
||||
<!-- TODO: configuration for presets -->
|
||||
- Type: `PresetConfig[]`
|
||||
|
||||
- Type: `any[]`
|
||||
```ts
|
||||
type PresetConfig = string | [string, any];
|
||||
```
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 = [
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ module.exports = function (context, options) {
|
|||
|
||||
Themes using the `<Translate>` API can provide default code translation messages.
|
||||
|
||||
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site current locale.
|
||||
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site's current locale.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
|
|
@ -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<string>` {#createData}
|
||||
|
||||
A declarative callback to create static data (generally json or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
|
||||
A declarative callback to create static data (generally JSON or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
|
||||
|
||||
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
|
||||
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
|
||||
|
||||
```jsx title="website/src/components/Friends.js"
|
||||
import React from 'react';
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```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:
|
|||
|
||||
</APITable>
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type Tag = string | {label: string; permalink: string};
|
||||
|
||||
// An author key references an author from the global plugin authors.yml file
|
||||
|
|
@ -234,13 +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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```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:
|
|||
|
||||
</APITable>
|
||||
|
||||
```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
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content
|
|||
|
||||
## Initial setup {#initial-setup}
|
||||
|
||||
To setup your site's blog, start by creating a `blog` directory.
|
||||
To set up your site's blog, start by creating a `blog` directory.
|
||||
|
||||
Then, add an item link to your blog within `docusaurus.config.js`:
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ To publish in the blog, create a Markdown file within the blog directory.
|
|||
|
||||
For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`:
|
||||
|
||||
```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md"
|
||||
```md title="website/blog/2019-09-05-hello-docusaurus-v2.md"
|
||||
---
|
||||
title: Welcome Docusaurus v2
|
||||
description: This is my first post on Docusaurus 2.
|
||||
|
|
@ -59,6 +59,7 @@ tags: [hello, docusaurus-v2]
|
|||
image: https://i.imgur.com/mErPwqL.png
|
||||
hide_table_of_contents: false
|
||||
---
|
||||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
|
|
@ -72,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.
|
||||
|
||||
<details>
|
||||
<summary>Example supported patterns</summary>
|
||||
|
|
@ -104,10 +105,11 @@ The blog's index page (by default, it is at `/blog`) is the _blog list page_, wh
|
|||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
title: Truncation Example
|
||||
---
|
||||
|
||||
All these will be part of the blog post summary.
|
||||
|
||||
Even this.
|
||||
|
|
@ -121,7 +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
|
||||
<Tabs groupId="author-frontmatter">
|
||||
|
|
@ -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
|
||||
<Tabs groupId="author-frontmatter">
|
||||
|
|
@ -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`.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
|
|||
| --- | --- | --- |
|
||||
| `--port` | `3000` | Specifies the port of the dev server. |
|
||||
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
|
||||
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
|
||||
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
|
||||
| `--no-open` | `false` | Do not open automatically the page in the browser. |
|
||||
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
|
||||
|
|
@ -66,7 +66,7 @@ There are multiple ways to obtain a certificate. We will use [mkcert](https://gi
|
|||
|
||||
3. Start the app with Docusaurus HTTPS env variables:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
|
||||
```
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ npm run swizzle @docusaurus/theme-classic DocSidebar
|
|||
|
||||
Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
|
||||
|
||||
`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle <themeName>` without `componentName` lists all the components available for swizzling.
|
||||
`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle [themeName]` without `componentName` lists all the components available for swizzling.
|
||||
|
||||
#### Options {#options-2}
|
||||
|
||||
|
|
@ -149,7 +149,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
|
|||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
|
||||
| `--skip-build` | `false` | Deploy website without building it. This may be useful when using custom deploy script. |
|
||||
| `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. |
|
||||
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
|
||||
### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
|
||||
|
|
@ -181,7 +181,7 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
|
|||
| `--locale` | `<defaultLocale>` | Define which locale folder you want to write translations the JSON files in |
|
||||
| `--override` | `false` | Override existing translation messages |
|
||||
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--messagePrefix` | `''` | Allows to add a prefix to each translation message, to help you highlight untranslated strings |
|
||||
| `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings |
|
||||
|
||||
### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ A Docusaurus site is statically rendered, and it can generally work without Java
|
|||
|
||||
## Configuration {#configuration}
|
||||
|
||||
The following parameters are required in `docusaurus.config.js` in order for Docusaurus to optimize routing and serve files from the correct location:
|
||||
The following parameters are required in `docusaurus.config.js` to optimize routing and serve files from the correct location:
|
||||
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
|
|
@ -34,7 +34,7 @@ The following parameters are required in `docusaurus.config.js` in order for Doc
|
|||
|
||||
## Testing your Build Locally {#testing-build-locally}
|
||||
|
||||
It is important to test your build locally before deploying to production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
|
||||
It is important to test your build locally before deploying it for production. Docusaurus provides a [`docusaurus serve`](cli.md#docusaurus-serve-sitedir) command for that:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run serve
|
||||
|
|
@ -70,8 +70,8 @@ If you are unsure of which one to choose, ask the following questions:
|
|||
How much resource (person-hours, money) am I willing to invest in this?
|
||||
</summary>
|
||||
|
||||
- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services is almost never free, and setting up an on-site server and connecting it to the WAN can be more costly.
|
||||
- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quota even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details.
|
||||
- 🔴 Self-hosting is the hardest to set up—you would usually need an experienced person to manage this. Cloud services are almost never free, and setting up an on-site server and connecting it to the WAN can be even more costly.
|
||||
- 🟢 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quotas even for free plans that you would almost never exceed. However, it's still ultimately limited—you would need to pay once you hit the limit. Check the pricing page of your provider for details.
|
||||
- 🟡 The GitHub Pages deployment workflow can be tedious to set up. (Evidence: see the length of [Deploying to GitHub Pages](#deploying-to-github-pages)!) However, this service (including build and deployment) is always free for public repositories, and we have detailed instructions to help you make it work.
|
||||
|
||||
</details>
|
||||
|
|
@ -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=<GITHUB_USERNAME>" && yarn deploy'
|
|||
|
||||
Beginning in August 2021, GitHub requires every command-line sign-in to use the **personal access token** instead of the password. When GitHub prompts for your password, enter the PAT instead. See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for more information.
|
||||
|
||||
Alternatively, you can use SSH (`USE_SSH=true`) to login.
|
||||
Alternatively, you can use SSH (`USE_SSH=true`) to log in.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -309,7 +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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
|||
<Link to="/courses" />
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Prefer this component to vanilla `<a>` tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use `<Link>`.
|
||||
|
||||
:::
|
||||
|
||||
### `<Redirect/>` {#redirect}
|
||||
|
||||
Rendering a `<Redirect>` will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props.
|
||||
Rendering a `<Redirect>` will navigate to a new location. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to [React Router's Redirect documentation](https://reacttraining.com/react-router/web/api/Redirect) for more info on available props.
|
||||
|
||||
Example usage:
|
||||
|
||||
|
|
@ -158,11 +164,11 @@ const Home = () => {
|
|||
|
||||
### `<BrowserOnly/>` {#browseronly}
|
||||
|
||||
The `<BrowserOnly>` component permits to render React components only in the browser, after the React app has hydrated.
|
||||
The `<BrowserOnly>` component permits to render React components only in the browser after the React app has hydrated.
|
||||
|
||||
:::tip
|
||||
|
||||
Use it for integrating with code that can't run in Node.js, because `window` or `document` objects are being accessed.
|
||||
Use it for integrating with code that can't run in Node.js, because the `window` or `document` objects are being accessed.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -249,20 +255,20 @@ export default function VisitMyWebsiteMessage() {
|
|||
|
||||
When [localizing your site](./i18n/i18n-introduction.md), the `<Translate/>` component will allow providing **translation support to React components**, such as your homepage. The `<Translate>` component supports [interpolation](#interpolate).
|
||||
|
||||
The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/[locale]`.
|
||||
The translation strings will statically extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and a `code.json` translation file will be created in `website/i18n/[locale]`.
|
||||
|
||||
:::note
|
||||
|
||||
The `<Translate/>` props **must be hardcoded strings**.
|
||||
|
||||
Apart the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work.
|
||||
Apart from the `values` prop used for interpolation, it is **not possible to use variables**, or the static extraction wouldn't work.
|
||||
|
||||
:::
|
||||
|
||||
#### Props {#translate-props}
|
||||
|
||||
- `children`: untranslated string in the default site locale (can contain [interpolation placeholders](#interpolate))
|
||||
- `id`: optional value to use as key in JSON translation files
|
||||
- `id`: optional value to be used as the key in JSON translation files
|
||||
- `description`: optional text to help the translator
|
||||
- `values`: optional object containing interpolation placeholder values
|
||||
|
||||
|
|
@ -302,7 +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
|
||||
<Translate id="homepage.title" />
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<h3>Only h2 and h3 will be in the toc by default.</h3>
|
||||
<h3>Only h2 and h3 will be in the TOC by default.</h3>
|
||||
|
||||
You can configure the TOC heading levels either per-document or in the theme configuration.
|
||||
You can configure the TOC heading levels either per document or in the theme configuration.
|
||||
|
||||
The headers are well-spaced so that the hierarchy is clear.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/.
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<details>
|
||||
<summary>A real world example</summary>
|
||||
<summary>A real-world example</summary>
|
||||
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!
|
|||
</TabItem>
|
||||
<TabItem value="YAML">
|
||||
|
||||
```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';
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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';
|
|||
|
||||
<DocusaurusSvg />
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ My text
|
|||
|
||||
This `<head>` 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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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**:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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](/)
|
||||
|
||||
|
||||
```
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 (``)?
|
||||
- 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
|
|||
<details>
|
||||
<summary>How are <code>remark-math</code> and <code>rehype-katex</code> different?</summary>
|
||||
|
||||
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 `<span class="math math-inline">...</span>` 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 `<span class="math math-inline">...</span>` 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.
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -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');
|
||||
|
|
|
|||
|
|
@ -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
|
|||
<br />
|
||||
```
|
||||
|
||||
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
|
||||
<CodeBlock className="language-jsx" title="/src/myComponent">
|
||||
|
|
@ -132,7 +132,7 @@ You have to use `<CodeBlock>` 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';
|
|||
<br />
|
||||
```
|
||||
|
||||
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)).
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -132,11 +132,11 @@ It is possible to only render the default tab with `<Tabs lazy />`.
|
|||
|
||||
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 `<Tab>` 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 `<Tab>` 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
|
|||
<br/>
|
||||
```
|
||||
|
||||
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
|
||||
<Tabs groupId="operating-systems">
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -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 `<Username name="Sebastien"/>` will work fine.
|
||||
|
||||
More complex JSX fragments using object/array props like `<User person={{name: "Sebastien"}}/>` are more likely to fail due to a syntax that does not look like HTML.
|
||||
Simple JSX fragments using simple string props like `<Username name="Sebastien"/>` will work fine; more complex JSX fragments using object/array props like `<User person={{name: "Sebastien"}}/>` 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';
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
<!--
|
||||
|
||||
|
|
@ -126,23 +126,23 @@ References
|
|||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
||||
We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help you navigate through the prismatic choices out there.
|
||||
We've also studied other main static site generators and would like to share our insights on the comparison, hopefully helping you navigate through the prismatic choices out there.
|
||||
|
||||
### Gatsby {#gatsby}
|
||||
|
||||
[Gatsby](https://www.gatsbyjs.com/) is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
[Gatsby](https://www.gatsbyjs.com/) is packed with a lot of features, has a rich ecosystem of plugins, and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
|
||||
GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
|
||||
|
||||
Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
|
||||
|
||||
[Docz](https://github.com/pedronauck/docz) is a Gatsby theme to build documentation website. It is currently less featured than Docusaurus.
|
||||
[Docz](https://github.com/pedronauck/docz) is a Gatsby theme to build documentation websites. It is currently less featured than Docusaurus.
|
||||
|
||||
### Next.js {#nextjs}
|
||||
|
||||
[Next.js](https://nextjs.org/) is another very popular hybrid React framework. It can help you build a good documentation website, but it is not opinionated toward the documentation use-case, and it will require a lot more work to implement what Docusaurus provides out-of-the-box.
|
||||
|
||||
[Nextra](https://github.com/shuding/nextra) is an opinionated static-site-generator built on top of Next.js. It is currently less featured than Docusaurus.
|
||||
[Nextra](https://github.com/shuding/nextra) is an opinionated static site generator built on top of Next.js. It is currently less featured than Docusaurus.
|
||||
|
||||
### VuePress {#vuepress}
|
||||
|
||||
|
|
@ -150,9 +150,9 @@ Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and i
|
|||
|
||||
### MkDocs {#mkdocs}
|
||||
|
||||
[MkDocs](https://www.mkdocs.org/) is a popular Python static-site-generator with value proposition similar to Docusaurus.
|
||||
[MkDocs](https://www.mkdocs.org/) is a popular Python static site generator with value propositions similar to Docusaurus.
|
||||
|
||||
It is a good option if you don't need a single-page application, and don't plan to leverage React.
|
||||
It is a good option if you don't need a single-page application and don't plan to leverage React.
|
||||
|
||||
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) is a beautiful theme.
|
||||
|
||||
|
|
@ -162,7 +162,7 @@ It is a good option if you don't need a single-page application, and don't plan
|
|||
|
||||
### GitBook {#gitbook}
|
||||
|
||||
[GitBook](https://www.gitbook.com/) has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
|
||||
[GitBook](https://www.gitbook.com/) has a very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs of open source projects' documentation sites. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
|
||||
|
||||
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ Currently, GitBook is only free for open-source and non-profit teams. Docusaurus
|
|||
|
||||
[Jekyll](https://github.com/jekyll/jekyll) is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
|
||||
|
||||
In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
|
||||
In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites' performance, asset building pipeline and optimizations, and ease to set up.
|
||||
|
||||
## Staying informed {#staying-informed}
|
||||
|
||||
|
|
@ -183,4 +183,4 @@ In comparison with statically generated HTML and interactivity added using `<scr
|
|||
|
||||
If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/facebook/docusaurus) for us, or send a tweet mentioning the [@docusaurus](https://twitter.com/docusaurus) Twitter account.
|
||||
|
||||
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!
|
||||
|
|
|
|||
|
|
@ -456,7 +456,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
If you want to keep the `.html` extension as the canonical url of a page, docs can declare a `slug: installation.html` frontmatter.
|
||||
If you want to keep the `.html` extension as the canonical url of a page, docs can declare a `slug: installation.html` front matter.
|
||||
|
||||
## Components {#components}
|
||||
|
||||
|
|
@ -565,7 +565,7 @@ This feature is replaced by [inline table of content](../guides/markdown-feature
|
|||
|
||||
In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `<img>` and `<br>` which are valid in HTML would have to be explicitly closed now ( `<img/>` and `<br/>`). All tags in MDX documents have to be valid JSX.
|
||||
|
||||
Frontmatter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your frontmatter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` -> `title: Part 1: "my part1 title"`.
|
||||
Frontmatter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your front matter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` -> `title: Part 1: "my part1 title"`.
|
||||
|
||||
**Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
|
||||
|
||||
|
|
@ -589,7 +589,7 @@ The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`.
|
|||
|
||||
After migration, your folder structure should look like this:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
my-project
|
||||
├── docs
|
||||
└── website
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ While our main focus will still be helping you get your documentations right and
|
|||
|
||||
Your Docusaurus 1 site should have the following structure:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
├── docs
|
||||
└── website
|
||||
├── blog
|
||||
|
|
|
|||
|
|
@ -110,7 +110,7 @@ Unfortunately, Crowdin does not have any "Duplicate/clone Project" feature, whic
|
|||
- Download the Crowdin translations locally
|
||||
- Try to run/build your site and see if there are any errors
|
||||
|
||||
You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (frontmatter, admonition, code blocks...), and the translated md files might be invalid for the MDX parser.
|
||||
You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated md files might be invalid for the MDX parser.
|
||||
|
||||
You will have to fix all the errors until your site builds. You can do that by modifying the translated md files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`.
|
||||
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ title: Hello, World !
|
|||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The `id` frontmatter is no longer altered and will remain the same. Internally, it is set as `version-${version}/${id}`.
|
||||
Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The `id` front matter is no longer altered and will remain the same. Internally, it is set as `version-${version}/${id}`.
|
||||
|
||||
Essentially, here are the necessary changes in each versioned_docs file:
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ original_id: hello
|
|||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely to occur.
|
||||
Since we don't allow `/` in v1 & v2 for front matter, conflicts are less likely to occur.
|
||||
|
||||
So v1 users need to migrate their versioned_sidebars file
|
||||
|
||||
|
|
@ -126,7 +126,7 @@ For example, if your `versions.json` looks like this in v1
|
|||
|
||||
Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
website
|
||||
├── versioned_docs
|
||||
│ ├── version-1.1.0
|
||||
|
|
@ -139,9 +139,9 @@ website
|
|||
│ └── version-1.0.0-sidebars.json
|
||||
```
|
||||
|
||||
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right frontmatter and id reference too).
|
||||
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right front matter and id reference too).
|
||||
|
||||
```shell {3-5,12}
|
||||
```bash {3-5,12}
|
||||
website
|
||||
├── versioned_docs
|
||||
│ ├── version-1.1.0
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Presets are collections of plugins and themes.
|
|||
|
||||
## Using presets {#using-presets}
|
||||
|
||||
A preset is usually a npm package, so you install them like other npm packages using npm.
|
||||
A preset is usually an npm package, so you install them like other npm packages using npm.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save @docusaurus/preset-classic
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ This configuration file can be updated by:
|
|||
|
||||
:::caution
|
||||
|
||||
It is highly recommended using a config similar to the [**Docusaurus 2 website config**](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json).
|
||||
It is highly recommended to use a config similar to the [**Docusaurus 2 website config**](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json).
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -275,6 +275,6 @@ To use your own search, swizzle the `SearchBar` component in `@docusaurus/theme-
|
|||
npm run swizzle @docusaurus/theme-classic SearchBar
|
||||
```
|
||||
|
||||
This will create a `src/themes/SearchBar` file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own `SearchBar` component now.
|
||||
This will create an `src/themes/SearchBar` file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own `SearchBar` component now.
|
||||
|
||||
**Notes**: You can alternatively [swizzle from Algolia SearchBar](#editing-the-algolia-search-component) and create your own search component from there.
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ Docusaurus is a static site generator—HTML files are statically generated for
|
|||
|
||||
The alt tag for an image tells the search engine what the image is about, and is used when the image can't be visually seen, e.g. when using a screen reader, or when the image is broken. Alt tags are commonly supported in Markdown.
|
||||
|
||||
You may also add a title for your image—this doesn't impact SEO much, but is displayed as tooltip when hovering above the image, usually used to provide hints.
|
||||
You may also add a title for your image—this doesn't impact SEO much but is displayed as a tooltip when hovering above the image, usually used to provide hints.
|
||||
|
||||
```md
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ Docusaurus blogs support [rich search results](https://search.google.com/test/ri
|
|||
|
||||
## Robots file {#robots-file}
|
||||
|
||||
To add a `robots.txt` file that regulates search engines' behavior about which should be displayed and which shouldn't, provide it as [static asset](./static-assets.md). The following would allow access to all sub-pages from all requests:
|
||||
A `robots.txt` file regulates search engines' behavior about which should be displayed and which shouldn't. You can provide it as [static asset](./static-assets.md). The following would allow access to all sub-pages from all requests:
|
||||
|
||||
```text title="static/robots.txt"
|
||||
User-agent: *
|
||||
|
|
@ -124,4 +124,4 @@ Docusaurus uses your file names as links, but you can always change that using s
|
|||
|
||||
Search engines rely on the HTML markup such as `<h2>`, `<table>`, etc., to understand the structure of your webpage. When Docusaurus renders your pages, semantic markup, e.g. `<aside>`, `<nav>`, `<main>`, are used to divide the different sections of the page, helping the search engine to locate parts like sidebar, navbar, and the main page content.
|
||||
|
||||
Most [CommonMark](https://spec.commonmark.org/0.30/#atx-headings) syntax have their corresponding HTML tags. By using Markdown consistently in your project, you will make it easier for search engines to understand your page content.
|
||||
Most [CommonMark](https://spec.commonmark.org/0.30/#atx-headings) syntaxes have their corresponding HTML tags. By using Markdown consistently in your project, you will make it easier for search engines to understand your page content.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: static-assets
|
|||
title: Static Assets
|
||||
---
|
||||
|
||||
Every website needs assets: images, stylesheets, favicons etc. By default, you are suggested to put these assets in the `static` folder.
|
||||
Every website needs assets: images, stylesheets, favicons, etc. By default, you are suggested to put these assets in the `static` folder.
|
||||
|
||||
Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
|
||||
|
||||
|
|
@ -28,11 +28,11 @@ Now, all files in `public` as well as `static` will be copied to the build outpu
|
|||
|
||||
In JSX, you can reference assets from the `static` folder in your code using absolute paths, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `<img src="/img/docusaurus.png" />` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
|
||||
|
||||
You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
|
||||
You can `import` or `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
|
||||
|
||||
:::info
|
||||
|
||||
In Markdown, things are different: you can stick to use absolute paths because Docusaurus actually handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
|
||||
In Markdown, things are different: you can stick to using absolute paths because Docusaurus actually handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -66,6 +66,6 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
|
|||
|
||||
Keep in mind that:
|
||||
|
||||
- By default, none of the files in `static` folder will be post-processed, hashed or minified.
|
||||
- Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error.
|
||||
- By default, none of the files in the `static` folder will be post-processed, hashed, or minified.
|
||||
- Missing files referenced via hard-coded absolute paths will not be detected at compilation time and will result in a 404 error.
|
||||
- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting.
|
||||
|
|
|
|||
|
|
@ -8,19 +8,19 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
|
|||
|
||||
:::tip
|
||||
|
||||
This section discusses about styling through stylesheets. If you find yourself needing to update the DOM structure, you can refer to [swizzling](./using-themes.md#swizzling-theme-components).
|
||||
This section is focused on styling through stylesheets. If you find yourself needing to update the DOM structure, you can refer to [swizzling](./using-themes.md#swizzling-theme-components).
|
||||
|
||||
:::
|
||||
|
||||
A Docusaurus site is a single-page React application. You can style it the way you style React apps.
|
||||
|
||||
There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from a more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.
|
||||
There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.
|
||||
|
||||
## Global styles {#global-styles}
|
||||
|
||||
This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with. It works fine for small websites that do not have much customization.
|
||||
This is the most traditional way of styling that most developers (including non-front-end developers) would be familiar with. It works fine for small websites that do not have much customization.
|
||||
|
||||
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset.
|
||||
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing them as an option into the preset.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -60,7 +60,7 @@ function MyComponent() {
|
|||
|
||||
### Theme Class Names
|
||||
|
||||
We provide some predefined CSS class names to provide access for developers to style layout of a page globally in Docusaurus. The purpose is to have stable classnames shared by all themes that are meant to be targeted by custom CSS.
|
||||
We provide some predefined CSS class names for global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.
|
||||
|
||||
```mdx-code-block
|
||||
import ThemeClassNamesCode from '!!raw-loader!@site/../packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts';
|
||||
|
|
@ -78,7 +78,7 @@ import CodeBlock from '@theme/CodeBlock';
|
|||
|
||||
### Styling your site with Infima {#styling-your-site-with-infima}
|
||||
|
||||
`@docusaurus/preset-classic` uses [Infima](https://infima.dev/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://infima.dev/).
|
||||
`@docusaurus/preset-classic` uses [Infima](https://infima.dev/) as the underlying styling framework. Infima provides a flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://infima.dev/).
|
||||
|
||||
When you scaffold your Docusaurus project with `create-docusaurus`, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file.
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ Alternatively, use the following tool to generate the different shades for your
|
|||
|
||||
#### Dark Mode {#dark-mode}
|
||||
|
||||
To customize the Infima variables for dark mode you can add the following to `src/css/custom.css`.
|
||||
To customize the Infima variables for dark mode, you can add the following to `src/css/custom.css`.
|
||||
|
||||
```css title="/src/css/custom.css"
|
||||
html[data-theme='dark'] {
|
||||
|
|
@ -150,7 +150,7 @@ function MyComponent() {
|
|||
}
|
||||
```
|
||||
|
||||
The class names which will be processed by webpack into a globally unique class name during build.
|
||||
The class names will be processed by webpack into a globally unique class name during build.
|
||||
|
||||
## CSS-in-JS {#css-in-js}
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: typescript-support
|
|||
title: TypeScript Support
|
||||
---
|
||||
|
||||
Docusaurus is written in TypeScript, and provides first-class TypeScript support.
|
||||
Docusaurus is written in TypeScript and provides first-class TypeScript support.
|
||||
|
||||
## Initialization {#initialization}
|
||||
|
||||
|
|
@ -38,27 +38,24 @@ Now you can start writing TypeScript theme components.
|
|||
|
||||
## Typing the config file {#typing-config}
|
||||
|
||||
It is **not possible** to use a TypeScript config file in Docusaurus, unless you compile it yourself to JavaScript.
|
||||
It is **not possible** to use a TypeScript config file in Docusaurus unless you compile it yourself to JavaScript.
|
||||
|
||||
We recommend using [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html):
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
// highlight-next-line
|
||||
// @ts-check
|
||||
// highlight-end
|
||||
|
||||
// highlight-start
|
||||
// highlight-next-line
|
||||
/** @type {import('@docusaurus/types').Plugin} */
|
||||
// highlight-end
|
||||
function MyPlugin(context, options) {
|
||||
return {
|
||||
name: 'my-plugin',
|
||||
};
|
||||
}
|
||||
|
||||
// highlight-start
|
||||
// highlight-next-line
|
||||
/** @type {import('@docusaurus/types').Config} */
|
||||
// highlight-end
|
||||
const config = {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
|
|
@ -68,9 +65,8 @@ const config = {
|
|||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
// highlight-start
|
||||
// highlight-next-line
|
||||
/** @type {import('@docusaurus/preset-classic').Options} */
|
||||
// highlight-end
|
||||
({
|
||||
docs: {
|
||||
path: 'docs',
|
||||
|
|
@ -84,9 +80,8 @@ const config = {
|
|||
],
|
||||
],
|
||||
themeConfig:
|
||||
// highlight-start
|
||||
// highlight-next-line
|
||||
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
|
||||
// highlight-end
|
||||
({
|
||||
colorMode: {
|
||||
defaultMode: 'dark',
|
||||
|
|
@ -110,7 +105,7 @@ module.exports = config;
|
|||
|
||||
Type annotations are very useful and help your IDE understand the type of config objects!
|
||||
|
||||
The best IDEs (VSCode, WebStorm, Intellij...) will provide a nice auto-completion experience.
|
||||
The best IDEs (VSCode, WebStorm, IntelliJ...) will provide a nice auto-completion experience.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -128,7 +123,7 @@ npm run tsc
|
|||
|
||||
## Swizzling TypeScript theme components {#swizzling-typescript-theme-components}
|
||||
|
||||
For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`.
|
||||
For themes that support TypeScript theme components, you can add the `--typescript` flag to the end of the `swizzle` command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`.
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-classic Footer -- --typescript
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: using-plugins
|
|||
title: Plugins
|
||||
---
|
||||
|
||||
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via [presets](presets.md).
|
||||
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via [presets](presets.md).
|
||||
|
||||
## Available plugins {#available-plugins}
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ We maintain a [list of official plugins](./api/plugins/overview.md), but the com
|
|||
|
||||
## Installing a plugin {#installing-a-plugin}
|
||||
|
||||
A plugin is usually a npm package, so you install them like other npm packages using npm.
|
||||
A plugin is usually an npm package, so you install them like other npm packages using npm.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save docusaurus-plugin-name
|
||||
|
|
@ -115,7 +115,7 @@ At most one plugin instance can be the "default plugin instance", by omitting th
|
|||
|
||||
## Plugins design {#plugins-design}
|
||||
|
||||
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
|
||||
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.
|
||||
|
||||
## Creating plugins {#creating-plugins}
|
||||
|
||||
|
|
@ -164,7 +164,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
Then in the folder `my-plugin` you can create an index.js such as this:
|
||||
Then in the folder `my-plugin`, you can create an `index.js` such as this:
|
||||
|
||||
```js title="my-plugin.js"
|
||||
module.exports = async function myPlugin(context, options) {
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: using-themes
|
|||
title: Themes
|
||||
---
|
||||
|
||||
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.
|
||||
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on the client-side, whereas plugins are more focused on server-side functionalities. Themes are also designed to be replaceable with other themes.
|
||||
|
||||
**Themes are for providing UI components to present the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy.
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ import Navbar from '@theme/Navbar';
|
|||
The alias `@theme` can refer to a few directories, in the following priority:
|
||||
|
||||
1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
|
||||
2. A Docusaurus theme packages's `theme` directory.
|
||||
2. A Docusaurus theme package's `theme` directory.
|
||||
3. Fallback components provided by Docusaurus core (usually not needed).
|
||||
|
||||
## Swizzling theme components {#swizzling-theme-components}
|
||||
|
|
@ -97,7 +97,7 @@ As an example, to swizzle the `<Footer />` component in `@docusaurus/theme-class
|
|||
npm run swizzle @docusaurus/theme-classic Footer
|
||||
```
|
||||
|
||||
This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.
|
||||
This will copy the current `<Footer />` component used by the theme to an `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use the swizzled component in place of the original one from the theme.
|
||||
|
||||
Although we highly discourage swizzling of all components, if you wish to do that, run:
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ npm run swizzle @docusaurus/theme-classic
|
|||
|
||||
Sometimes, you just want to wrap an existing theme component with additional logic, and it can be a pain to have to maintain an almost duplicate copy of the original theme component.
|
||||
|
||||
In such case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it.
|
||||
In this case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it.
|
||||
|
||||
### For site owners {#for-site-owners}
|
||||
|
||||
|
|
@ -153,11 +153,11 @@ export default function CodeBlock(props) {
|
|||
}
|
||||
```
|
||||
|
||||
Check the code of `docusaurus-theme-live-codeblock` for details.
|
||||
Check the code of `@docusaurus/theme-live-codeblock` for details.
|
||||
|
||||
:::caution
|
||||
|
||||
Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-codeblock`), you likely don't need `@theme-init`.
|
||||
Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-c
|
|||
|
||||
<summary>How are theme aliases resolved?</summary>
|
||||
|
||||
It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup where three themes/plugins and the site itself all try to define the same component. Internally, Docusaurus loads these themes as a "stack".
|
||||
It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack".
|
||||
|
||||
```text
|
||||
+-------------------------------------------------+
|
||||
|
|
@ -181,11 +181,11 @@ It can be quite hard to wrap your mind around these aliases. Let's imagine the f
|
|||
|
||||
The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
|
||||
|
||||
`@theme/*` always points to the topmost component—when code block is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
|
||||
`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
|
||||
|
||||
`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
|
||||
|
||||
`@theme-init/*` always points to the bottommost component—usually this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
|
||||
`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -216,7 +216,7 @@ Use this component to render React Context providers and global stateful logic.
|
|||
|
||||
While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.
|
||||
|
||||
Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by a `src/theme` directory full of components.
|
||||
Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by an `src/theme` directory full of components.
|
||||
|
||||
To summarize:
|
||||
|
||||
|
|
@ -226,9 +226,9 @@ To summarize:
|
|||
|
||||
## Writing customized Docusaurus themes {#writing-customized-docusaurus-themes}
|
||||
|
||||
A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:
|
||||
A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:
|
||||
|
||||
```shell {5-7}
|
||||
```bash {5-7}
|
||||
website
|
||||
├── package.json
|
||||
└── src
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue